motif-annotation-correlation-analysis
Summary
Quantify redundancy and synergy between pairs of genomic annotation sets (e.g., motifs and kmers) in chromatin accessibility data using correlation and synergy metrics. This skill identifies which annotation pairs co-occur by chance versus providing complementary information about chromatin variability.
When to use
Use this skill when you have a chromVARDeviations object with multiple annotation sets (such as JASPAR motifs and kmers) and need to determine which annotation pairs are redundant (high correlation) versus synergistic (high synergy z-scores). Typical triggers include comparing motif-based annotations to sequence-based features, or evaluating whether adding a second annotation set provides independent information beyond an existing set.
When NOT to use
- Annotations from a single set only (correlation and synergy require at least two sets)
- Raw fragment count matrices that have not undergone bias correction and deviation computation
- Data in which peaks have not been pre-filtered for non-overlapping regions and sufficient quality
Inputs
- chromVARDeviations object with precomputed bias-corrected deviations and z-scores
- Annotation matrix with named rows (peaks/regions) and columns (annotation identifiers)
- Two subsets of annotation indices (e.g., motif_ix, kmer_ix) defining the annotation sets to compare
Outputs
- Correlation matrix (named rows and columns) as CSV file
- Synergy scores table (annotation pair names, z-scores, p-values) as CSV file
How to apply
Load a chromVARDeviations object containing precomputed bias-corrected deviations and z-scores. Subset the annotation matrix to the two annotation sets of interest by selecting their respective column indices (e.g., motif_ix columns and kmer_ix columns). Apply getAnnotationCorrelation to compute pairwise Pearson correlations between the annotation sets across all samples, producing a correlation matrix with named rows and columns indicating annotation pairs. Apply getAnnotationSynergy to compute z-scores that compare observed variance for peaks containing both annotations against a random subsample of peaks with only the higher-variability annotation. The synergy z-score indicates whether the paired annotations explain more variance together than expected by chance. Export both the correlation matrix and synergy scores (z-scores and p-values) as CSV files with preserved headers for downstream interpretation.
Related tools
- chromVAR (Core package providing getAnnotationCorrelation and getAnnotationSynergy functions for computing redundancy and synergy metrics between annotation sets) — https://github.com/GreenleafLab/chromVAR
- SummarizedExperiment (R/Bioconductor class used to structure the chromVARDeviations object and organize annotations, samples, and assays)
- Matrix (R package providing sparse matrix operations for efficient handling of large annotation matrices)
- motifmatchr (Used upstream to match motifs to peaks and produce motif annotation indices input to this workflow) — https://github.com/GreenleafLab/motifmatchr
Examples
# After loading chromVARDeviations object 'dev' with motif and kmer annotations
corr_matrix <- getAnnotationCorrelation(dev[, c(motif_ix_cols, kmer_ix_cols)])
synergy_scores <- getAnnotationSynergy(dev, annotation_ix = c(motif_ix_cols, kmer_ix_cols))
write.csv(corr_matrix, 'annotation_correlations.csv', row.names=TRUE, col.names=TRUE)
write.csv(synergy_scores, 'annotation_synergy.csv', row.names=FALSE)
Evaluation signals
- Correlation matrix is symmetric (cij = cji), contains values between -1 and 1, and has row and column names matching input annotation identifiers
- Synergy z-scores and p-values are properly computed; positive z-scores indicate synergy (non-redundant information), while negative or near-zero z-scores indicate redundancy
- CSV exports contain preserved headers with annotation pair names clearly identifying which two sets were compared
- No NaN or infinite values in correlation or synergy outputs; missing values indicate insufficient peaks meeting the comparison criteria
- Synergy computation uses random subsampling of the higher-variability annotation set, so results are reproducible only with fixed random seed
Limitations
- Synergy z-scores depend on the size and composition of random subsamples; results may vary between runs unless random seed is fixed
- Requires that both annotation sets are already present and properly indexed in the chromVARDeviations object; filtering to non-overlapping peaks must be performed upstream
- Correlation and synergy metrics are sensitive to the quality and completeness of deviation computation; biased or incomplete bias correction will inflate or deflate both metrics
- The synergy metric assumes that the higher-variability annotation set is the reference; swapping which set is treated as reference may alter interpretation
Evidence
- [other] chromVAR provides functions to identify motifs or other genomic annotations associated with variability in chromatin accessibility between individual cells or samples: "chromVAR provides functions to identify motifs or other genomic annotations associated with variability in chromatin accessibility between individual cells or samples"
- [other] getAnnotationCorrelation computes pairwise Pearson correlations between annotation sets: "Apply getAnnotationCorrelation to compute pairwise Pearson correlations between the two annotation sets across all samples, outputting a correlation matrix with named rows and columns"
- [other] getAnnotationSynergy computes z-scores for variability synergy by comparing observed variance for peaks containing both annotations against a random subsample: "Apply getAnnotationSynergy to compute z-scores for variability synergy, comparing the observed variance for peaks containing both annotations against a random subsample of peaks with only the"
- [other] Load the chromVARDeviations object containing precomputed bias-corrected deviations and z-scores: "Load the chromVARDeviations object containing precomputed bias-corrected deviations and z-scores for the annotation set"
- [other] Subset annotation matrix and export results as CSV files with headers preserved: "Export the correlation matrix as a named CSV file with row and column headers preserved, and the synergy scores as a second CSV file with annotation pair names, synergy z-scores, and p-values"
1---2name: motif-annotation-correlation-analysis3description: Use when you have a chromVARDeviations object with multiple annotation sets (such as JASPAR motifs and kmers) and need to determine which annotation pairs are redundant (high correlation) versus synergistic (high synergy z-scores).4license: CC-BY-4.05---67# motif-annotation-correlation-analysis89## Summary1011Quantify redundancy and synergy between pairs of genomic annotation sets (e.g., motifs and kmers) in chromatin accessibility data using correlation and synergy metrics. This skill identifies which annotation pairs co-occur by chance versus providing complementary information about chromatin variability.1213## When to use1415Use this skill when you have a chromVARDeviations object with multiple annotation sets (such as JASPAR motifs and kmers) and need to determine which annotation pairs are redundant (high correlation) versus synergistic (high synergy z-scores). Typical triggers include comparing motif-based annotations to sequence-based features, or evaluating whether adding a second annotation set provides independent information beyond an existing set.1617## When NOT to use1819- Annotations from a single set only (correlation and synergy require at least two sets)20- Raw fragment count matrices that have not undergone bias correction and deviation computation21- Data in which peaks have not been pre-filtered for non-overlapping regions and sufficient quality2223## Inputs2425- chromVARDeviations object with precomputed bias-corrected deviations and z-scores26- Annotation matrix with named rows (peaks/regions) and columns (annotation identifiers)27- Two subsets of annotation indices (e.g., motif_ix, kmer_ix) defining the annotation sets to compare2829## Outputs3031- Correlation matrix (named rows and columns) as CSV file32- Synergy scores table (annotation pair names, z-scores, p-values) as CSV file3334## How to apply3536Load a chromVARDeviations object containing precomputed bias-corrected deviations and z-scores. Subset the annotation matrix to the two annotation sets of interest by selecting their respective column indices (e.g., motif_ix columns and kmer_ix columns). Apply getAnnotationCorrelation to compute pairwise Pearson correlations between the annotation sets across all samples, producing a correlation matrix with named rows and columns indicating annotation pairs. Apply getAnnotationSynergy to compute z-scores that compare observed variance for peaks containing both annotations against a random subsample of peaks with only the higher-variability annotation. The synergy z-score indicates whether the paired annotations explain more variance together than expected by chance. Export both the correlation matrix and synergy scores (z-scores and p-values) as CSV files with preserved headers for downstream interpretation.3738## Related tools3940- **chromVAR** (Core package providing getAnnotationCorrelation and getAnnotationSynergy functions for computing redundancy and synergy metrics between annotation sets) — https://github.com/GreenleafLab/chromVAR41- **SummarizedExperiment** (R/Bioconductor class used to structure the chromVARDeviations object and organize annotations, samples, and assays)42- **Matrix** (R package providing sparse matrix operations for efficient handling of large annotation matrices)43- **motifmatchr** (Used upstream to match motifs to peaks and produce motif annotation indices input to this workflow) — https://github.com/GreenleafLab/motifmatchr4445## Examples4647```48# After loading chromVARDeviations object 'dev' with motif and kmer annotations49corr_matrix <- getAnnotationCorrelation(dev[, c(motif_ix_cols, kmer_ix_cols)])50synergy_scores <- getAnnotationSynergy(dev, annotation_ix = c(motif_ix_cols, kmer_ix_cols))51write.csv(corr_matrix, 'annotation_correlations.csv', row.names=TRUE, col.names=TRUE)52write.csv(synergy_scores, 'annotation_synergy.csv', row.names=FALSE)53```5455## Evaluation signals5657- Correlation matrix is symmetric (cij = cji), contains values between -1 and 1, and has row and column names matching input annotation identifiers58- Synergy z-scores and p-values are properly computed; positive z-scores indicate synergy (non-redundant information), while negative or near-zero z-scores indicate redundancy59- CSV exports contain preserved headers with annotation pair names clearly identifying which two sets were compared60- No NaN or infinite values in correlation or synergy outputs; missing values indicate insufficient peaks meeting the comparison criteria61- Synergy computation uses random subsampling of the higher-variability annotation set, so results are reproducible only with fixed random seed6263## Limitations6465- Synergy z-scores depend on the size and composition of random subsamples; results may vary between runs unless random seed is fixed66- Requires that both annotation sets are already present and properly indexed in the chromVARDeviations object; filtering to non-overlapping peaks must be performed upstream67- Correlation and synergy metrics are sensitive to the quality and completeness of deviation computation; biased or incomplete bias correction will inflate or deflate both metrics68- The synergy metric assumes that the higher-variability annotation set is the reference; swapping which set is treated as reference may alter interpretation6970## Evidence7172- [other] chromVAR provides functions to identify motifs or other genomic annotations associated with variability in chromatin accessibility between individual cells or samples: "chromVAR provides functions to identify motifs or other genomic annotations associated with variability in chromatin accessibility between individual cells or samples"73- [other] getAnnotationCorrelation computes pairwise Pearson correlations between annotation sets: "Apply getAnnotationCorrelation to compute pairwise Pearson correlations between the two annotation sets across all samples, outputting a correlation matrix with named rows and columns"74- [other] getAnnotationSynergy computes z-scores for variability synergy by comparing observed variance for peaks containing both annotations against a random subsample: "Apply getAnnotationSynergy to compute z-scores for variability synergy, comparing the observed variance for peaks containing both annotations against a random subsample of peaks with only the"75- [other] Load the chromVARDeviations object containing precomputed bias-corrected deviations and z-scores: "Load the chromVARDeviations object containing precomputed bias-corrected deviations and z-scores for the annotation set"76- [other] Subset annotation matrix and export results as CSV files with headers preserved: "Export the correlation matrix as a named CSV file with row and column headers preserved, and the synergy scores as a second CSV file with annotation pair names, synergy z-scores, and p-values"
HolobiomicsLab 