Version Compatibility

Reference examples tested with: TOGA 1.1.7+ (hillerlab/TOGA; Kirilenko 2023 Science 380:eabn3107), CESAR 2.0 (Sharma & Hiller 2017 NAR 45:8369), LiftOff 1.6.3+ (Shumate & Salzberg 2021 Bioinformatics 37(12):1639-1643), Comparative Annotation Toolkit (CAT) 2.4+, GeMoMa 1.9+ (Keilwagen 2019 Methods Mol Biol 1962:161), UCSC liftOver 2024+, Cactus 2.9.1+ (for HAL input), HAL toolkit 2.3+, NextFlow 24+ for TOGA pipeline, BUSCO 5.7+ / Compleasm 0.2.7+ for QC, Snakemake 8.0+ for CAT, R 4.4+. The current TOGA expects HAL from Cactus 2.5+; older HAL formats may fail.

Before using code patterns, verify installed versions match. If versions differ:

• CLI: toga.py --help; cesar --help; liftoff --version
• Python: pip show liftoff
• Java: gemoma --help (Java 11+)

If code throws TOGA chain file missing, CESAR fragment not found, LiftOff annotation not parsed, the toolchain expects specific input formats: TOGA needs HAL or chain/net files from Cactus / LASTZ; CESAR needs exon-level GFF; LiftOff needs reference GFF and aligned FASTA. Pre-process with the appropriate format conversion.

Comparative Annotation Projection

"Annotate this new genome using my well-annotated reference" -> Annotation projection from a reference is the modern alternative to de novo gene prediction; it produces high-quality, comparable annotations across genomes by leveraging evolutionary conservation. The 2023-era standard is TOGA + CESAR 2.0 (Kirilenko 2023 Science 380:eabn3107), which uses whole-genome alignment chains + ML classification + codon-aware exon projection to scale to hundreds of genomes (Zoonomia: 488 mammals; Bird10000 Genomes: 501 birds). For ortholog-based projection (no WGA needed), LiftOff (Shumate & Salzberg 2021 Bioinformatics 37(12):1639) is the standard. The critical decision is WGA-anchored (TOGA) vs ortholog-anchored (LiftOff): TOGA explicitly classifies gene intactness vs loss using the alignment chains, LiftOff relies on reciprocal-best-hit equivalents.

• CLI: toga.py --chain chain.bb --bed ref.bed --tDB target.2bit --qDB query.2bit --pn project_name -- WGA-based projection
• CLI: cesar -i exons.fa -d 4 -o output.aln -- codon-aware exon alignment (used internally by TOGA)
• CLI: liftoff -g ref.gff query.fa ref.fa -o query.gff -- ortholog-based projection
• CLI: gemoma -- evidence-based comparative annotation (Java)
• CLI: cat (Comparative Annotation Toolkit) -- multi-species annotation projection

Algorithmic Taxonomy

Methodology evolves; the Kirilenko 2023 TOGA paradigm (WGA-anchored + intactness classification) is the gold standard for vertebrate-scale comparative annotation. For pairwise transfers, LiftOff is the modern standard. Verify the current TOGA documentation (hillerlab/TOGA) before locking on a single approach.

Decision Tree by Experimental Scenario

Per-Tool Failure Modes

TOGA chain file missing or incompatible

Trigger: Running TOGA on Cactus HAL without proper chain file extraction.

Mechanism: TOGA requires UCSC-style chain files derived from Cactus HAL or LASTZ chains/nets pipeline. Cactus HAL doesn't directly produce chain files; conversion via halSynteny + chainNet + axtChain is required.

Symptom: TOGA fails with "chain file not found" or "no syntenic blocks for query."

Fix: Use halSynteny (HAL toolkit) to extract syntenic blocks; convert to chain format via axtChain and chainNet. The TOGA Nextflow wrapper handles this automatically; for manual runs, see UCSC kentUtils chain documentation.

CESAR exon-fragment misalignment in highly divergent species

Trigger: Projecting from mouse to fish (~400 Myr divergence); many exons fail CESAR projection.

Mechanism: CESAR's HMM model is calibrated for vertebrate divergence (< 100 Myr typical). At deep divergence, exon boundaries shift; CESAR may misalign or fail to project.

