Motif database query and matching

motif-database-query-and-matching

Summary

Query a curated motif database (e.g., CIS-BP) and match motif position-weight matrices (PWMs) against a set of DNA sequences (typically differentially accessible peaks from single-cell ATAC-seq). This skill produces motif occurrence calls and enrichment statistics that identify transcription factor binding sites overrepresented in the input peak set.

When to use

You have a set of differentially accessible peaks (output from differential accessibility testing, e.g., tl.diff_test) from single-cell ATAC-seq data and want to identify which transcription factor motifs are overrepresented in those peaks relative to a background model, to infer regulatory drivers of chromatin accessibility changes.

When NOT to use

• Input peaks have not been validated for reproducibility or consistency; enrichment results on noisy peak sets will be unreliable.
• Background model or motif database is not appropriate for the organism or cell type (e.g., using a vertebrate motif database on plant ATAC-seq data).
• You are interested only in de novo motif discovery rather than matching against known databases.

Inputs

• Differentially accessible peak set (BED-like format or genomic interval set)
• Motif position-weight matrix (PWM) library from CIS-BP or equivalent curated database

Outputs

• Motif enrichment table (columns: motif ID, TF name, enrichment score, p-value, q-value)
• Peak-motif match annotation (which motifs occur in which peaks)

How to apply

Load differentially accessible peaks as a feature set into SnapATAC2. Retrieve motif position-weight matrices from a curated motif database (datasets.cis_bp provides the CIS-BP dataset). Invoke tl.motif_enrichment on the peak set; the function scans for motif occurrences within the differential regions and computes enrichment statistics (typically log-odds ratios or similar) against a background model. Validate the output motif enrichment table for required columns (motif IDs, enrichment scores, p-values), non-null values, and statistical significance thresholds (typically p < 0.05). The resulting table ranks motifs by overrepresentation, allowing prioritization of candidate regulatory transcription factors.

Related tools

• SnapATAC2 (Provides tl.motif_enrichment function, datasets.cis_bp database loader, and integration with tl.diff_test for differential peak analysis) — https://github.com/scverse/SnapATAC2
• tl.motif_enrichment (Core function that performs motif occurrence scanning and enrichment statistic computation against background model) — https://github.com/scverse/SnapATAC2
• datasets.cis_bp (Loads CIS-BP motif database with position-weight matrices and motif definitions) — https://github.com/scverse/SnapATAC2
• tl.diff_test (Identifies differentially accessible peaks that serve as input to motif enrichment) — https://github.com/scverse/SnapATAC2

Examples

import snapatac2 as snap; peaks = snap.tl.diff_test(adata, groupby='cell_type'); motifs = snap.datasets.cis_bp(); enrichment = snap.tl.motif_enrichment(peaks, motif_matrix=motifs)

Evaluation signals

• Motif enrichment table contains all expected columns (motif ID, enrichment score, p-value) with non-null values.
• P-values are in valid range [0, 1] and reflect expected statistical distribution under null hypothesis.
• Top-ranked motifs correspond to known regulators of chromatin accessibility in the cell type or biological context (literature validation).
• Enrichment scores are interpretable (e.g., log-odds ratio or z-score) and correlate with motif frequency in the peak set.
• Results are reproducible across independent runs and consistent with complementary differential analysis (e.g., tl.marker_regions on the same peaks).

Limitations

• Motif enrichment depends on quality and completeness of the reference PWM database; missing or poorly-annotated motifs will not be detected.
• Background model assumptions (e.g., uniform nucleotide distribution, motif independence) may not hold for all genomic regions; peak set-specific background may yield different results.
• Motif matching is sequence-based only; does not account for chromatin accessibility, cofactor binding, or 3D chromatin structure that may modulate actual TF occupancy.
• Multiple hypothesis testing correction (q-value computation) assumes independence of motif tests, which may be violated for similar or degenerate motif PWMs.

Evidence

• [other] Load the CIS-BP motif database using datasets.cis_bp to obtain motif definitions and position-weight matrices: "Load the CIS-BP motif database using datasets.cis_bp to obtain motif definitions and position-weight matrices."
• [other] Invoke tl.motif_enrichment on the peak set, scanning for motif occurrences within differential regions and computing enrichment statistics: "Invoke tl.motif_enrichment on the peak set, scanning for motif occurrences within differential regions and computing enrichment statistics against a background model."
• [other] Retrieve the resulting motif enrichment table containing motif IDs, enrichment scores, and p-values: "Retrieve the resulting motif enrichment table containing motif IDs, enrichment scores, and p-values."
• [methods] tl.motif_enrichment for motif analysis: "tl.motif_enrichment for motif analysis"
• [readme] End-to-end analysis pipeline for single-cell ATAC-seq data, including preprocessing, dimension reduction, clustering, data integration, peak calling, differential analysis, motif analysis, regulatory network analysis: "End-to-end analysis pipeline for single-cell ATAC-seq data, including preprocessing, dimension reduction, clustering, data integration, peak calling, differential analysis, motif analysis, regulatory"