lifton 1.0.10

What's new in v1.0.10#

LiftOn v1.0.10 builds on v1.0.9's whole-genome robustness with a third best-of-outcome merge candidate (miniprot's native CDS-only model), a divergence-adaptive miniprot-only rescue floor, output that is complete and spec-valid enough to hand downstream unedited, and a large byte-neutral speed and memory reduction — GFF3 validation alone drops from 5.64 GB to 267 MB on a full mammalian lift. It also fixes ten reported issues, including a DNA-lift SQL error that made the same input succeed on one machine and fail on another (GH #35) and a single bad alignment taking a whole chromosome with it (GH #39). See the full CHANGELOG.md for details.

Several new defaults CHANGE the output annotation relative to earlier versions (each ships with an opt-out flag that restores the previous behaviour):

• A third merge candidate is now default-ON: alongside {chained merge, Liftoff-only}, LiftOn scores miniprot's native CDS-only model and adopts it only when its ORF-rescued protein identity is strictly higher, so per-transcript identity never decreases. Pass --no-miniprot-candidate to restore the two-way merge.

• The miniprot-only rescue floor is now divergence-adaptive: 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 --no-adaptive-rescue-floor to restore the fixed floor.

• CDS rows are richer and spec-valid: rebuilt CDS lines used to lose the reference's descriptive attributes (Dbxref, product, protein_id, ...) and carried no ID at all; they now inherit those attributes and share one ID=cds-<transcript>. Coding transcripts are also harmonized to mRNA. Coordinates and the encoded protein are untouched, and output grows 12–43%.

• Gene-like lift is now default-ON: LiftOn now lifts every reference gene-like top-level type (pseudogenes, ncRNA_genes, structured mobile elements, ...), not just gene. Pass --gene-only to restore the old gene-only lift.

• Miniprot-only rescue is now default-ON: when the DNA lift misses a reference coding gene entirely, LiftOn fills it in from the miniprot model (tagged lifton_rescue=miniprot_only), recovering genes at large evolutionary distance. Pass --no-miniprot-rescue to opt out.

• Best-of-outcome merge is now default-ON: per transcript, LiftOn keeps whichever of {chained Liftoff↔miniprot merge, Liftoff-only} scores higher against the reference protein, instead of applying the chained CDS unconditionally. Pass --legacy-merge to restore the unconditional (published-manuscript) merge.

• Banded / windowed alignment is now default-ON: the protein/DNA aligner is anchor-windowed above ~2500 aa / 8000 nt, so giant genes are memory-bounded (no more titin-scale OOM) while same-species lifts stay identity-exact. Pass --full-dp-align to restore the exact giant-only full-DP path.

Installation#

$ pip install lifton

$ git clone https://github.com/Kuanhao-Chao/LiftOn
$ python setup.py install

Why LiftOn❓#

1. Burgeoning number of genome assemblies: As of December 2023, there are 30,530 eukaryotic genomes, 567,228 prokaryotic genomes, and 66,429 viruses listed on NCBI (NCBI genome browser). However, genome annotation is lagging behind. As more high-quality assemblies are generated, we need an accurate lift-over tool to annotate them.

2. Improved protein-coding gene mapping: The popular Liftoff tool maps genes based on DNA alignments alone. Miniprot maps genes based on protein alignments but, without gene structure information, may not be as accurate on their own (See FAQ Common mistakes of Liftoff and miniprot). 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 (JHU RefSeqv110 + Liftoff v5.1).

3. Improved distantly related species lift-over: 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 "Mouse to Rat" and "Drosophila melanogaster to Drosophila erecta" result sections.

LiftOn is free, it's open source, it's easy to install , and it's in Python!

Who is it for❓#

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:

1. If you have sequenced and assembled a new genome and require annotation, LiftOn provides an efficient solution for generating annotations for your genome.

2. 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.

3. For researchers interested in using T2T-CHM13 annotations, try LiftOn! We have pre-generated the JHU_LiftOn_v1.0_chm13v2.0.gff3 (ftp://ftp.ccb.jhu.edu/pub/data/LiftOn/JHU_LiftOn_v1.0_chm13v2.0.gff3) file for your convenience.

What does LiftOn do❓#

Let's first define the problem: Given a reference Genome , an Annotation , and a target Genome . The lift-over problem is defined as the process of changing the coordinates of Annotation from Genome to Genome , and generate a new annotation file Annotation . A simple illustration of the lift-over problem is shown in Figure 1.

LiftOn is the best tool to help you solve this problem! LiftOn employs a two-step protein maximization algorithm (PM algorithm).

1. The first module is the chaining algorithm. 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.

2. The second module is the open-reading frame search (ORF search) algorithm. 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.

Inputs & outputs#

• Input:

  1. target Genome in FASTA format.

  2. reference Genome in FASTA format.

  3. reference Annotation in GFF3 format.

• Output:

  1. LiftOn annotation file, Annotation , in GFF3 format.

  2. Protein sequence identities & mutation types

  3. Features with extra copies

  4. Unmapped features

User support#

Please go through the documentation below first. If you have questions about using the package, a bug report, or a feature request, please use the GitHub issue tracker here:

https://github.com/Kuanhao-Chao/LiftOn/issues

Key contributors#

LiftOn was designed and developed by Kuan-Hao Chao. This documentation was written by Kuan-Hao Chao and Alan Man. The LiftOn logo was designed by Alan Man.

Table of contents#

LiftOn's limitation#

LiftOn's chaining algorithm 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.

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.

As of v1.0.9 the per-locus processing step (the wall-clock hot spot) runs multi-threaded via --threads N --locus-pipeline; output is emitted in submission order, so a multi-threaded run is byte-for-byte identical to --threads 1.

Cite us#

Kua-Hao Chao, Jakob M. Heinz, Celine Hoh, Alan Mao, Alaina Shumate, Mihaela Pertea, and Steven L. Salzberg. "Combining DNA and protein alignments to improve genome annotation with LiftOn." Genome Research 35.2, 311-325 (2025), doi: https://doi.org/10.1101/gr.279620.124.

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