Symptom: Many genes in mouse have TOGA "M" (missing) or "PI" (partial-intact) classification in fish; coverage of expected genes is low.

Fix: TOGA documentation recommends < 300 Myr divergence for reliable projection. For deeper divergence, manual review of failed exons; consider GeMoMa with multiple reference species. Some genes won't project because they're truly absent (orphan genes); others fail due to alignment limitations.

LiftOff tandem duplicate ambiguity

Trigger: LiftOff on genomes with extensive tandem duplications (e.g., NLR clusters in plants, olfactory receptors in mammals).

Mechanism: LiftOff uses ortholog detection similar to OrthoFinder; tandem duplicates create many similar sequences, making reciprocal-best-hit identification ambiguous.

Symptom: LiftOff reports many "multimapped" genes; tandem clusters have one-to-many or many-to-one orthology calls.

Fix: Pre-collapse tandem duplicates manually; or use LiftOff with -mismatch 5 and -flank 0.5 for more relaxed mapping; or use TOGA which has tandem-aware classification.

TOGA intactness classification false negatives

Trigger: TOGA classifies a gene as "Lost" when it is actually intact.

Mechanism: TOGA uses ML classifier on chain features + frame preservation; assembly gaps, short alignment fractions, or CESAR projection failures can cause false-loss calls.

Symptom: TOGA "Lost" gene actually present in independent validation (RNA-Seq, manual inspection); known biology contradicts loss.

Fix: Manual review of TOGA "Lost" calls in the loss_summ_data.tsv; cross-validate with RNA-Seq mapping; use ID + biology to verify. TOGA's classifier is calibrated for mammals/birds; non-canonical genome architectures may produce false losses.

Reference choice bias

Trigger: Projecting from one reference (e.g., mouse) produces different annotation than from another (e.g., human).

Mechanism: Each reference's annotation has its own biases (gene structures, splice variants, missing genes). Projection inherits these biases; different references produce somewhat different annotations.

Symptom: Mouse-reference TOGA annotation has gene X missing in query; human-reference TOGA has it present; or different exon structures.

Fix: Project from multiple references; consensus annotation. CAT integrates multi-reference projection; manual review of inconsistencies. Document reference choice impact.

Pseudogenization vs gene loss distinction

Trigger: Reporting a "lost" gene that retains coding sequence (frame may be conserved but expression lost).

Mechanism: TOGA detects loss of coding capacity (intactness), but doesn't directly identify pseudogenization (loss of expression). A pseudogene with intact reading frame may be classified "Intact" by TOGA.

Symptom: TOGA "Intact" annotation but the gene is pseudogene per RNA-Seq + Ribo-Seq evidence.

Fix: Combine TOGA intactness with expression data (RNA-Seq from species of interest); apply PseudoPipe (Zhang 2006 GR 16:1041) or RetroFinder (Baertsch 2008 GR 18:1675) for systematic pseudogene detection.

Splice variant inconsistency across projections

Trigger: Projecting genes with extensive alternative splicing.

Mechanism: Reference may have alternative splice variants; projection of alternative isoforms requires per-isoform alignment which may fail for some variants.

Symptom: Query species has fewer projected isoforms than reference; canonical isoform present but alternatives missing.

Fix: TOGA projects each transcript independently; manual review of dropped isoforms. RNA-Seq from species of interest for novel splice variants.

Annotation pipeline reference quality affecting projection

Trigger: Projecting from an outdated or buggy reference annotation.

Mechanism: Errors in reference annotation propagate to all projections. A wrong exon boundary in mouse is propagated to all mammals.

Symptom: Same exon boundary error appears across many projected annotations.

Fix: Verify reference annotation quality via BUSCO + manual gene model review; use updated Ensembl / NCBI releases (current 2024-Q4).

Polyploid query genome handling

Trigger: Projecting annotations onto a polyploid query without subgenome consideration.

Mechanism: Projection sees multiple homeologous regions; ortholog detection ambiguous between subgenomes.

Symptom: Polyploid query annotation has ~2x the genes expected; many "redundant" projections from homeologs.

Fix: Assign subgenomes before projection (see [[whole-genome-duplication]]); project to each subgenome separately. AnchorWave proali handles ploidy; LiftOff doesn't natively.

Chromosome-level vs scaffold-level reference

