# Motif Database Query And Matching

> Use when you have a set of differentially accessible peaks (output from differential accessibility testing, e.g., tl.

- Skill: `holobiomicslab/motif-database-query-and-matching` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/motif-database-query-and-matching`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/motif-database-query-and-matching/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/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"