How to fetch balanced cooler matrix?

[bskubi]

Using the cooler library, I normally call Cooler.matrix(balance=True) to create an object that will fetch a balanced matrix, rather than passing a particular normalization string as is done with hic-straw. Using a .mcool file, how would I obtain a balanced matrix from a .mcool file using hictkpy?

Thank you!

[robomics]

Hi, you can fetch normalized interactions like so:

f = hictkpy.File("test.cool")
sel = f.fetch(normalization="weight")  # this is the default name used by cooler when saving balancing weights
sel = f.fetch(normalization="KR")
sel = f.fetch(normalization="foobar")  # normalizations can in principle have any name. The name used is determined by the tool used to normalize the Cooler/.hic file

For a complete list of the arguments accepted by File.fetch() check out the relevant section in the API docs - link.
We also have some examples in the Quickstart section of the docs.

Unfortunately there is no reasonable way to select a default weight name given that the API is format agnostic.

Here are a few other potentially useful commands:

f.avail_normalizations()  # Get the list of available normalizations as a List[str]
f.has_normalization("foobar")  # Check whether the file has normalization weights with the given name
f.weights("foobar")  # Return the vector of weights as a numpy.NDArray
f.weights(["foo", "bar"])  # Return the weights as a pandas.DataFrame

Or if you prefer to work with CLI tools:

user@dev:/tmp$ hictk dump -t normalizations 4DNFIZ1ZVXC8.mcool
KR
SCALE
VC
VC_SQRT
weight

user@dev:/tmp$ hictk dump -t weights --resolution 10000 4DNFIZ1ZVXC8.mcool | head
KR	SCALE	VC	VC_SQRT	weight
0.6086455557414997	0.6099059649492686	0.6985603009866895	0.7692300521384852	54.645964337802916
1.283911000107672	1.2865122321762432	1.5335410562998621	1.1397300421869327	126.79126534782031
1.1772096377259684	1.1788639852798648	1.509306985553431	1.1306887817996827	122.44696183684262
1.0138842887639419	1.016095524279372	1.3056199984074146	1.0516293275077588	90.18278097717564
1.1888554311130186	1.1913429000256799	1.554830800693923	1.147614058757168	115.87718577637905
1.1871607524935952	1.189577012061341	1.6079041705840822	1.1670363224726157	123.03529343084571
1.3507504757632192	1.3534383978522373	1.9305721405848508	1.2787843410969668	146.87852929677075
1.3519175610742031	1.3547056053177857	2.066237639436367	1.3229530337536146	143.63539477173543
1.679828465612945	1.6830591337035108	2.7453955847164124	1.5249540500366427	192.63058412009948

[bskubi]

Thank you very much for this comprehensive answer!