Package: chromosight
ChromosightPython package to detect chromatin loops (and other patterns) in Hi-C contact maps.Associated publication:https://www.nature.com/articles/s41467-020-19562-7Documentation and analyses examples:https://chromosight.readthedocs.ioscripts used for the analysis presented in the articlehttps://github.com/koszullab/chromosight_analyses_scriptsInstallationStable version with pip:pip3install--userchromosightStable version with conda:condainstall-cbioconda-cconda-forgechromosightor, if you want to get the latest development version:pip3 install --user -e git+https://github.com/koszullab/chromosight.git@master#egg=chromosightUsageThe two main subcommands ofchromosightaredetectandquantify. For more advanced use, there are two additional subcomands:generate-configandlist-kernels. To get the list and description of those subcommands, you can always run:chromosight--helpPattern detection is done using thedetectsubcommand. Thequantifysubcommand is used to compute pattern matching scores for a list of 2D coordinates on a Hi-C matrix. Thegenerate-configsubcommand is used to create a new type of pattern that can then be fed todetectusing the--custom-kerneloption. Thelist-kernelscommand is used to view informations about the available patterns.Get startedTo get a first look at a chromosight run, you can runchromosight test, which will download a test dataset from the github repository and runchromosight detecton it. You can then have a look at the output files generated.Important optionsWhen runningchromosight detect, there are a handful parameters which are especially important:--min-dist: Minimum genomic distance from which to detect patterns. For loops, this means the smallest loop size accepted (i.e. distance between the two anchors).--max-dist: Maximum genomic distance from which to detect patterns. Increasing also increases runtime and memory use.--pearson: Detection threshold. Decrease to allow a greater number of pattern detected (with potentially more false positives). Setting a very low value may actually reduce the number of detected patterns. This is due to the algorithm which might merge neighbouring patterns.--perc-zero: Proportion of zero pixels allowed in a window for detection. If you have low coverage, increasing this value may improve results.ExampleTo detect all chromosome loops with sizes between 2kb and 200kb using 8 parallel threads:chromosightdetect--threads8--min-dist20000--max-dist200000hic_data.cooloutput_prefixOptionsPattern exploration and detection

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

Usage:
    chromosight detect  [--kernel-config=FILE] [--pattern=loops]
                        [--pearson=auto] [--win-size=auto] [--iterations=auto]
                        [--win-fmt={json,npy}] [--norm={auto,raw,force}]
                        [--subsample=no] [--inter] [--tsvd] [--smooth-trend]
                        [--n-mads=5] [--min-dist=0] [--max-dist=auto]
                        [--no-plotting] [--min-separation=auto] [--dump=DIR]
                        [--threads=1] [--perc-zero=auto]
                        [--perc-undetected=auto] <contact_map> <prefix>
    chromosight generate-config [--preset loops] [--click contact_map]
                        [--norm={auto,raw,norm}] [--win-size=auto] [--n-mads=5]
                        [--threads=1] <prefix>
    chromosight quantify [--inter] [--pattern=loops] [--subsample=no]
                         [--win-fmt=json] [--kernel-config=FILE] [--norm={auto,raw,norm}]
                         [--threads=1] [--n-mads=5] [--win-size=auto]
                         [--perc-undetected=auto] [--perc-zero=auto]
                         [--no-plotting] [--tsvd] <bed2d> <contact_map> <prefix>
    chromosight list-kernels [--long] [--mat] [--name=kernel_name]
    chromosight test

    detect:
        performs pattern detection on a Hi-C contact map via template matching
    generate-config:
        Generate pre-filled config files to use for detect and quantify.
        A config consists of a JSON file describing parameters for the
        analysis and path pointing to kernel matrices files. Those matrices
        files are tsv files with numeric values as kernel to use for
        convolution.
    quantify:
        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.
    list-kernels:
        Prints information about available kernels.
    test:
        Download example data and run loop detection on it.InputInput Hi-C contact maps should be in cool format. 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:https://open2c.github.io/cooler/Most other Hi-C data formats (hic, homer, hic-pro), can be converted to cool usinghicexplorer's hicConvertFormatorhic2cool. Bedgraph2 format can be converted directly using cooler with the commandcooler load -f bg2 <chrom.sizes>:<binsize> in.bg2.gz out.cool. For more informations, see thecooler documentationForchromosight quantify, the bed2d file is a text file with at least 6 tab-separated columns containing pairs of coordinates. The first 6 columns should bechrom start end chrom start endand have no header. Alternatively, the output text file generated bychromosight detectis also accepted. Instructions to generate a bed2d file from a bed file are givenin the documentation.OutputThree files are generated by chromosight'sdetectandquantifycommands. Their filenames are determined by the value of the<prefix>argument:prefix.tsv: List of genomic coordinates, bin ids and correlation scores for the pattern identifiedprefix.json: JSON file containing the windows (of the same size as the kernel used) around the patterns from pattern.txtprefix.pdf: Plot showing the pileup (average) window of all detected patterns. Plot generation can be disabled using the--no-plottingoption.Alternatively, one can set the--win-fmt=npyoption to dump windows into a npy file instead of JSON. This format can easily be loaded into a 3D array using numpy'snp.loadfunction.Note: the p-values and q-values provided in prefix.tsv should not be used as a criterion for filtering and are only useful for ranking calls. Their values are obtained from a Pearson correlation test and could be biased due to the dependence between contact values in the window.ContributingAll contributions are welcome. We use thenumpy standardfor docstrings when documenting functions.The code formatting standard we use isblack, with --line-length=79 to follow PEP8 recommendations. We usenose2as our testing framework. Ideally, new functions should have associated unit tests, placed in thetestsfolder.To test the code, you can run:nose2-stests/FAQQuestions from previous users are available in thegithub issues. You can open a new issue for your question if it is not already covered.CitationWhen using Chromosight in you research, please cite the pubication:https://www.nature.com/articles/s41467-020-19562-7