sparse-matrix-subset-indexing

sparse-matrix-subset-indexing

Summary

Subset annotation matrices within chromVAR Deviations objects by selecting specific rows (annotation sets) or columns (samples) using standard R indexing to isolate feature pairs of interest before computing correlation or synergy metrics. This is a foundational data manipulation step that preserves sparsity and enables targeted pairwise annotation analysis.

When to use

When you have a chromVARDeviations object with multiple annotation sets (e.g., JASPAR motif indices and kmer indices) and you need to isolate two specific annotation sets for correlation or synergy computation, or when you wish to exclude low-quality or irrelevant samples before annotation relationship analysis.

When NOT to use

• Input annotation matrix is already filtered to a single annotation set or fewer than two sets (nothing to subset).
• Performing whole-matrix analysis intended to compare all annotation pairs simultaneously; subsetting prematurely may exclude relevant cross-set comparisons.
• Working with a dense matrix representation; sparse subsetting assumes sparse Matrix format to preserve efficiency.

Inputs

• chromVARDeviations object with annotation matrix (assay)
• Column/row indices or names identifying the two annotation sets of interest

Outputs

• Subsetted sparse matrix of annotations (typically Matrix::dgCMatrix or similar)
• Annotation pair identifiers (e.g., motif_ix and kmer_ix column names)

How to apply

Load the chromVARDeviations object containing precomputed bias-corrected deviations and z-scores. Identify the column indices (or names) corresponding to the two annotation sets of interest in the annotation matrix—for example, motif_ix columns for JASPAR motifs and kmer_ix columns for kmers. Use standard R matrix subsetting syntax (e.g., annotations[, c(motif_cols, kmer_cols)] or by named column selection) to extract the subset. Verify that the resulting matrix retains the sparse Matrix format to avoid memory overhead. The subsetted matrix then serves as input to downstream functions like getAnnotationCorrelation or getAnnotationSynergy, which operate on pairs of annotations across all retained samples.