semvec/pypi-packages huggingface dataset:
pyliftover 0.4.1
Pure-python implementation of UCSC ``liftOver`` genome coordinate conversion.
License: MIT
Keywords: bioinformatics liftover genome-analysis

============================================================================
Pure-python implementation of UCSC ``liftOver`` genome coordinate conversion
============================================================================

.. image:: https://travis-ci.org/konstantint/pyliftover.png?branch=master   :target: https://travis-ci.org/konstantint/pyliftover

PyLiftover is a library for quick and easy conversion of genomic (point) coordinates between different assemblies.

It uses the same logic and coordinate conversion mappings as the UCSC `liftOver tool <http://genome.ucsc.edu/cgi-bin/hgLiftOver>`_.

As of current version (0.2), PyLiftover only does conversion of point coordinates, that is, 
unlike ``liftOver``, it does not convert ranges, nor does it provide any special facilities to work with BED files.
For single-point coordinates it produces exactly the same output as ``liftOver`` (verified with at least the ``hg17ToHg18.over.chain.gz`` file for now).

Installation
------------

The simplest way to install the package is via ``easy_install`` or ``pip``::

    $ easy_install pyliftover

Usage
-----
The primary usage example, supported by the library is the following::

    from pyliftover import LiftOver
    lo = LiftOver('hg17', 'hg18')
    lo.convert_coordinate('chr1', 1000000)

The first line will automatically download the hg17-to-hg18 coordinate conversion `chain file <http://genome.ucsc.edu/goldenPath/help/chain.html>`_ from UCSC,
unless it is already cached or available in the current directory. Alternatively, you may provide your own chain file::

    lo = LiftOver('hg17ToHg18.over.chain.gz')
    lo.convert_coordinate('chr1', 1000000, '-')

The result of ``lo.convert_coordinate`` call is either ``None`` (if the source chromosome name is unrecognized) or a list of target positions in the
new assembly. The list may be empty (locus is deleted in the new assembly), have a single element (locus matched uniquely), or, in principle, 
have multiple elements (although this is probably a rare occasion for most default intra-species genomic conversions).
Note that coordinates in the tool are 0-based. That is, a position that you would refer to in the genome browser by ``chr1:10`` 
corresponds to coordinate ``9`` in PyLiftover's terms.

Although you may try to apply the tool with arbitrary chain files, like the original ``liftOver`` tool, it makes most sense for conversion of 
coordinates between different assemblies of the same species.


See also
--------

* Blog post: http://fouryears.eu/2013/02/25/the-curse-of-genomic-coordinates/
* Report issues and submit fixes at Github: https://github.com/konstantint/pyliftover