lifton 1.0.9

Combining DNA and protein alignments to improve genome annotation with LiftOn

LiftOn is a homology-based lift-over tool using both DNA-DNA alignments (from Liftoff, credits to Dr. Alaina Shumate) and protein-DNA alignments (from miniprot, credits to Dr. Heng Li) to accurately map annotations between genome assemblies of the same or different species. LiftOn employs a two-step protein maximization algorithm to improve the annotation of protein-coding genes in the T2T-CHM13 JHU RefSeqv110 + Liftoff v5.1 annotation. The latest T2T-CHM13 annotation generated by LiftOn is available as JHU_LiftOn_v1.0_chm13v2.0.gff3 (ftp://ftp.ccb.jhu.edu/pub/data/LiftOn/JHU_LiftOn_v1.0_chm13v2.0.gff3) .

What's new in v1.0.9#

LiftOn v1.0.9 is an incremental release. See the full CHANGELOG.md for the complete list of changes, robustness fixes (full RefSeq / cross-species genomes that previously crashed now complete), byte-identical performance fast-paths, and new validation tools.

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

• 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#

Install through pip#

LiftOn is on PyPi now. Check out all the releases here. Pip automatically resolves and installs any dependencies required by LiftOn.

$ pip install lifton

Install from source#

You can also install LiftOn from source. Check out the latest version !

$ 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#

• Installation
  • System requirements
  • Install through pip
  • Install through conda
  • Install from source
  • Check LiftOn installation
  • Now, you are ready to go !
• Quick Start Guide
  • Super-Quick Start (one-liner)
  • Interpreting outputs on the terminal
  • Try LiftOn on Google Colab

Examples

• Same species lift-over
• Closely related species lift-over
• Distantly related species lift-over

Info

• Output files
  • lifton.gff3
  • lifton_output/
• Gene / Transcript counting
  • Gene counting
  • Transcript counting
• Evaluation metrics - sequence identity
  • DNA sequence identity score
  • Protein sequence identity score
• Behind the scenes
  • Deciding chromosomes and features for annotation lift-over
  • Matching miniprot & Liftoff genome annotation
  • Protein-maximization algorithm
  • Mutation report
  • Reference
• FAQ ...
• User Manual
  • LiftOn
• Changelog
  • v1.0.1
• License
• Contact

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.