Metadata-Version: 2.4
Name: lifton
Version: 1.0.13
Summary: Combining DNA and protein alignments to improve genome annotation with LiftOn
Home-page: https://github.com/Kuanhao-Chao/Lifton
Author: Kuan-Hao Chao
Author-email: kh.chao@cs.jhu.edu
License: GPL-3.0-or-later
Project-URL: Documentation, https://khchao.com/LiftOn/
Project-URL: Source, https://github.com/Kuanhao-Chao/Lifton
Project-URL: Bug Tracker, https://github.com/Kuanhao-Chao/Lifton/issues
Project-URL: Publication, https://doi.org/10.1101/gr.279620.124
Keywords: genome annotation,liftover,lift-over,bioinformatics,genomics,miniprot,minimap2,gff3,comparative genomics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22.0
Requires-Dist: biopython>=1.76
Requires-Dist: parasail>=1.2.4
Requires-Dist: intervaltree>=3.1.0
Requires-Dist: interlap>=0.2.6
Requires-Dist: networkx>=3.3
Requires-Dist: pyfaidx>=0.5.8
Requires-Dist: pysam>=0.19.1
Requires-Dist: gffutils>=0.10.1
Requires-Dist: ujson>=3.2.0
Requires-Dist: duckdb!=1.5.3,!=1.5.4,>=1.0
Requires-Dist: pyarrow>=14
Provides-Extra: native
Requires-Dist: mappy; extra == "native"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: hypothesis>=6.0; extra == "test"
Requires-Dist: coverage>=6.0; extra == "test"
Requires-Dist: flake8>=6.0; extra == "test"
Requires-Dist: packaging>=21; extra == "test"
Requires-Dist: setuptools>=61; extra == "test"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "test"
Requires-Dist: matplotlib>=3.5; extra == "test"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<img alt="My Logo" class="logo header-image only-light align-center" src="https://storage.googleapis.com/storage.khchao.com/figures/LiftOn/LiftOn_color.png" style="width:90%">

<div class="content">
<a class="reference external image-reference" href="https://img.shields.io/badge/License-GPLv3-yellow.svg"><img alt="https://img.shields.io/badge/License-GPLv3-yellow.svg" src="https://img.shields.io/badge/License-GPLv3-yellow.svg"></a>
<a class="reference external image-reference" href="https://img.shields.io/badge/version-v1.0.13-blue"><img alt="https://img.shields.io/badge/version-v1.0.13-blue" src="https://img.shields.io/badge/version-v1.0.13-blue"></a>
<a class="reference external image-reference" href="https://pepy.tech/project/lifton"><img alt="https://static.pepy.tech/personalized-badge/lifton?period=total&amp;units=abbreviation&amp;left_color=grey&amp;right_color=blue&amp;left_text=PyPi%20downloads" src="https://static.pepy.tech/personalized-badge/lifton?period=total&amp;units=abbreviation&amp;left_color=grey&amp;right_color=blue&amp;left_text=PyPi%20downloads"></a>
<a class="reference external image-reference" href="https://github.com/Kuanhao-Chao/lifton/releases"><img alt="https://img.shields.io/github/downloads/Kuanhao-Chao/lifton/total.svg?style=social&amp;logo=github&amp;label=Download" src="https://img.shields.io/github/downloads/Kuanhao-Chao/lifton/total.svg?style=social&amp;logo=github&amp;label=Download"></a>
<a class="reference external image-reference" href="https://github.com/Kuanhao-Chao/lifton/releases"><img alt="https://img.shields.io/badge/platform-macOS_/Linux-green.svg" src="https://img.shields.io/badge/platform-macOS_/Linux-green.svg"></a>
<a class="reference external image-reference" href="https://colab.research.google.com/github/Kuanhao-Chao/lifton/blob/main/notebook/lifton_example.ipynb"><img alt="https://colab.research.google.com/assets/colab-badge.svg" src="https://colab.research.google.com/assets/colab-badge.svg"></a>
<div class="line-block">
<div class="line"><br></div>
</div>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">

