search

4dn-dcic / hic2cool

Lightweight converter between hic and cool contact matrices.
MIT License
63 stars 7 forks source link
bioinformatics contact-matrices converter cooler hi-c juicer

readme

hic2cool

Build Status

Converter between hic files (from juicer) and single-resolution or multi-resolution cool files (for cooler). Both hic and cool files describe Hi-C contact matrices. Intended to be lightweight, this can be used as an imported package or a stand-alone Python tool for command line conversion

The hic parsing code is based off the straw project by Neva C. Durand and Yue Wu. The hdf5-based structure used for cooler file writing is based off code from the cooler repository.

Important

Using the Python package

$ pip install hic2cool

You can also download the code directly and install using Poetry (as of version 1.0.0)

$ poetry install

Once the package is installed, the main method is hic2cool_convert. It takes the same parameters as hic2cool.py, described in the next section. Example usage in a Python script is shown below or in test.py.

from hic2cool import hic2cool_convert
hic2cool_convert(<infile>, <outfile>, <resolution (optional)>, <nproc (optional)>, <warnings (optional)>, <silent (optional)>)

Converting files using the command line

The main use of hic2cool is converting between filetypes using hic2cool convert. If you install hic2cool itself using pip, you use it on the command line with:

$ hic2cool convert <infile> <outfile> -r <resolution> -p <nproc>

Arguments for hic2cool convert

infile is a .hic input file.

outfile is a .cool output file.

-r, or --resolution, is an integer bp resolution supported by the hic file. Please note that only resolutions contained within the original hic file can be used. If 0 is given, will use all resolutions to build a multi-resolution file. Default is 0.

-p, or --nproc, is the number of processes to use. Default 1. The multiprocessing is not very efficient and would slightly improve speed only for large high-resolution matrices.

-w, or --warnings, causes warnings to be explicitly printed to the console. This is false by default, though there are a few cases in which hic2cool will exit with an error based on the input hic file.

-s, or --silent, run in silent mode and hide console output from the program. Default false.

-v, or --version, print out hic2cool package version and exit.

-h, or --help, print out help about the package/specific run mode and exit.

Running hic2cool from the command line will cause some helpful information about the hic file to be printed to stdout unless the -s flag is used.

Output file structure

If you elect to use all resolutions, a multi-resolution .mcool file will be produced. This changes the hdf5 structure of the file from a typical .cool file. Namely, all of the information needed for a complete cooler file is stored in separate hdf5 groups named by the individual resolutions. The hdf5 hierarchy is organized as such:

File --> 'resolutions' --> '###' (where ### is the resolution in bp). For example, see the code below that generates a multi-res file and then accesses the specific resolution of 10000 bp.

from hic2cool import hic2cool_convert
import cooler
### using 0 triggers a multi-res output
hic2cool_convert('my_hic.hic', 'my_cool.cool', 0)
### will give you the cooler object with resolution = 10000 bp
my_cooler = cooler.Cooler('my_cool.cool::resolutions/10000')

When using only one resolution, the .cool file produced stores all the necessary information at the top level. Thus, organization in the multi-res format is not needed. The code below produces a file with one resolution, 10000 bp, and opens it with a cooler object.

from hic2cool import hic2cool_convert
import cooler
### giving a specific resolution below (e.g. 10000) triggers a single-res output
hic2cool_convert('my_hic.hic', 'my_cool.cool', 10000)
h5file = h5py.File('my_cool.cool', 'r')
### will give you the cooler object with resolution = 10000 bp
my_cooler = cooler.Cooler(h5file)

higlass

Multi-resolution coolers produced by hi2cool can be visualized using higlass. Please note that single resolution coolers are NOT higlass compatible (created when using a non-zero value for -r). If you created a cooler before hic2cool version 0.5.0 that you want to view in higlass, it is highly recommended that you upgrade it before viewing on higlass to ensure correct normalization behavior.

To apply the hic normalization transformations in higlass, right click on the tileset and do the following:

"<name of tileset>" --> "Configure Series" --> "Transforms" --> "<norm>"

higlass img

Updating hic2cool coolers

As of hic2cool version 0.5.0, there was a critical change in how hic normalization vectors are handled in the resulting cooler files. Prior to 0.5.0, hic normalization vectors were inverted by hic2cool. The rationale for doing this is that hic uses divisive normalization values, whereas cooler uses multiplicative values. However, higlass and the 4DN analysis pipelines specifically handled the divisive normalization values, so hic2cool now handles them the same way.

In the near future, there will be a cooler package release to correctly handle divisive hic normalization values when balancing.

To update a hic2cool cooler, simply run:

hic2cool update <infile> <outfile (optional)>

If you only provide the infile argument, then the cooler will be updated directly. If you provide an optional outfile file path, then a new cooler updated cooler file will be created and the original file will remain unchanged.

Extracting hic normalization values

As of hic2cool 0.5.0, you can easily extract hic normalization vectors to an existing cooler file. This will only work if the specified cooler file shares the resolutions found in the hic file. To do this, simply run:

hic2cool extract-norms <hic file> <cooler file>

You may also provide the optional -e flag, which will cause the mitchondrial chromosome to automatically be omitted from the extraction. This is found by name; the code specifically looks for one of ['M', 'MT', 'chrM', 'chrMT'] (in a case-insensitive way). Just like with hic2cool convert, you can also provide -s and -w arguments.

Changelog

1.0.1

Contributors

Written by Carl Vitzthum (1), Nezar Abdennur (2), Soo Lee (1), and Peter Kerpedjiev (3).

(1) Park lab, Harvard Medical School DBMI

(2) Mirny lab, MIT

(3) Gehlenborg lab, Harvard Medical School DBMI

Originally published 1/26/17.