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).

Related tools

• cooltools (Core library providing digitize() and saddle() functions for binning eigenvector tracks and computing saddle matrices and strength metrics) — https://github.com/open2c/cooltools
• cooler (Sparse HDF5-based format for storage and retrieval of high-resolution contact matrices and associated genomic tracks) — https://github.com/open2c/cooler
• Python (Programming language for accessing cooltools API, handling eigenvector and cooler file I/O, and computing saddle strength metrics)

Examples

from cooltools import saddle, digitize; import cooler; c = cooler.Cooler('sample.cool'); eigvec = eigvec_track_from_file('eigvec.txt'); digitized = digitize(eigvec, n_bins=2); s, saddledata = saddle(c, digitized); print(f'Saddle strength: {s:.2f}')

Evaluation signals

• NPZ output file is valid HDF5 and contains saddledata array with shape (n_compartment_bins, n_compartment_bins) matching the number of eigenvector quantile bins used in digitization
• Saddle strength value is a finite positive scalar (typically 0.5–3.0 for mammalian genomes); negative or infinite values indicate computation or data quality issues
• Diagonal elements of saddledata (A–A and B–B interactions) are substantially higher than off-diagonal elements (A–B interactions), confirming compartment segregation
• Saddle matrix is symmetric (or nearly symmetric, within numerical tolerance), as compartment interaction is a symmetric relationship
• Repeated computation with different random seeds or subsets of input chromosomes produces saddle strength values within ±0.1 log2 units, confirming robustness

Limitations

• Saddle strength is sensitive to the choice of digitization threshold (number and placement of bins); different quantile schemes or fixed thresholds can yield different metrics. The article does not prescribe a standard threshold, so comparison across studies requires consistent binning strategies.
• The saddle.mask_bad_bins method is available to filter bins based on Hi-C-level quality flags, but the article notes this feature is optional; omitting masking may bias strength estimates if bad bins preferentially occur in one compartment type.
• Saddle analysis aggregates across entire chromosomes or chromosomal regions; local compartment switches or dynamic transitions are smoothed out in the global metric. Saddle strength does not resolve sub-kilobase compartment heterogeneity.
• The smoothing API for P(s) and other derivatives mentioned in the article is noted as unstable, limiting downstream normalization or visualization of saddle matrices in some versions of cooltools.

Evidence

• [other] Apply cooltools.digitize to bin the eigenvector values into discrete compartment categories (typically 2–5 bins) according to quantile or fixed thresholds.: "Apply cooltools.digitize to bin the eigenvector values into discrete compartment categories (typically 2–5 bins) according to quantile or fixed thresholds."
• [other] Call cooltools.saddle with the digitized track and cooler object to compute the 2D saddle matrix aggregating Hi-C contact frequency by compartment pair.: "Call cooltools.saddle with the digitized track and cooler object to compute the 2D saddle matrix aggregating Hi-C contact frequency by compartment pair."
• [other] Extract and save the saddledata array (untransformed) to an NPZ file and compute saddle strength as a scalar metric quantifying A/B compartment interaction asymmetry.: "Extract and save the saddledata array (untransformed) to an NPZ file and compute saddle strength as a scalar metric quantifying A/B compartment interaction asymmetry."
• [other] What are the input and output specifications for the cooltools.saddle function when applied to binned eigenvector track data from a cooler Hi-C matrix file?: "What are the input and output specifications for the cooltools.saddle function when applied to binned eigenvector track data from a cooler Hi-C matrix file?"
• [other] Cooltools provides saddle analysis functionality as part of its high-resolution Hi-C analysis toolkit, operating on cooler-format datasets that store high-resolution contact matrices and associated genomic tracks.: "Cooltools provides saddle analysis functionality as part of its high-resolution Hi-C analysis toolkit, operating on cooler-format datasets that store high-resolution contact matrices and associated"
• [readme] how to extract eigenvectors and create saddleplots reflecting A/B compartments: "how to extract eigenvectors and create saddleplots reflecting A/B compartments"
• [other] Added saddle.mask_bad_bins method to filter bins in a track based on Hi-C bin-level filtering: "Added saddle.mask_bad_bins method to filter bins in a track based on Hi-C bin-level filtering"