motif-annotation-correlation-analysis

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.