Trigger: Projecting from chromosome-level reference to scaffold-level query.

Mechanism: Scaffold-level query has gaps and ambiguous gene assignments; projection mostly succeeds but some genes split across scaffolds.

Symptom: Projected GFF has fragmented gene models; some genes have 2-3 entries across scaffolds.

Fix: Pre-scaffold query (Hi-C scaffolding if possible); or accept partial annotations; document fragmentation rate. TOGA reports "Partial Intact" for these cases.

Quantitative Thresholds

TOGA Standard Workflow

Goal: Project annotations from reference to query genome(s), classifying gene-loss / intactness.

Approach: Cactus WGA -> halSynteny + chainNet -> TOGA Nextflow pipeline.

# Prerequisites: Cactus HAL file from [[whole-genome-alignment]]
# OR LASTZ chain/net pipeline output

# 1. Extract syntenic blocks from HAL
halSynteny output.hal reference query --queryGenome query > query.synteny.psl

# 2. Convert PSL to UCSC chain format
axtChain -psl -linearGap=loose query.synteny.psl reference.2bit query.2bit chains/query.chain.gz
# Note: `-psl` is correct here only if the input is PSL. When the input comes from
# `lastz --format=axt`, drop the `-psl` flag (or emit PSL from LASTZ first).

# 3. Run TOGA. The canonical invocation is `python toga.py` from the TOGA checkout;
# the Nextflow-style command shown below mirrors the same arguments but may not be
# the standard entry point in your release -- verify against the hillerlab/TOGA README.
python toga.py \
    chains/query.chain.gz \
    reference_annotation.bed \
    reference.2bit \
    query.2bit \
    --pn project_name \
    --cpus 32

# Output:
#   project_name/loss_summ_data.tsv           Per-gene intactness call
#   project_name/orthology_classification.tsv One-to-one / one-to-many / many-to-many
#   project_name/query_annotation.bed         Lifted gene annotation
#   project_name/query_annotation.gff         GFF format
#   project_name/cesar_alignment/             CESAR exon alignments

'''Parse TOGA loss summary to identify gene loss vs intact.'''
import pandas as pd


def load_toga_loss(loss_summary_path):
    '''loss_summary_data.tsv columns: TRANSCRIPT, STATUS, IS_INTACT, ...'''
    df = pd.read_csv(loss_summary_path, sep='\t')
    return df


def classify_genes(df):
    '''Standard TOGA classification: I/PI/UL/L/M/PM'''
    return df.groupby('STATUS')['TRANSCRIPT'].count()


def filter_high_confidence_intact(df):
    '''Filter to high-confidence intact (I) only. PI is partial-intact; L is Lost.'''
    return df[df['STATUS'] == 'I']

LiftOff for Pairwise Annotation Transfer

Goal: Transfer reference annotation to query genome via ortholog mapping.

Approach: Minimap2-based ortholog detection -> per-gene transfer.

# Standard LiftOff (verify flags with `liftoff --help`)
liftoff -g reference.gff \
    query.fa reference.fa \
    -o query.gff \
    -u unmapped.txt \
    -copies \
    -overlap 0.5 \
    -mismatch 2 \
    -gap 5 \
    -threads 16

# Output:
#   query.gff             Lifted annotations
#   unmapped.txt          Genes failed to lift

For closely related species, default settings suffice. For divergent (75-90% identity), use -mismatch 5 -gap 10. For tandem-rich regions, -copies allows multiple projections.

Comparative Annotation Toolkit (CAT)

# Setup
git clone https://github.com/ComparativeGenomicsToolkit/Comparative-Annotation-Toolkit
cd Comparative-Annotation-Toolkit && pip install .

# Edit config.yaml with reference + query genomes
# Then run Snakemake pipeline
snakemake --use-conda --cores 32 --configfile config.yaml

CAT integrates AUGUSTUS + LiftOff + TransMap; output is multi-species comparative annotation.

Reconciliation: When Methods Disagree

Operational rule for publication: TOGA + Cactus HAL for clade-level annotation (Zoonomia-style); LiftOff for pairwise transfer to closely related (<100 Myr); BRAKER3 / Funannotate for de novo where projection fails; manual review of TOGA "Lost" / "PI" calls.

Cohort Gotchas

