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"