chromatin-accessibility-deviation-computation
Summary
Compute deviation scores that quantify how individual cells or samples deviate from the expected chromatin accessibility pattern for specific genomic annotations (motifs or kmers). This transforms sparse ATAC-seq counts into bias-corrected deviation matrices suitable for identifying annotation-accessibility associations.
When to use
When you have filtered ATAC-seq or DNAse-seq peak counts (after GC bias correction, sample filtering, and peak filtering) and wish to measure how strongly each annotation (motif or kmer) influences chromatin accessibility variability in each sample relative to a background expectation.
When NOT to use
- Input counts have not been bias-corrected with addGCBias or filtered with filterSamples/filterPeaks; computeDeviations requires preprocessed, quality-filtered input.
- Annotation matrix is already in a non-sparse, dense format unsuitable for chromVAR's internal optimization; use sparse Matrix objects.
- Goal is only clustering or dimensionality reduction without annotation interpretation; newer methods like SnapATAC outperform chromVAR for clustering tasks.
Inputs
- SummarizedExperiment with peak-by-sample counts matrix (bias-corrected, filtered for sample depth ≥1500 and in-peak fraction ≥0.15, peaks non-overlapping)
- Sparse annotation matrix (rows=peaks, columns=annotations) from matchMotifs or matchKmers
Outputs
- chromVARDeviations SummarizedExperiment object with two assays: 'deviations' (peak-annotation-by-sample deviation scores) and 'z' (z-score normalized deviations)
How to apply
Load the filtered SummarizedExperiment counts object and match annotations (motifs via matchMotifs or kmers via matchKmers) to generate a sparse annotation matrix. Pass both the counts and annotation matrix to computeDeviations, which internally computes per-annotation accessibility deviations as the difference between observed and bias-expected accessibility, producing z-scores normalized across samples. The resulting SummarizedExperiment contains two assays: deviations (raw deviation scores) and z-scores (standardized across samples); these serve as input for downstream variability, correlation, or synergy analyses. The key rationale is that deviation computation accounts for GC content bias and library size differences, enabling fair cross-sample comparisons of annotation-specific accessibility patterns.
Related tools
- chromVAR (Primary package providing computeDeviations function and SummarizedExperiment/chromVARDeviations classes) — https://github.com/GreenleafLab/chromVAR
- motifmatchr (Matches motif position weight matrices to peak sequences; produces annotation matrix input for computeDeviations) — https://github.com/GreenleafLab/motifmatchr
- BSgenome.Hsapiens.UCSC.hg19 (Provides genome sequence for kmer matching and motif matching operations)
- SummarizedExperiment (Bioconductor class for storing counts matrix, peak metadata, and sample metadata)
- Matrix (Sparse matrix representation used internally by chromVAR for efficient computation)
- BiocParallel (Optional parallelization backend; register parameter choice (SerialParam, MulticoreParam, or SnowParam) before computeDeviations)
Examples
dev <- computeDeviations(object = counts_filtered, annotations = motif_ix)
Evaluation signals
- Output object is a valid chromVARDeviations inheriting from SummarizedExperiment with exactly two assays ('deviations' and 'z')
- Deviations assay dimensions are (number_of_annotations × number_of_samples) and z-scores have mean ~0 and std ~1 within each sample
- Z-scores are centered and scaled per sample (not globally), confirming bias correction and normalization are internally applied
- All deviation and z-score values are numeric and finite (no NaN or Inf); missing values indicate failed annotation-peak matches
- Downstream variability or correlation analyses (e.g., computeVariability, getAnnotationCorrelation) on the output object execute without error and produce expected dimensions
Limitations
- computeDeviations assumes input counts are sparse and bias-corrected; dense or uncorrected input may produce misleading deviation scores.
- Deviation computation is sensitive to annotation-matching quality; low specificity in motif matching or kmer matches will introduce noise into deviation scores.
- Performance degrades with very large numbers of annotations (e.g., >50,000 kmers) or samples; batch processing or annotation subsetting may be necessary.
- Z-score normalization is per-sample; cross-sample comparisons of absolute deviations should use the raw 'deviations' assay, not 'z'.
Evidence
- [intro] computeDeviations computes bias-corrected deviations: "The function
computeDeviations returns a SummarizedExperiment with two "assays""
- [intro] deviation computation is central to annotation-variability association: "aims to identify motifs or other genomic annotations associated with variability in chromatin accessibility between individual cells or samples"
- [intro] kmer matching produces annotation input for deviations: "matchKmers(6, counts_filtered, genome=BSgenome.Hsapiens.UCSC.hg19), then compute deviations with computeDeviations(counts_filtered, kmer_ix_6mer)"
- [intro] GC bias correction is prerequisite: "The function
addGCBias returns an updated SummarizedExperiment with a new rowData column named "bias""
- [intro] Sample and peak filtering are prerequisites: "it is advisable to filter out samples with insufficient reads using filterSamples"
1---2name: chromatin-accessibility-deviation-computation3description: Use when when you have filtered ATAC-seq or DNAse-seq peak counts (after GC bias correction, sample filtering, and peak filtering) and wish to measure how strongly each annotation (motif or kmer) influences chromatin accessibility variability in each sample relative to a background expectation.4license: CC-BY-4.05---67# chromatin-accessibility-deviation-computation89## Summary1011Compute deviation scores that quantify how individual cells or samples deviate from the expected chromatin accessibility pattern for specific genomic annotations (motifs or kmers). This transforms sparse ATAC-seq counts into bias-corrected deviation matrices suitable for identifying annotation-accessibility associations.1213## When to use1415When you have filtered ATAC-seq or DNAse-seq peak counts (after GC bias correction, sample filtering, and peak filtering) and wish to measure how strongly each annotation (motif or kmer) influences chromatin accessibility variability in each sample relative to a background expectation.1617## When NOT to use1819- Input counts have not been bias-corrected with addGCBias or filtered with filterSamples/filterPeaks; computeDeviations requires preprocessed, quality-filtered input.20- Annotation matrix is already in a non-sparse, dense format unsuitable for chromVAR's internal optimization; use sparse Matrix objects.21- Goal is only clustering or dimensionality reduction without annotation interpretation; newer methods like SnapATAC outperform chromVAR for clustering tasks.2223## Inputs2425- SummarizedExperiment with peak-by-sample counts matrix (bias-corrected, filtered for sample depth ≥1500 and in-peak fraction ≥0.15, peaks non-overlapping)26- Sparse annotation matrix (rows=peaks, columns=annotations) from matchMotifs or matchKmers2728## Outputs2930- chromVARDeviations SummarizedExperiment object with two assays: 'deviations' (peak-annotation-by-sample deviation scores) and 'z' (z-score normalized deviations)3132## How to apply3334Load the filtered SummarizedExperiment counts object and match annotations (motifs via matchMotifs or kmers via matchKmers) to generate a sparse annotation matrix. Pass both the counts and annotation matrix to computeDeviations, which internally computes per-annotation accessibility deviations as the difference between observed and bias-expected accessibility, producing z-scores normalized across samples. The resulting SummarizedExperiment contains two assays: deviations (raw deviation scores) and z-scores (standardized across samples); these serve as input for downstream variability, correlation, or synergy analyses. The key rationale is that deviation computation accounts for GC content bias and library size differences, enabling fair cross-sample comparisons of annotation-specific accessibility patterns.3536## Related tools3738- **chromVAR** (Primary package providing computeDeviations function and SummarizedExperiment/chromVARDeviations classes) — https://github.com/GreenleafLab/chromVAR39- **motifmatchr** (Matches motif position weight matrices to peak sequences; produces annotation matrix input for computeDeviations) — https://github.com/GreenleafLab/motifmatchr40- **BSgenome.Hsapiens.UCSC.hg19** (Provides genome sequence for kmer matching and motif matching operations)41- **SummarizedExperiment** (Bioconductor class for storing counts matrix, peak metadata, and sample metadata)42- **Matrix** (Sparse matrix representation used internally by chromVAR for efficient computation)43- **BiocParallel** (Optional parallelization backend; register parameter choice (SerialParam, MulticoreParam, or SnowParam) before computeDeviations)4445## Examples4647```48dev <- computeDeviations(object = counts_filtered, annotations = motif_ix)49```5051## Evaluation signals5253- Output object is a valid chromVARDeviations inheriting from SummarizedExperiment with exactly two assays ('deviations' and 'z')54- Deviations assay dimensions are (number_of_annotations × number_of_samples) and z-scores have mean ~0 and std ~1 within each sample55- Z-scores are centered and scaled per sample (not globally), confirming bias correction and normalization are internally applied56- All deviation and z-score values are numeric and finite (no NaN or Inf); missing values indicate failed annotation-peak matches57- Downstream variability or correlation analyses (e.g., computeVariability, getAnnotationCorrelation) on the output object execute without error and produce expected dimensions5859## Limitations6061- computeDeviations assumes input counts are sparse and bias-corrected; dense or uncorrected input may produce misleading deviation scores.62- Deviation computation is sensitive to annotation-matching quality; low specificity in motif matching or kmer matches will introduce noise into deviation scores.63- Performance degrades with very large numbers of annotations (e.g., >50,000 kmers) or samples; batch processing or annotation subsetting may be necessary.64- Z-score normalization is per-sample; cross-sample comparisons of absolute deviations should use the raw 'deviations' assay, not 'z'.6566## Evidence6768- [intro] computeDeviations computes bias-corrected deviations: "The function `computeDeviations` returns a SummarizedExperiment with two "assays""69- [intro] deviation computation is central to annotation-variability association: "aims to identify motifs or other genomic annotations associated with variability in chromatin accessibility between individual cells or samples"70- [intro] kmer matching produces annotation input for deviations: "matchKmers(6, counts_filtered, genome=BSgenome.Hsapiens.UCSC.hg19), then compute deviations with computeDeviations(counts_filtered, kmer_ix_6mer)"71- [intro] GC bias correction is prerequisite: "The function `addGCBias` returns an updated SummarizedExperiment with a new rowData column named "bias""72- [intro] Sample and peak filtering are prerequisites: "it is advisable to filter out samples with insufficient reads using filterSamples"
HolobiomicsLab