LiftOn is a homology-based lift-over tool using both DNA-DNA alignments (from <a href="https://academic.oup.com/bioinformatics/article/37/12/1639/6035128?login=true" target="_blank">Liftoff</a>, credits to <a href="https://scholar.google.com/citations?user=N3tXk7QAAAAJ&amp;hl=en" target="_blank">Dr. Alaina Shumate</a>) and protein-DNA alignments (from <a href="https://academic.oup.com/bioinformatics/article/39/1/btad014/6989621" target="_blank">miniprot</a>, credits to <a href="http://liheng.org" target="_blank">Dr. Heng Li</a>) to accurately map annotations between genome assemblies of the same or different species. LiftOn employs a two-step <a href="https://khchao.com/LiftOn/content/behind_scenes.html#protein-maximization-algorithm">protein maximization algorithm</a> to improve the annotation of protein-coding genes in the T2T-CHM13 <a href="https://s3-us-west-2.amazonaws.com/human-pangenomics/T2T/CHM13/assemblies/annotation/chm13v2.0_RefSeq_Liftoff_v5.1.gff3.gz" target="_blank">JHU RefSeqv110 + Liftoff v5.1</a> annotation.
The latest T2T-CHM13 annotation generated by LiftOn is available as <a href="ftp://ftp.ccb.jhu.edu/pub/data/LiftOn/JHU_LiftOn_v1.0.12_chm13v2.0.gff3" target="_blank">JHU_LiftOn_v1.0.12_chm13v2.0.gff3 <i class="fa fa-download"></i></a>, lifted from the GRCh38.p14 RefSeq annotation (release RS_2025_08) with LiftOn v1.0.12.

