TF-MINDI: Transcription Factor Motif Instance Neighborhood Decomposition and Interpretation

TF-MINDI: Transcription Factor Motif Instance Neighborhood Decomposition and Interpretation#

Tests Documentation

TF-MINDI is a Python package for analyzing transcription factor binding patterns from deep learning model attribution scores. It identifies and clusters sequence motifs from contribution scores, maps them to transcription factor families, and provides visualization tools for regulatory genomics analysis.

Getting Started#

See the tutorials and the API documentation.

Key Features#

  • Seqlet Extraction: Identifies important sequence regions from contribution scores with a choice of seqlet callers (recursive, hysteresis, local-contrast, wavelet-Otsu, finemo)

  • Motif Similarity Analysis: Compares extracted seqlets to known motif databases using TomTom

  • TF Family Annotation: Projects seqlets into a reference motif space and assigns them a TF family

  • Clustering & Dimensionality Reduction: Groups similar seqlets using Leiden clustering and t-SNE visualization

  • Pattern Generation: Creates consensus motifs from clustered seqlets with alignment

  • Visualization: Region-level contribution plots, t-SNE embeddings, motif logos, and heatmaps

Installation#

tfmindi requires Python 3.12 and Linux.

pip install tfmindi          # CPU
pip install tfmindi[gpu]     # GPU, CUDA 12.x -- recommended

GPU Acceleration#

Every heavy step runs on the GPU when one is available: TomTom motif similarity, PCA, the neighborhood graph, t-SNE, Leiden clustering, and the TF-family kNN projection. On a genome-scale run this is 6x-7x end to end compared to the cpu version.

The backend is auto-detected. Override it with tm.set_backend("cpu"/"gpu") or the TFMINDI_BACKEND environment variable. Every accelerated step falls back to its CPU implementation with a warning if the GPU path fails, so a run never breaks on a GPU problem.

If tfmindi can’t find your GPU, import rapids_singlecell directly and see what errors you get. You may have to set LD_LIBRARY_PATH for cuml as described here.

Quick Start#

TF-MINDI follows a scanpy-inspired workflow: tm.pp (preprocess) → tm.tl (analyze) → tm.pl (plot), with a single AnnData carrying state between steps.

import tfmindi as tm

# --- Preprocessing: seqlets -> motif similarity -> AnnData ---
collection = tm.MotifCollectionData("mcv11.refdata.tar.gz")
motifs = collection.get_motifs(20)  # 20 motifs per reference cluster

# contrib and oh are (n_regions, 4, region_width) arrays
seqlets_df, seqlet_matrices = tm.pp.extract_seqlets(contrib=contrib, oh=oh, threshold=0.05)
sim_matrix = tm.pp.calculate_motif_similarity(seqlet_matrices, motifs)
adata = tm.pp.create_seqlet_adata(
    sim_matrix,
    seqlets_df,
    oh_sequences=oh,
    contrib_scores=contrib,
    motif_collection=motifs,
)

# --- Tools: annotate, cluster, build consensus patterns ---
tm.tl.predict_tf_family_seqlets(adata, collection, cluster_resolution=5.0, n_motifs_per_reference_cluster=20)
tm.tl.embed_and_cluster(adata, resolution=2.5)
patterns = tm.tl.create_patterns(adata, annotation_col="predicted_5.0_predicted_family")

# --- Plotting ---
tm.pl.tsne(adata, color_by="predicted_5.0_predicted_family")
tm.pl.pattern_logos(patterns)
tm.pl.region_contributions(adata, annotation_col="predicted_5.0_predicted_family", example_idx=0)

tm.save_h5ad(adata, "seqlets.h5ad")  # use these, not adata.write_h5ad

Release Notes#

See the changelog.

Contact#

If you found a bug, please use the issue tracker.

Citation#