Output files
After running LiftOn, you will obtain a LiftOn GFF3 file and a lifton_output/ directory. More details are shown in the output directory hierarchy below. This page provides guidance on how to interpret your results.
LiftOn output directory hierarchy
# LiftOn output directory hierarchy
.
├── lifton.gff3
└── lifton_output
|
├── score.txt
├── run_manifest.json
|
├── liftoff
│ ├── liftoff.gff3
│ ├── liftoff.gff3_db
│ └── unmapped_features.txt
|
├── miniprot
│ ├── miniprot.gff3 # default path
│ ├── miniprot.gff3_db # default path
│ └── miniprot.duckdb # --stream path
|
├── intermediate_files
│ ├── proteins.fa
│ ├── reference_all_genes.fa
│ ├── reference_all_to_target_all.sam
│ ├── target_all.mmi
│ ├── ref_feature.txt
│ ├── ref_transcript.txt
│ └── transcripts.fa
|
└── stats
├── extra_copy_features.txt
├── mapped_feature.txt
├── mapped_transcript.txt
└── unmapped_features.txt
lifton.gff3
This is the main output of LiftOn software. It is an annotation file of the target genome in GFF3 format. Following is an example of a gene locus. For more details about GFF3, check GFF3 file format.
LiftOn stages this file in the destination directory and publishes it with an
atomic replacement only after processing succeeds. Every run applies a
streaming structural GFF3 gate before publication; --validate-output adds
deeper hierarchy, containment, CDS-phase, and LiftOn-attribute checks. Invalid
output never replaces an existing file and is preserved as
*.partial.gff3. --allow-partial-output permits known per-locus failures,
but never bypasses either validation gate.
lifton_output/
This directory contains all LiftOn outputs, including the following:
run_manifest.json
This JSON file records the exact command and sanitized options, SHA-256 input
fingerprints, LiftOn/Python/dependency/tool versions, Git revision, selected
backends and cache decisions, phase timings, resource use, output validation,
counts, and per-stage failures. Archive it with lifton.gff3 to make a run
auditable and reproducible.
1. score.txt
It is a tsv file summarizing the LiftOn results.
Column definition
Transcript ID
Liftoff transcript protein sequence identity: \(0-1\)
miniprot transcript protein sequence identity: \(0-1\)
LiftOn transcript DNA sequence identity: \(0-1\)
LiftOn transcript protein sequence identity: \(0-1\)
The source of the annotation:
'Liftoff', 'miniprot', or 'LiftOn_chaining_algorithm'.
Mutation types
'synonymous', 'nonsynonymous', 'inframe_insertion', 'inframe_deletion', 'frameshift', 'stop_codon_gain', 'stop_codon_loss', and 'start_codon_loss".
Transcript locus coordinate:
<chromosome>:<start>-<end>
2. liftoff/
The liftoff GFF3 annotatation generated during the LiftOn process.
3. miniprot/
The miniprot GFF3 file generated during the LiftOn process.
4. intermediate_files/
This directory stores intermediate protein and transcript sequences (FASTA),
gene-to-genome alignments (SAM), reference feature classifications, and the
run-local minimap2 target index (normally target_all.mmi; chromosome
splits use their target prefix). LiftOn first validates a cached
<target FASTA>.mmi next to the target FASTA. A missing index, unresolved
Git LFS pointer, corrupt index, or index built for a different target is rebuilt
here automatically so the input directory does not need to be writable. LiftOn
preserves invalid adjacent files. Run-local indexes can be deleted after a run;
they are generated data, not part of the final annotation.
5. stats/mapped_feature.txt
It is a TSV file summarizing the number of features being mapped from the reference genome to the target genome.
Column definition
Feature ID
The number of feature copy
Feeature type: coding, non-coding, or other
6. stats/mapped_transcript.txt
It is a TSV file summarizing the number of transcripts being mapped from the reference genome to the target genome.
Column definition
Transcript ID
The number of transcript copy
Transcript type: coding, non-coding, or other
7. stats/extra_copy_features.txt
Similar to mapped_feature.txt, this TSV file summarizes the number of additional copies of genes and indicates whether they are coding or non-coding.
Column definition
Feature ID
The number of feature copy
Feeature type: coding, non-coding, or other
8. stats/unmapped_features.txt
It is a TSV file summarizing unmapped gene IDs and their types.
Column definition
Gene ID
Feeature type: coding, non-coding, or other