<section id="whats-new" class="">
<h2>What's new in v1.0.12<a class="headerlink" href="#whats-new" title="Permalink to this heading">#</a></h2>
<p><strong>v1.0.12</strong> makes very large-genome runs safer and diagnosable. For targets above 4 billion bases, LiftOn now runs Liftoff/minimap2 before miniprot so the two index-memory peaks do not overlap; <code>--parallel-aligners</code> explicitly overrides that safeguard. Native process signals are named correctly (for example, <code>-11</code> is <code>SIGSEGV</code>), and <code>run_manifest.json</code> records target size, the resolved schedule, commands, stages, bounded stderr tails, and signals. It also fixes trans-spliced copies whose children could bind to a same-ID parent on the wrong sequence. It also fixes a flat annotation -- a prokaryotic GFF3 with top-level <code>CDS</code> rows and no <code>gene</code> -- selecting nothing and failing several steps later, and adds <code>-dir/--intermediate-dir</code> so concurrent runs stop sharing one <code>lifton_output/</code>.</p>
<p><strong>v1.0.12 also recovers far more genes between distantly related species, and gives miniprot-derived models their stop codon.</strong> The miniprot-only rescue judged a candidate by its genomic span, which includes introns and so follows genome size: lifting from human into the compact fish, bird and frog genomes it discarded 75-83&nbsp;% of the missed genes miniprot found, although their alignments covered the whole reference protein. A second rescue sub-pass now judges exactly those by protein coverage, each rescued gene carries its other transcripts, and miniprot-derived CDS rows gain the stop codon the reference convention includes. Primary-assembly gene recall rises from 0.32 to 0.59 (human&nbsp;&#8594;&nbsp;zebrafish), 0.36 to 0.62 (human&nbsp;&#8594;&nbsp;chicken) and 0.36 to 0.64 (human&nbsp;&#8594;&nbsp;xenopus). Each ships with an opt-out; see the changelog.</p>
<p><strong>Several defaults CHANGE the output annotation relative to earlier versions</strong> (each ships with an opt-out flag that restores the previous behaviour):</p>
<ul class="simple">
<li><p><strong>A protein-coverage rescue sub-pass is default-ON</strong> (<em>v1.0.12</em>): it reconsiders miniprot-only candidates the rescue's genomic length band rejected, admitting those whose hit covers at least 0.8 of the reference protein at the same identity floor. Pass <code>--no-coverage-rescue-gate</code> to opt out.</p></li>
<li><p><strong>Rescued genes carry their isoforms</strong> (<em>v1.0.12</em>): each rescued gene also receives the other transcripts of the same reference gene whose miniprot hits lie at its locus; gene placement is unchanged. Pass <code>--no-rescue-isoforms</code> to opt out.</p></li>
<li><p><strong>Miniprot-derived models carry their stop codon</strong> (<em>v1.0.12</em>): miniprot's CDS ends at the last aligned codon, while the reference convention includes the stop. The terminal CDS and its exon now grow by those three bases when the genome has them, and only when the model does not get worse. Pass <code>--no-orf-stop-completion</code> to opt out.</p></li>
</ul>
<p>From earlier releases:</p>
<ul class="simple">
<li><p><strong>A third merge candidate is now default-ON</strong>: alongside {chained merge, Liftoff-only}, LiftOn scores miniprot's native CDS-only model and adopts it only when its ORF-rescued protein identity is <em>strictly</em> higher, so per-transcript identity never decreases. Pass <code>--no-miniprot-candidate</code> to restore the two-way merge.</p></li>
<li><p><strong>The miniprot-only rescue floor is now divergence-adaptive</strong>: the fixed 0.50 protein-identity floor is lowered toward 0.30 as the DNA lift's gene recall drops, recovering more genuinely missing genes at large evolutionary distance while staying inert on same- and close-species lifts. Pass <code>--no-adaptive-rescue-floor</code> to restore the fixed floor.</p></li>
<li><p><strong>CDS rows are richer and spec-valid</strong>: rebuilt CDS lines used to lose the reference's descriptive attributes (<code>Dbxref</code>, <code>product</code>, <code>protein_id</code>, ...) and carried no <code>ID</code> at all; they now inherit those attributes and share one <code>ID=cds-&lt;transcript&gt;</code>. Coding transcripts are also harmonized to <code>mRNA</code>. Coordinates and the encoded protein are untouched, and output grows 12&#8211;43%.</p></li>
<li><p><strong>Gene-like lift is now default-ON</strong>: LiftOn now lifts every reference gene-like top-level type (pseudogenes, <code>ncRNA_gene</code>s, structured mobile elements, ...), not just <code>gene</code>. Pass <code>--gene-only</code> to restore the old <code>gene</code>-only lift.</p></li>
<li><p><strong>Miniprot-only rescue is now default-ON</strong>: when the DNA lift misses a reference coding gene entirely, LiftOn fills it in from the miniprot model (tagged <code>lifton_rescue=miniprot_only</code>), recovering genes at large evolutionary distance. Pass <code>--no-miniprot-rescue</code> to opt out.</p></li>
<li><p><strong>Best-of-outcome merge is now default-ON</strong>: per transcript, LiftOn keeps whichever of {chained Liftoff&#8596;miniprot merge, Liftoff-only} scores higher against the reference protein, instead of applying the chained CDS unconditionally. Pass <code>--legacy-merge</code> to restore the unconditional (published-manuscript) merge.</p></li>
<li><p><strong>Banded / windowed alignment is now default-ON</strong>: the protein/DNA aligner is anchor-windowed above ~2500&nbsp;aa&nbsp;/&nbsp;8000&nbsp;nt, so giant genes are memory-bounded (no more titin-scale OOM) while same-species lifts stay identity-exact. Pass <code>--full-dp-align</code> to restore the exact giant-only full-DP path.</p></li>
</ul>
<div class="line-block">
<div class="line"><br></div>
</div>
</section>

<section id="installation-wrap" class="">
<h2>Installation<a class="headerlink" href="#installation-wrap" title="Permalink to this heading">#</a></h2>

<section id="install-through-pip">
<span id="id2"></span><h3>Install through pip<a class="headerlink" href="#install-through-pip" title="Permalink to this heading">#</a></h3>
<p>Install LiftOn's Python runtime from <a class="reference external" href="https://pypi.org/project/lifton/">PyPI</a>. Fresh standard lifts also require the <strong>minimap2 and miniprot executables on PATH</strong>; pip does not install them.</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ pip install lifton
</pre></div>
</div>
<p>Install the external aligners through Conda with strict channel priority:</p>
<pre>conda install --override-channels -c conda-forge -c bioconda --strict-channel-priority minimap2 miniprot</pre>
<p>Standard pip installs do not require mappy. The optional experimental binding is available through <code>pip install "lifton[native]"</code>; its source builds need a C compiler and zlib development headers. Conda supplies a prebuilt mappy alternative. See the <a href="https://khchao.com/LiftOn/content/installation.html">installation guide</a> for complete Conda, macOS and Seqera environments.</p>
<div class="line-block">
</div>
</section>

<section id="install-from-source">
<span id="id4"></span><h3>Install from source<a class="headerlink" href="#install-from-source" title="Permalink to this heading">#</a></h3>
<p>You can also install LiftOn from source. Check out the <a class="reference external" href="https://github.com/Kuanhao-Chao/LiftOn">latest version </a>
!</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git clone https://github.com/Kuanhao-Chao/LiftOn

$ cd LiftOn
$ python -m pip install .
</pre></div>
</div>
<div class="line-block">
<div class="line"><br></div>
</div>
</section>
</section>


<section id="why-lifton" class="">
<h2>Why LiftOn❓<a class="headerlink" href="#why-lifton" title="Permalink to this heading">#</a></h2>
<ol class="arabic simple">
<li><p><strong>Burgeoning number of genome assemblies</strong>: As of December 2023, there are 30,530 eukaryotic genomes, 567,228 prokaryotic genomes, and 66,429 viruses listed on NCBI (<a class="reference external" href="https://www.ncbi.nlm.nih.gov/genome/browse/#!/overview/">NCBI genome browser</a>). However, genome annotation is lagging behind. As more high-quality assemblies are generated, we need an accurate lift-over tool to annotate them.</p></li>
<li><p><strong>Improved protein-coding gene mapping</strong>: The popular <a class="reference external" href="https://academic.oup.com/bioinformatics/article/37/12/1639/6035128?login=true">Liftoff</a> tool maps genes based on DNA alignments alone. <a class="reference external" href="https://github.com/lh3/miniprot">Miniprot</a> maps genes based on protein alignments but, without gene structure information, may not be as accurate on their own (See <a class="reference internal" href="https://khchao.com/LiftOn/content/how_to_page.html#why-lifton-qa"><span class="std std-ref">FAQ Common mistakes of Liftoff and miniprot</span></a>). LiftOn combines both DNA-to-genome and protein-to-genome alignments and produces better gene mapping results! LiftOn improves upon the current released T2T-CHM13 annotation (<a class="reference external" href="https://s3-us-west-2.amazonaws.com/human-pangenomics/T2T/CHM13/assemblies/annotation/chm13v2.0_RefSeq_Liftoff_v5.1.gff3.gz">JHU RefSeqv110 + Liftoff v5.1</a>).</p></li>
<li><p><strong>Improved distantly related species lift-over</strong>: A key limitation of DNA-based lift-over tools is that they do not perform well when the reference and target genomes have significantly diverged. With the help of protein alignments and the protein maximization algorithm, LiftOn improves the lift-over process between distantly related species. See "<a class="reference internal" href="https://khchao.com/LiftOn/content/distant_species_liftover/liftover_mouse_2_rat.html#distant-species-liftover-mouse-to-rat"><span class="std std-ref">Mouse to Rat</span></a>" and "<a class="reference internal" href="https://khchao.com/LiftOn/content/distant_species_liftover/liftover_drosophila_erecta.html#distant-species-liftover-drosophila-melanogaster-2-erecta"><span class="std std-ref">Drosophila melanogaster to Drosophila erecta</span></a>" result sections.</p></li>
</ol>
<p>LiftOn is free, it's open source, it's easy to install , and it's in Python!</p>
<div class="line-block">
<div class="line"><br></div>
</div>
</section>
<section id="who-is-it-for" class="">
<h2>Who is it for❓<a class="headerlink" href="#who-is-it-for" title="Permalink to this heading">#</a></h2>
<p>LiftOn is designed for researchers and bioinformaticians who are interested in genome annotation. It is an easy-to-install and easy-to-run command-line tool. Specifically, it is beneficial in the following scenarios:</p>
<ol class="arabic simple">
<li><p>If you have sequenced and assembled a new genome and require annotation, LiftOn provides an efficient solution for generating annotations for your genome.</p></li>
<li><p>LiftOn is an excellent tool for those looking to perform comparative genomics analysis. It facilitates the lifting over and comparison of gene contents between different genomes, aiding in understanding evolutionary relationships and functional genomics.</p></li>
<li><p>For researchers interested in using T2T-CHM13 annotations, try LiftOn! We have pre-generated the <a class="reference external" href="ftp://ftp.ccb.jhu.edu/pub/data/LiftOn/JHU_LiftOn_v1.0.12_chm13v2.0.gff3">JHU_LiftOn_v1.0.12_chm13v2.0.gff3</a> file for your convenience.</p></li>
</ol>
<div class="line-block">
<div class="line"><br></div>
</div>
</section>
<section id="what-does-lifton-do" class="">
<h2>What does LiftOn do❓<a class="headerlink" href="#what-does-lifton-do" title="Permalink to this heading">#</a></h2>
<p>Let's first define the problem:
Given a reference <strong>Genome</strong> <span class="math notranslate nohighlight"><mjx-container class="MathJax CtxtMenu_Attached_0" jax="CHTML" tabindex="0" ctxtmenu_counter="0" style="font-size: 118.9%; position: relative;"><mjx-math class="MJX-TEX" aria-hidden="true"><mjx-mi class="mjx-i"><mjx-c class="mjx-c1D445 TEX-I"></mjx-c></mjx-mi></mjx-math><mjx-assistive-mml unselectable="on" display="inline"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>R</mi></math></mjx-assistive-mml></mjx-container></span>, an <strong>Annotation</strong> <span class="math notranslate nohighlight"><mjx-container class="MathJax CtxtMenu_Attached_0" jax="CHTML" tabindex="0" ctxtmenu_counter="1" style="font-size: 118.9%; position: relative;"><mjx-math class="MJX-TEX" aria-hidden="true"><mjx-msub><mjx-mi class="mjx-i"><mjx-c class="mjx-c1D445 TEX-I"></mjx-c></mjx-mi><mjx-script style="vertical-align: -0.153em;"><mjx-mi class="mjx-i" size="s"><mjx-c class="mjx-c1D434 TEX-I"></mjx-c></mjx-mi></mjx-script></mjx-msub></mjx-math><mjx-assistive-mml unselectable="on" display="inline"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>R</mi><mi>A</mi></msub></math></mjx-assistive-mml></mjx-container></span>, and a target <strong>Genome</strong> <span class="math notranslate nohighlight"><mjx-container class="MathJax CtxtMenu_Attached_0" jax="CHTML" tabindex="0" ctxtmenu_counter="2" style="font-size: 118.9%; position: relative;"><mjx-math class="MJX-TEX" aria-hidden="true"><mjx-mi class="mjx-i"><mjx-c class="mjx-c1D447 TEX-I"></mjx-c></mjx-mi></mjx-math><mjx-assistive-mml unselectable="on" display="inline"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>T</mi></math></mjx-assistive-mml></mjx-container></span>. The lift-over problem is defined as the process of changing the coordinates of <strong>Annotation</strong> <span class="math notranslate nohighlight"><mjx-container class="MathJax CtxtMenu_Attached_0" jax="CHTML" tabindex="0" ctxtmenu_counter="3" style="font-size: 118.9%; position: relative;"><mjx-math class="MJX-TEX" aria-hidden="true"><mjx-msub><mjx-mi class="mjx-i"><mjx-c class="mjx-c1D445 TEX-I"></mjx-c></mjx-mi><mjx-script style="vertical-align: -0.153em;"><mjx-mi class="mjx-i" size="s"><mjx-c class="mjx-c1D434 TEX-I"></mjx-c></mjx-mi></mjx-script></mjx-msub></mjx-math><mjx-assistive-mml unselectable="on" display="inline"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>R</mi><mi>A</mi></msub></math></mjx-assistive-mml></mjx-container></span> from <strong>Genome</strong> <span class="math notranslate nohighlight"><mjx-container class="MathJax CtxtMenu_Attached_0" jax="CHTML" tabindex="0" ctxtmenu_counter="4" style="font-size: 118.9%; position: relative;"><mjx-math class="MJX-TEX" aria-hidden="true"><mjx-mi class="mjx-i"><mjx-c class="mjx-c1D445 TEX-I"></mjx-c></mjx-mi></mjx-math><mjx-assistive-mml unselectable="on" display="inline"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>R</mi></math></mjx-assistive-mml></mjx-container></span> to <strong>Genome</strong> <span class="math notranslate nohighlight"><mjx-container class="MathJax CtxtMenu_Attached_0" jax="CHTML" tabindex="0" ctxtmenu_counter="5" style="font-size: 118.9%; position: relative;"><mjx-math class="MJX-TEX" aria-hidden="true"><mjx-mi class="mjx-i"><mjx-c class="mjx-c1D447 TEX-I"></mjx-c></mjx-mi></mjx-math><mjx-assistive-mml unselectable="on" display="inline"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>T</mi></math></mjx-assistive-mml></mjx-container></span>, and generate a new annotation file <strong>Annotation</strong> <span class="math notranslate nohighlight"><mjx-container class="MathJax CtxtMenu_Attached_0" jax="CHTML" tabindex="0" ctxtmenu_counter="6" style="font-size: 118.9%; position: relative;"><mjx-math class="MJX-TEX" aria-hidden="true"><mjx-msub><mjx-mi class="mjx-i"><mjx-c class="mjx-c1D447 TEX-I"></mjx-c></mjx-mi><mjx-script style="vertical-align: -0.153em; margin-left: -0.12em;"><mjx-mi class="mjx-i" size="s"><mjx-c class="mjx-c1D434 TEX-I"></mjx-c></mjx-mi></mjx-script></mjx-msub></mjx-math><mjx-assistive-mml unselectable="on" display="inline"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>T</mi><mi>A</mi></msub></math></mjx-assistive-mml></mjx-container></span>. A simple illustration of the lift-over problem is shown in <a class="reference internal" href="#liftover-illustration"><span class="std std-numref">Figure 1</span></a>.</p>
<figure class="align-center" id="id4">
<figcaption>
<span id="liftover-illustration"></span><a class="reference internal image-reference" href="https://storage.googleapis.com/storage.khchao.com/figures/LiftOn/liftover_illustration.gif"><img alt="graphics/liftover_illustration.gif" src="https://storage.googleapis.com/storage.khchao.com/figures/LiftOn/liftover_illustration.gif" style="width: 672.5px; height: 270.0px;"></a>
</figcaption>
</figure>
<div class="line-block">
<div class="line"><br></div>
</div>
<p>LiftOn is the best tool to help you solve this problem! LiftOn employs a two-step <a class="reference internal" href="https://khchao.com/LiftOn/content/behind_scenes.html#protein-maximization-algorithm"><span class="std std-ref">protein maximization algorithm</span></a> (PM algorithm).</p>
<ol class="arabic simple">
<li><p>The first module is the <em>chaining algorithm</em>. It starts by extracting protein sequences annotated by Liftoff and miniprot. LiftOn then aligns these sequences to full-length reference proteins. For each gene locus, LiftOn compares each section of the protein alignments from Liftoff and miniprot, chaining together the best combinations.</p></li>
<li><p>The second module is the <em>open-reading frame search (ORF search) algorithm</em>. In the case of truncated protein-coding transcripts, this algorithm examines alternative frames to identify the ORF that produces the longest match with the reference protein.</p></li>
</ol>
<div class="line-block">
<div class="line"><br></div>
</div>
</section>
<section id="inputs-outputs" class="">
<h2>Inputs &amp; outputs<a class="headerlink" href="#inputs-outputs" title="Permalink to this heading">#</a></h2>
<ul class="simple">
<li><dl class="simple">
<dt><strong>Input</strong>:</dt><dd><ol class="arabic simple">
<li><p>target <strong>Genome</strong> <span class="math notranslate nohighlight"><mjx-container class="MathJax CtxtMenu_Attached_0" jax="CHTML" tabindex="0" ctxtmenu_counter="7" style="font-size: 118.9%; position: relative;"><mjx-math class="MJX-TEX" aria-hidden="true"><mjx-mi class="mjx-i"><mjx-c class="mjx-c1D447 TEX-I"></mjx-c></mjx-mi></mjx-math><mjx-assistive-mml unselectable="on" display="inline"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>T</mi></math></mjx-assistive-mml></mjx-container></span> in FASTA format.</p></li>
<li><p>reference <strong>Genome</strong> <span class="math notranslate nohighlight"><mjx-container class="MathJax CtxtMenu_Attached_0" jax="CHTML" tabindex="0" ctxtmenu_counter="8" style="font-size: 118.9%; position: relative;"><mjx-math class="MJX-TEX" aria-hidden="true"><mjx-mi class="mjx-i"><mjx-c class="mjx-c1D445 TEX-I"></mjx-c></mjx-mi></mjx-math><mjx-assistive-mml unselectable="on" display="inline"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>R</mi></math></mjx-assistive-mml></mjx-container></span> in FASTA format.</p></li>
<li><p>reference <strong>Annotation</strong> <span class="math notranslate nohighlight"><mjx-container class="MathJax CtxtMenu_Attached_0" jax="CHTML" tabindex="0" ctxtmenu_counter="9" style="font-size: 118.9%; position: relative;"><mjx-math class="MJX-TEX" aria-hidden="true"><mjx-msub><mjx-mi class="mjx-i"><mjx-c class="mjx-c1D445 TEX-I"></mjx-c></mjx-mi><mjx-script style="vertical-align: -0.153em;"><mjx-mi class="mjx-i" size="s"><mjx-c class="mjx-c1D434 TEX-I"></mjx-c></mjx-mi></mjx-script></mjx-msub></mjx-math><mjx-assistive-mml unselectable="on" display="inline"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>R</mi><mi>A</mi></msub></math></mjx-assistive-mml></mjx-container></span> in GFF3 format.</p></li>
</ol>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt><strong>Output</strong>:</dt><dd><ol class="arabic simple">
<li><p>LiftOn annotation file, <strong>Annotation</strong> <span class="math notranslate nohighlight"><mjx-container class="MathJax CtxtMenu_Attached_0" jax="CHTML" tabindex="0" ctxtmenu_counter="10" style="font-size: 118.9%; position: relative;"><mjx-math class="MJX-TEX" aria-hidden="true"><mjx-msub><mjx-mi class="mjx-i"><mjx-c class="mjx-c1D447 TEX-I"></mjx-c></mjx-mi><mjx-script style="vertical-align: -0.153em; margin-left: -0.12em;"><mjx-mi class="mjx-i" size="s"><mjx-c class="mjx-c1D434 TEX-I"></mjx-c></mjx-mi></mjx-script></mjx-msub></mjx-math><mjx-assistive-mml unselectable="on" display="inline"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>T</mi><mi>A</mi></msub></math></mjx-assistive-mml></mjx-container></span>, in GFF3 format.</p></li>
<li><p>Protein sequence identities &amp; mutation types</p></li>
<li><p>Features with extra copies</p></li>
<li><p>Unmapped features</p></li>
</ol>
</dd>
</dl>
</li>
</ul>
<div class="line-block">
<div class="line"><br></div>
</div>
</section>
<section id="user-support" class="">
<h2>User support<a class="headerlink" href="#user-support" title="Permalink to this heading">#</a></h2>
<p>Please go through the <a class="reference internal" href="#table-of-contents"><span class="std std-ref">documentation</span></a> below first. If you have questions about using the package, a bug report, or a feature request, please use the GitHub issue tracker here:</p>
<p><a class="reference external" href="https://github.com/Kuanhao-Chao/LiftOn/issues">https://github.com/Kuanhao-Chao/LiftOn/issues</a></p>
<div class="line-block">
<div class="line"><br></div>
</div>
</section>
<section id="key-contributors" class="">
<h2>Key contributors<a class="headerlink" href="#key-contributors" title="Permalink to this heading">#</a></h2>
<p>LiftOn was designed and developed by <a class="reference external" href="https://khchao.com/">Kuan-Hao Chao</a>.  This documentation was written by <a class="reference external" href="https://khchao.com/">Kuan-Hao Chao</a> and <a class="reference external" href="https://github.com/am12">Alan Man</a>. The LiftOn logo was designed by <a class="reference external" href="https://github.com/am12">Alan Man</a>.</p>
<div class="line-block">
<div class="line"><br></div>
</div>
</section>
<section id="table-of-contents" class="">
<span id="id3"></span><h2>Table of contents<a class="headerlink" href="#table-of-contents" title="Permalink to this heading">#</a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/installation.html">Installation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/installation.html#system-requirements">System requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/installation.html#install-through-pip">Install through pip</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/installation.html#install-through-conda">Install through conda</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/installation.html#install-from-source">Install from source</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/installation.html#check-lifton-installation">Check LiftOn installation</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/installation.html#now-you-are-ready-to-go">Now, you are ready to go !</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/quickstart.html">Quick Start Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/quickstart.html#super-quick-start-one-liner">Super-Quick Start (one-liner)</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/quickstart.html#interpreting-outputs-on-the-terminal">Interpreting outputs on the terminal</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/quickstart.html#try-lifton-on-google-colab">Try LiftOn on Google Colab</a></li>
</ul>
</li>
</ul>
</div>
<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">Examples</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/same_species_liftover/index.html">Same species lift-over</a></li>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/close_species_liftover/index.html">Closely related species lift-over</a></li>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/distant_species_liftover/index.html">Distantly related species lift-over</a></li>
</ul>
</div>
<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">Info</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/output_explanation.html">Output files</a><ul>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/output_explanation.html#lifton-gff3">lifton.gff3</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/output_explanation.html#lifton-output">lifton_output/</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/feature_counting.html">Gene / Transcript counting</a><ul>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/feature_counting.html#gene-counting">Gene counting</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/feature_counting.html#transcript-counting">Transcript counting</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/evaluation_metrics.html">Evaluation metrics - sequence identity</a><ul>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/evaluation_metrics.html#dna-sequence-identity-score">DNA sequence identity score</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/evaluation_metrics.html#protein-sequence-identity-score">Protein sequence identity score</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/behind_scenes.html">Behind the scenes</a><ul>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/behind_scenes.html#deciding-chromosomes-and-features-for-annotation-lift-over">Deciding chromosomes and features for annotation lift-over</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/behind_scenes.html#matching-miniprot-liftoff-genome-annotation">Matching miniprot &amp; Liftoff genome annotation</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/behind_scenes.html#protein-maximization-algorithm">Protein-maximization algorithm</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/behind_scenes.html#mutation-report">Mutation report</a></li>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/behind_scenes.html#reference">Reference</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/how_to_page.html">FAQ ...</a></li>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/function_manual.html">User Manual</a><ul>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/function_manual.html#lifton">LiftOn</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/changelog.html">Changelog</a><ul>
<li class="toctree-l2"><a class="reference internal" href="https://khchao.com/LiftOn/content/changelog.html#v1-0-0">v1.0.1</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/license.html">License</a></li>
<li class="toctree-l1"><a class="reference internal" href="https://khchao.com/LiftOn/content/contact.html">Contact</a></li>
</ul>
</div>
<div class="line-block">
<div class="line"><br></div>
</div>
</section>
<section id="lifton-s-limitation">
<h2>LiftOn's limitation<a class="headerlink" href="#lifton-s-limitation" title="Permalink to this heading">#</a></h2>
<p>LiftOn's <em>chaining algorithm</em> currently only utilizes miniprot alignment results to fix the Liftoff annotation. However, it can be extended to chain together multiple DNA- and protein-based annotation files or aasembled RNA-Seq transcripts.</p>
<p>DNA- and protein-based methods still have some limitations. We are developing a module to merge the LiftOn annotation with the released curated annotations to generate better annotations.</p>
<p>As of v1.0.9 the per-locus processing step (the wall-clock hot spot) runs multi-threaded via <code>--threads N --locus-pipeline</code>; output is emitted in submission order, so a multi-threaded run is byte-for-byte identical to <code>--threads 1</code>.</p>
<div class="line-block">
<div class="line"><br></div>
</div>
</section>
</section>


<section id="cite-us" class="">
<h2>Cite us<a class="headerlink" href="#cite-us" title="Permalink to this heading">#</a></h2>
<p>Kua-Hao Chao, Jakob M. Heinz, Celine Hoh, Alan Mao, Alaina Shumate, Mihaela Pertea, and Steven L. Salzberg. <i>"Combining DNA and protein alignments to improve genome annotation with LiftOn."</i> <b>Genome Research</b> 35.2, 311-325 (2025), doi: https://doi.org/10.1101/gr.279620.124.
<a href="https://doi.org/10.1093/bioinformatics/btaa1016" target="_blank"> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> </a> </p>

<p>Alaina Shumate, and Steven L. Salzberg. <i>"Liftoff: accurate mapping of gene annotations."</i> <b>Bioinformatics</b> 37.12 (2021): 1639-1643.

<a href="https://doi.org/10.1093/bioinformatics/btaa1016" target="_blank"> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg>
</a>
</p><div class="line-block">
<div class="line"><br></div>
</div>
</section>

<br>
<br>
<br>

<img alt="My Logo" class="logo header-image only-light align-center" src="https://storage.googleapis.com/storage.khchao.com/figures/jhu-logo-dark.png">
