This skill covers balancing, normalizing, and transforming Hi-C contact matrices with cooler and cooltools. Balancing (ICE/KR/SCALE) removes per-bin coverage bias so a single map is internally self-consistent under the equal-visibility assumption; computing distance-decay expected (expected_cis as a per-diagonal P(s) curve, expected_trans as a scalar) and dividing observed by it produces an observed/expected (O/E) matrix that exposes loops and compartments above the polymer background. The skill emphasizes two reframes most tutorials skip: balancing is a within-matrix operation and is NOT a cross-sample normalizer (subtracting two balanced maps reads depth as biology), and the equal-visibility model is silently violated by copy-number variation, so raw counts -- not ICE -- are correct for CNV/SV work in aneuploid genomes. It also owns the P(s) log-derivative as a polymer-state diagnostic and the resolution-vs-depth budget.
pip install cooler cooltools bioframe numpy
A .cool/.mcool matrix (see hic-data-io). Analysis functions take a single-resolution URI (file.mcool::/resolutions/10000), never the bare .mcool. Most operations require a balanced matrix (a stored weight column); balancing is a prerequisite for O/E, compartments, insulation, and dots.
Tell your AI agent what you want to do: - "Balance my Hi-C cooler with ICE, cis-only" - "Compute the P(s) contact-decay curve and its log-derivative" - "Make an observed/expected matrix for chr1" - "Why does my balanced matrix look wrong on a tumor sample?" - "What resolution can I afford with this many valid pairs?"
"Balance my 10kb .mcool with ICE, cis-only, masking low-coverage and blacklisted bins, and store the weights. Tell me whether it converged."
"KR balancing won't converge on my sparse high-resolution map. What should I switch to?"
"Compute cis expected with smoothing for hg38 chromosome arms, then build a log2(O/E) matrix for chr2 by dividing out the distance-matched expected."
"Compute the trans expected scalar per chromosome pair so I can make a genome-wide O/E."
"Plot the contact-probability-vs-distance curve and its log-log derivative; I want to see whether cohesin depletion flattened the loop-extrusion bump."
"My sample is an aneuploid tumor. Should I balance before calling CNV from the Hi-C coverage, or use raw counts?"
"I have two conditions at different depth and want to compare them. Is balancing both then subtracting correct?"
weight column exists.cooler.balance_cooler, reporting convergence; fall back from KR to ICE/SCALE if a juicer map failed to converge.expected_cis (per-diagonal P(s), smoothed) and/or expected_trans (scalar), then build O/E by mapping expected onto the dense matrix by diagonal offset.ignore_diags=2 removes ligation chemistry (self-ligation, dangling ends, religated fragments), not 3D contact -- that is why P(s)/expected starts at diagonal 2.divisive_weights before applying an imported vector.