saddle-matrix-computation-from-binned-tracks

saddle-matrix-computation-from-binned-tracks

Summary

Compute a 2D saddle matrix that aggregates Hi-C contact frequency by genomic compartment pair, quantifying A/B compartment interaction asymmetry. This skill transforms digitized eigenvector tracks (binned into discrete compartment categories) and a cooler Hi-C contact matrix into a saddle strength metric and full saddledata array.

When to use

You have a cooler Hi-C contact matrix file and an associated eigenvector track (from prior eigs_cis calculation or similar), and you need to quantify the preferential interaction patterns between A and B chromatin compartments. Use this skill when you want to measure compartment organization strength via the saddle plot, a classical 2D aggregation metric in genome architecture analysis.

When NOT to use

• Eigenvector track is missing or not yet computed from the Hi-C matrix.
• Hi-C data is not in cooler format or lacks bin-level coordinate metadata.
• Your goal is to visualize contact maps directly rather than quantify compartment interaction patterns.

Inputs

• cooler file (.cool or .mcool) containing binned Hi-C contact matrix
• eigenvector track array (continuous values per genomic bin, e.g. from eigs_cis)
• compartment binning parameters (number of bins or quantile thresholds)

Outputs

• saddle matrix (2D NumPy array, shape: n_bins × n_bins)
• saddledata (untransformed saddle matrix, typically saved to NPZ file)
• saddle strength (scalar float quantifying A/B compartment interaction asymmetry)
• digitized track (binned eigenvector values, integer class labels per bin)

How to apply

First, load the cooler file and its paired eigenvector track using cooler and bioframe APIs. Apply cooltools.digitize to bin the continuous eigenvector values into discrete compartment categories (typically 2–5 bins defined by quantiles or fixed thresholds). Call cooltools.saddle with the digitized track and cooler object to compute the 2D saddle matrix aggregating contact frequency by compartment pair. The saddle function performs quantile-based binning and cross-tabulation, producing both the untransformed saddledata array and a saddle strength scalar. Extract and validate the NPZ output file structure, confirm matrix dimensions match the number of bins, and verify saddle strength falls within expected ranges (typically 0–1 or higher for strong compartmentalization). The key rationale is that the digitized track reduces continuous variation to discrete classes, enabling robust aggregation across many loci.