• Plant comparative annotation: GENESPACE handles synteny-aware ortholog detection; project via plant-specific tools
• Bacterial annotation: different problem; use [[pangenome-analysis]] with Bakta consistent annotation
• Single-cell expression data: RNA-Seq evidence for projected genes essential
• Repetitive genes (MHC, OR): projection unreliable; use [[pangenome-analysis]] with PGR-TK
• Recently diverged strains: LiftOff with strict parameters; high accuracy
• Polyploid query: assign subgenomes first ([[whole-genome-duplication]])
• Distantly related to reference (>300 Myr): projection rate drops; consider de novo with comparative evidence
• Fragmented draft genomes: projection works on contigs but gene splits possible
• Reference annotation quality: verify BUSCO before propagating to all projections
• Non-canonical genomes (B chromosomes, supernumerary): typically excluded from projection

Anticipated Reviewer Pushback

Common Errors

Tool Installation Notes

# TOGA
conda env create -f https://raw.githubusercontent.com/hillerlab/TOGA/master/toga_env.yml
# Requires Nextflow and nf-core

# CESAR 2.0 (bundled with TOGA)
git clone https://github.com/hillerlab/CESAR2.0

# LiftOff
pip install liftoff

# UCSC liftOver
conda install -c bioconda ucsc-liftover

# Comparative Annotation Toolkit (CAT)
git clone https://github.com/ComparativeGenomicsToolkit/Comparative-Annotation-Toolkit
cd Comparative-Annotation-Toolkit && pip install .

# GeMoMa
wget https://gemoma.de/jcag/gemoma.zip && unzip gemoma.zip

# Comparative tools
conda install -c bioconda cactus busco compleasm

# De novo annotation (alternative)
conda install -c bioconda braker3 funannotate maker

For TOGA pipeline at vertebrate-scale, use Nextflow with proper HPC config (Slurm / Kubernetes); allocate >= 32 cores per genome.

References

• Kirilenko BM et al 2023 Science 380:eabn3107 (TOGA; Zoonomia + Bird10000 standard)
• Sharma V & Hiller M 2017 NAR 45:8369 (CESAR 2.0)
• Shumate A & Salzberg SL 2021 Bioinformatics 37(12):1639-1643 (LiftOff)
• Hickey G et al 2013 Bioinformatics 29:1341 (HAL toolkit)
• Keilwagen J et al 2019 Methods Mol Biol 1962:161 (GeMoMa)
• Brůna T et al 2024 NAR Genom Bioinform 6:lqae068 (BRAKER3)
• Cantarel BL et al 2008 Genome Res 18:188 (MAKER)
• Stanke M et al 2008 Bioinformatics 24:637 (AUGUSTUS)
• Diekhans M et al 2007 Nat Genet 39:583 (TransMap)
• Zhang Z et al 2006 Genome Res 16:1041 (PseudoPipe)
• Armstrong J et al 2020 Nature 587:246 (Progressive Cactus)
• Baertsch R et al 2008 Genome Res 18:1675 (RetroFinder)
• Liao W-W et al 2023 Nature 617:312 (HPRC draft pangenome; relevant context)
• Smith LP et al 2024 (Comparative Annotation Toolkit updates)
• Salzberg SL 2019 Bioinformatics 35:1844 (next-gen annotation pipelines)
• Comparative Genomics Toolkit (CGT) GitHub
• TimeTree (database) for divergence dates

Related Skills

• comparative-genomics/whole-genome-alignment - Cactus WGA precedes TOGA
• comparative-genomics/synteny-analysis - Synteny detection from WGA
• comparative-genomics/ortholog-inference - TOGA orthology classification
• comparative-genomics/pangenome-analysis - PGR-TK for repetitive / clinical genes
• comparative-genomics/whole-genome-duplication - Subgenome assignment for polyploid query
• genome-annotation/eukaryotic-gene-prediction - BRAKER3 / Funannotate de novo alternative
• genome-annotation/functional-annotation - Function assignment downstream
• genome-annotation/annotation-transfer - Related skill on annotation transfer mechanisms
• genome-annotation/prokaryotic-annotation - Bakta for prokaryote annotation
• read-qc/rnaseq-qc - RNA-Seq evidence to validate projected annotations
• read-alignment/star-alignment - RNA-Seq alignment for validation