This skill covers loading, converting, and manipulating Hi-C contact matrices in the cooler ecosystem (.cool/.mcool/.scool) and the Juicer .hic format. The central idea is that cooler stores raw observed counts and computes everything else on the fly, whereas .hic bakes normalization and expected vectors into a sealed binary; conversion between them is therefore never lossless in both directions. The skill teaches the single-resolution mcool URI, the divisive-vs-multiplicative weight-naming rule that silently corrupts balanced values, what survives .hic conversion (FRAG matrices and some norms do not), how to coarsen correctly by summing raw counts and re-balancing, and the chrom-naming and bin-table provenance that decide whether two coolers can even be compared.
pip install cooler hic2cool hictk bioframe numpy pandas
# hictk also ships as a conda package and a static binary:
conda install -c bioconda hictk cooler
A .cool must be balanced (carry a weight column) before most downstream analysis. Balancing mechanics live in matrix-operations; this skill loads, converts, and inspects.
Tell your AI agent what you want to do: - "Load the 10kb resolution from my mcool and pull out chr1" - "Convert this .hic file to a multi-resolution mcool, keeping the KR norms" - "Build a cooler from my pairs file at 10kb" - "Why is my balanced matrix all NaN?" - "My fetch('1') returns nothing - what is wrong?" - "Coarsen this 10kb cooler to 100kb correctly"
"I have an mcool. List its resolutions, open the 25kb level, tell me whether it is balanced, and return the balanced chr2 matrix as a numpy array."
"Fetch the inter-chromosomal (trans) submatrix between chr1 and chr8 from my balanced cooler."
"Convert in.hic to an mcool with all resolutions using hic2cool, and make sure the Juicer norm vectors come through as divisive so balancing is correct."
"This .hic is large - use hictk to convert just the 5kb and 10kb resolutions to a cooler, and warn me if any matrices are FRAG-binned and would be lost."
"Build a 10kb cooler from my flipped, deduped .pairs file using cooler cload, with hg38 chromsizes."
"I have an in-memory numpy contact matrix for chr1 - write it to a cooler without a slow per-bin-pair loop."
"My two coolers give different balanced values from the same .hic - figure out if it is a hic2cool version mismatch."
"Coarsen my 10kb cooler to 50kb and 100kb the correct way (raw sum then re-balance), not by summing balanced pixels."
file.mcool::/resolutions/<bp>), listing resolutions if needed.weight column and report whether the chosen resolution is balanced.cooler cload for pairs).zoomify/coarsen so raw counts are summed and balancing is re-run per resolution.::/resolutions/<bp> URI; never hand a bare .mcool to a downstream tool.weight column name is not cosmetic: cooler weight is multiplicative; KR/VC/VC_SQRT are auto-divisive. Do not rename Juicer norms to weight.cooler zoomify --balance)..hic matrices do not survive any converter; re-bin in base pairs from the pairs.chr1 vs 1 silently zeros every join; pin one chrom naming and one assembly across the cooler, FASTA, tracks, and blacklist.