Metadata-Version: 2.1
Name: pairLiftOver
Version: 0.1.5
Summary: Convert genomic coordinates of contact pairs from one assembly to another.
Home-page: https://github.com/XiaoTaoWang/pairLiftOver
Author: XiaoTao Wang
Author-email: wangxiaotao686@gmail.com
License: UNKNOWN
Description: pairLiftOver
        ============
        pairLiftOver is a Python package that converts the two-dimensional genomic coordinates
        of chromatin contact pairs between assemblies.
        
        pairLiftOver is based on the `UCSC chain files <https://genome.ucsc.edu/goldenPath/help/chain.html>`_.
        It takes a pairs file or matrix file as input, performs coordinate conversion for each contact pair,
        and outputs a sorted pairs file or contact matrix with coordinates in another assembly.
        
        Installation
        ============
        pairLiftOver is developed and tested on UNIX-like operating system, and following packages
        are required:
        
        - python 3.7+
        - pairtools 0.3.0
        - cooler
        - pyliftover
        - hic-straw 0.0.6
        
        We recommend using `conda <https://conda.io/miniconda.html>`_ to manage these packages. After
        you have installed conda on your system, execute the commands below::
        
            $ conda config --add channels defaults
            $ conda config --add channels bioconda
            $ conda config --add channels conda-forge
            $ conda create -n pairliftover python pairtools cooler pyliftover cxx-compiler
            $ conda activate pairliftover
            $ pip install pairLiftOver hic-straw
        
        Data Format
        ===========
        Currently, pairLiftOver supports 4 input data formats: `4DN pairs <https://github.com/4dn-dcic/pairix/blob/master/pairs_format_specification.md>`_,
        `allValidPairs <https://nservant.github.io/HiC-Pro/RESULTS.html>`_, `cool <https://open2c.github.io/cooler/>`_,
        and `hic <https://github.com/aidenlab/juicer/wiki/Data>`_. It is necessary to provide a pairs file
        (`4DN pairs <https://github.com/4dn-dcic/pairix/blob/master/pairs_format_specification.md>`_ or
        `allValidPairs <https://nservant.github.io/HiC-Pro/RESULTS.html>`_) to get the most accurate results,
        however, when such file is not available, pairLiftOver can also operate on contact matrices binned at kilobase resolutions
        (in `cool <https://open2c.github.io/cooler/>`_ or `hic <https://github.com/aidenlab/juicer/wiki/Data>`_ formats).
        For hic format, since multiple matrices at various resolutions are stored in a single file, pairLiftOver automatically detects
        and reads data from the one at the highest resolution. 
        
        The default output of pairLiftOver is a sorted pairs file in the standard 4DN pairs format,
        containing seven columns: “readID”, “chr1”, “pos1”, “chr2”, “pos2”, “strand1”, and “strand2”.
        However, you can also choose to output a matrix file in cool or hic format by setting the
        parameter ``--output-format``.
        
        Usage
        =====
        Open a terminal, type ``pairLiftOver -h`` for help information.
        
        Here is an example command which uses a 4DN pairs file in hg19 coordinates as input, and
        outputs an mcool file with chromatin contacts in hg38 coordinates::
        
            $ pairLiftOver --input test.hg19.pairs.gz --input-format pairs --out-pre test-hg38 \
            --output-format cool --out-chromsizes hg38.chrom.sizes --in-assembly hg19 --out-assembly hg38 \
            --logFile pairLiftOver.log
        
        Since the version 0.1.3, pairLiftOver has added a function to perform a pure
        format conversion. For example, the following command transforms a contact matrix
        from the .cool format to the .hic format, without the coordinate liftover. Note that
        the values of ``--in-assembly`` and ``--out-assembly`` need to be the same to turn
        on this function::
        
            $ pairLiftOver --input Rao2014-K562-MboI-allreps-filtered.5kb.cool --input-format cooler \
            --out-pre K562-format-conversion-test --output-format hic --out-chromsizes hg19.chrom.sizes \
            --in-assembly hg19 --out-assembly hg19 --memory 40G
        
        Running time and memory usage
        =============================
        The running time of pairLiftOver grows linearly with the number of contact pairs. The memory usage can
        be roughly controlled by the parameter ``--memory``. In the figure below, pairLiftOver was tested on the
        downsampled GM12878 Hi-C datasets (Rao 2014) (ranging from 100 million to 1 billion valid pairs). For each
        run, the memory and the number of processes allocated to pairLiftOver were set to 8Gb (``--memory 8G``) and
        8 (``--nproc 8``), respectively.
        
        .. image:: ./images/running-time-and-memory.png
                :align: center
        
        Accuracy
        ========
        So far, pairLiftOver has been tested on datasets of human (Rao 2014, GM12878 and K562), mouse (Rao 2014, CH12-LX)
        and zebrafish (Yang 2020, brain tissue). And the matrices obtained by pairLiftOver are nearly identical to the
        re-mapping results at various resolutions.
        
        .. image:: ./images/accuracy.png
                :align: center
        
        Citation
        ========
        Wang, X., Luan, Y., Yue, F. EagleC: A deep-learning framework for detecting a full range of
        structural variations from bulk and single-cell contact maps. Sci Adv. 2022.
        
        
        
Keywords: liftover pairs Hi-C 4DN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.6
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Description-Content-Type: text/x-rst
