# Kmer Annotation Matrix Assembly

> Use when you have filtered peak counts from ATAC or DNase-seq data (with GC bias correction and sample/peak filtering applied) and want to annotate peaks by k-mer content rather than known transcription factor motifs—particularly when comparing how k-mer size affects the magnitude of chromatin.

- Skill: `holobiomicslab/kmer-annotation-matrix-assembly` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/kmer-annotation-matrix-assembly`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/kmer-annotation-matrix-assembly/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/kmer-annotation-matrix-assembly

---


# kmer-annotation-matrix-assembly

## Summary

Generate k-mer annotation matrices that map short DNA sequence motifs (6-mers or 7-mers) to peaks in chromatin accessibility data, enabling subsequent deviation and variability scoring in chromVAR workflows. This is a prerequisite for motif-agnostic annotation of chromatin accessibility variability.

## When to use

You have filtered peak counts from ATAC or DNase-seq data (with GC bias correction and sample/peak filtering applied) and want to annotate peaks by k-mer content rather than known transcription factor motifs—particularly when comparing how k-mer size affects the magnitude of chromatin accessibility variability scores.

## When NOT to use

- You already have known transcription factor motif annotations and want to use matched motifs instead of k-mers.
- Your peak set contains overlapping peaks—apply filterPeaks() first to remove overlaps before k-mer annotation.
- You lack a reference genome object appropriate for your organism and assembly.

## Inputs

- SummarizedExperiment counts object (filtered, GC-bias corrected, with min_depth ≥ 1500 and min_in_peaks ≥ 0.15)
- Reference genome object (BSgenome, e.g., BSgenome.Hsapiens.UCSC.hg19)
- k-mer length integer (e.g., 6 or 7)

## Outputs

- Sparse binary matrix of k-mer annotations (rows = k-mers, columns = peaks)
- chromVAR kmer_ix object suitable for input to computeDeviations()

## How to apply

Load the filtered SummarizedExperiment counts object and call matchKmers() with the desired k-mer length (6, 7, or other integer) and a reference genome (e.g., BSgenome.Hsapiens.UCSC.hg19). The function returns a sparse binary matrix where rows are k-mers and columns are peaks, with 1 indicating presence of that k-mer in the peak sequence. Repeat for multiple k-mer sizes if performing comparative analysis (e.g., 6-mers vs. 7-mers) to assess how motif granularity affects downstream deviation computation and variability scoring. The resulting annotation matrix is then passed directly to computeDeviations() for deviation scoring.

## Related tools

- **chromVAR** (Main package providing matchKmers() and computeDeviations() functions for k-mer annotation and deviation scoring) — https://github.com/GreenleafLab/chromVAR
- **motifmatchr** (Dependency providing sequence-matching infrastructure used by matchKmers()) — https://github.com/GreenleafLab/motifmatchr
- **BSgenome.Hsapiens.UCSC.hg19** (Reference genome object required as input to matchKmers() for sequence lookup)
- **SummarizedExperiment** (Data structure class for storing counts and peak metadata)
- **BiocParallel** (Optional parallelization framework for faster k-mer matching on large peak sets)

## Examples

```
kmer_ix_6mer <- matchKmers(6, counts_filtered, genome=BSgenome.Hsapiens.UCSC.hg19)
kmer_ix_7mer <- matchKmers(7, counts_filtered, genome=BSgenome.Hsapiens.UCSC.hg19)
```

## Evaluation signals

- Resulting annotation matrix is sparse (not dense) and has dimensions: number of unique k-mers (rows) × number of peaks (columns).
- Matrix contains only binary values (0 or 1), indicating k-mer presence/absence in each peak.
- For a given k-mer size, the number of unique k-mers should be consistent with sequence diversity (7-mers will have up to 4^7 = 16,384 possible values; 6-mers up to 4^6 = 4,096).
- Downstream computeDeviations() runs without error and produces a deviation object with matching dimensions.
- Variability scores computed on 7-mer annotations are higher in magnitude (mean/median/std dev) than those from 6-mers, confirming expected granularity effect.

## Limitations

- matchKmers() requires a pre-filtered, non-overlapping peak set; overlapping peaks must be removed by filterPeaks() beforehand.
- k-mer matching is sequence-based only and does not account for TF binding affinity or biological context; consider complementing with motif-based approaches for functional interpretation.
- Larger k-mer sizes (e.g., 8-mers) generate increasingly sparse matrices and may reduce statistical power if peak sets are small.
- The choice of reference genome assembly is critical; mismatched assemblies will result in incorrect or missing k-mer matches.

## Evidence

- [other] Generate 6-mer kmer annotation matrix using matchKmers(6, counts_filtered, genome=BSgenome.Hsapiens.UCSC.hg19): "Generate 6-mer kmer annotation matrix using matchKmers(6, counts_filtered, genome=BSgenome.Hsapiens.UCSC.hg19)"
- [readme] Using kmers + PCA appears to be the best variant of chromVAR for clustering: "Using kmers + PCA appears to be the best variant of chromVAR for clustering"
- [other] chromVAR supports kmer-based annotation approaches as a viable method for analyzing chromatin accessibility variability: "chromVAR supports kmer-based annotation approaches as a viable method for analyzing chromatin accessibility variability, with kmers being suitable for deviation computation workflows"
- [readme] The function `matchMotifs` from the motifmatchr package finds which peaks contain which motifs: "The function `matchMotifs` from the motifmatchr package finds which peaks contain which motifs"