compartment-strength-quantification

compartment-strength-quantification

Summary

Quantify the asymmetry of A/B compartment interactions in Hi-C contact matrices by computing saddle strength—a scalar metric derived from a 2D saddle matrix aggregating contact frequency by digitized eigenvector compartment pairs. This metric summarizes the degree to which the genome is partitioned into spatially segregated A and B compartments.

When to use

When you have a binned Hi-C cooler file, an associated eigenvector track (from prior eigs_cis calculation), and need to measure how strongly the genome is partitioned into active (A) and inactive (B) compartments. Use this skill to produce a single scalar metric that quantifies compartment interaction asymmetry across a chromosome or genome, enabling comparison of compartmentalization strength across cell types, conditions, or timepoints.

When NOT to use

• The input eigenvector track has not been validated or is from a different resolution/genome version than the cooler file—compartment calls must be derived from the same contact matrix.
• The cooler file contains fewer than ~5 kb resolution bins or has severe sparsity in high-interaction regions; saddle matrices require sufficient contact counts per bin pair to estimate meaningful interaction frequencies.
• You need strand-level or allele-specific compartment strength; saddle analysis aggregates across the entire input track and does not decompose by strand or haplotype.

Inputs

• cooler file (.cool or .mcool) containing binned Hi-C contact matrix
• eigenvector track (1D array indexed by genomic bins, typically from eigs_cis)
• bin annotation table (bin_id, chrom, start, end for filtering/masking)

Outputs

• 2D saddle matrix (saddledata array, shape n_bins × n_bins, contact frequency by compartment pair)
• saddle strength scalar (quantifies A/B compartment interaction asymmetry)
• NPZ file containing saddledata and metadata

How to apply

First, load a cooler Hi-C matrix and its associated eigenvector track (typically computed from principal component analysis on the contact matrix). Apply cooltools.digitize to bin the continuous eigenvector values into discrete compartment categories, typically using 2–5 quantile-based bins (commonly 2 for A/B classification). Call cooltools.saddle with the digitized track and cooler object to compute the 2D saddle matrix, which aggregates contact frequency for all bin pairs of the two compartment types. Extract the untransformed saddledata array and compute saddle strength as a scalar metric—conventionally the log2 ratio of (A–A + B–B interactions) to (A–B interactions)—which quantifies the preferential self-interaction of each compartment type. Validate the computation by confirming the output array dimensions match expected (n_bins × n_bins), the NPZ file structure is intact, and the saddle strength value is within realistic bounds (typically 0.5–3.0 for mammalian genomes).