Skip to main content

Detect loops (and other patterns) in Hi-C contact maps.

Project description


animated logo

PyPI version Anaconda cloud Build Status codecov Read the docs License: GPLv3 Code style: black

Python package to detect chromatin loops (and other patterns) in Hi-C contact maps.


Stable version with pip:

pip3 install --user chromosight

Stable version with conda:

conda install -c bioconda -c conda-forge chromosight

or, if you want to get the latest development version:

pip3 install --user -e git+


chromosight has 3 subcommands: detect, quantify and generate-config. To get the list and description of those subcommands, you can always run:

chromosight --help

Pattern detection is done using the detect subcommand. The generate-config subcommand is used to create a new type of pattern that can then be fed to detect using the --custom-kernel option. The quantify subcommand is used to compute pattern matching scores for a list of 2D coordinates on a Hi-C matrix.

Get started

To get a first look at a chromosight run, you can run chromosight test, which will download a test dataset from the github repository and run chromosight detect on it.

Important options

  • --min-dist: Minimum distance from which to detect patterns.
  • --max-dist: Maximum distance from which to detect patterns. Increasing also increases runtime and memory use.
  • --precision: Decrease to allow a greater number of pattern detected (with potentially more false positives).
  • --perc-undetected: Proportion of empty pixels allowed in a window for detection.


To detect all chromosome loops with sizes between 2kb and 200kb using 8 parallel threads:

chromosight detect --threads 8 --min-dist 20000 --max-dist 200000 out_dir


Input Hi-C contact maps can be either in bedgraph2d or cool format. Bedgraph2d is defined as a tab-separated text file with 7 columns: chr1 start1 end1 chr2 start2 end2 contacts. The cool format is an efficient and compact format for Hi-C data based on HDF5. It is maintained by the Mirny lab and documented here:


Two files are generated in the output directory (replace pattern by the pattern used, e.g. loops or borders):

  • pattern_out.txt: List of genomic coordinates, bin ids and correlation scores for the pattern identified
  • pattern_out.json: JSON file containing the windows (of the same size as the kernel used) around the patterns from pattern.txt

Alternatively, one can set the --win-fmt=npy option to dump windows into a npy file instead of JSO. This format can easily be loaded into a 3D array using numpy's np.load function.


Pattern exploration and detection

Explore and detect patterns (loops, borders, centromeres, etc.) in Hi-C contact
maps with pattern matching.

    chromosight detect  [--kernel-config=FILE] [--pattern=loops] [--precision=auto]
                        [--iterations=auto] [--resize-kernel] [--win-fmt={json,npy}]
                        [--subsample=no] [--inter] [--smooth-trend] [--n-mads=5]
                        [--min-dist=0] [--max-dist=auto] [--no-plotting]
                        [--min-separation=auto] [--threads=1] [--dump=DIR]
                        [--perc-undetected=auto] <contact_map> [<output>]
    chromosight generate-config <prefix> [--preset loops] [--click contact_map] [--win-size=auto] [--n-mads=INT]
    chromosight quantify [--inter] [--pattern=loops] [--subsample=no] [--win-fmt=json]
                         [--n-mads=5] [--win-size=auto] <bed2d> <contact_map> <output>
    chromosight test

        performs pattern detection on a Hi-C contact map using kernel convolution
        Generate pre-filled config files to use for `chromosight detect`. 
        A config consists of a JSON file describing analysis parameters for the
        detection and path pointing to kernel matrices files. Those matrices
        files are tsv files with numeric values ordered in a square dense matrix
        to use for convolution.
        Given a list of pairs of positions and a contact map, computes the
        correlation coefficients between those positions and the kernel of the
        selected pattern.
        Download example data and run the program on it.


All contributions are welcome. We use the numpy standard for docstrings when documenting functions.

The code formatting standard we use is black, with --line-length=79 to follow PEP8 recommendations. We use nose2 as our testing framework. Ideally, new functions should have associated unit tests, placed in the tests folder.

To test the code, you can run:

nose2 -s tests/

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for chromosight, version 0.5.0
Filename, size File type Python version Upload date Hashes
Filename, size chromosight-0.5.0-py3-none-any.whl (138.5 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size chromosight-0.5.0.tar.gz (119.3 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page