Paludamentum is the coat of the emperor - evidence processing pipeline
Python
11
173 commits
updated Oct 11, 2026

$\color{lightgray}{\tiny\textsf{Logo generated by Gemini}}$
Authors: Lars Gabriel & Katharina J. Hoff
The paludamentum was the cloak worn by Roman emperors and commanders. This repository is the cloak around the emperors of the Gaius-Augustus gene finder family: a Nextflow pipeline that prepares extrinsic evidence (proteins, RNA-Seq, Iso-Seq), derives high-confidence genes from it, and integrates them with the ab initio predictions of the deep learning gene finder Tiberius or Vipsania.
The numbers in the figure are the steps below.
--result
and this step is skipped, see
Existing predictions.--stringtie instead of
the reads, see Existing StringTie assemblies.transdecoder: td1). ORFs that are supported by
protein homology (DIAMOND) and by the scored protein alignments become the
high-confidence (HC) gene set; a comparison of the ORF finders is in
docs/orf_finder_comparison.md.--busco_lineage), OMArk, a comparison with a
reference annotation (--reference_annotation), rRNA, tRNA, Rfam and
lncRNA genes (--ncrna) and GO terms with FANTASIA-Lite (--fantasia,
GPU). report.html sums it up. See
docs/postprocessing.md.Steps 4 and 5 run in one of three ways. The clade of the gene finder model and the inputs decide which (conf/hc_genes.yaml):
| HC genes (steps 4 and 5) | For | Proteins | Described in |
|---|---|---|---|
| TransDecoder flow: TD2 ORFs supported by the proteins | all other clades | required with reads | step 4 above |
| Drusilla flow with proteins: Drusilla ORFs, LightGBM filter and hint rescue of the ab initio genes | vertebrates, mammals | given | Drusilla flow |
| Drusilla flow without proteins: Drusilla ORFs merged with all ab initio genes | insects (recommended); any clade with a Drusilla model | not needed | Insects |
Without any evidence input the pipeline runs steps 1 and 6 only. That is useful to parallelize a gene finder over several GPUs.
Step 6 in detail: the color of a step says which data it needs, the label on it which option switches it on.
The pipeline runs with Singularity (or Apptainer): the gene finders and all tools run in container images that the pipeline pulls itself. You do not install HISAT2, miniprot, StringTie, Tiberius, Vipsania or any other tool.
You need:
git clone --recursive https://github.com/Gaius-Augustus/Paludamentum
cd Paludamentum
pip install -e .
This installs the launcher paludamentum. --recursive checks out the
submodules tiberius/, vipsania/ and drusilla/; in an existing clone run
git submodule update --init after git pull.
The first run pulls the images into ~/.cache/paludamentum/singularity,
later runs reuse them. Each gene finder image is about 9.4 GB, the image of
the evidence tools 0.6 GB. The images of BUSCO, FEELnc, OMArk and
FANTASIA-Lite are pulled only when their steps are switched on. On a cluster this directory must be on a file
system that the compute nodes can read; set NXF_SINGULARITY_CACHEDIR to
use another directory.
# Tiberius, ab initio only, parallelized over GPUs by Nextflow
paludamentum --nf_config slurm_generic --genome genome.fa --model_cfg eudicotyledons
# Tiberius with evidence, inputs from a params file
paludamentum --params_yaml params.yaml --nf_config slurm_generic
# Vipsania with evidence, inputs on the command line
paludamentum --genefinder vipsania --nf_config local --genome genome.fa --model Fungi \
--proteins proteins.faa --rnaseq_paired "/abs/path/rnaseq/*_{1,2}.fastq.gz"
# Tiberius with proteins and an existing StringTie assembly instead of reads
paludamentum --nf_config local --genome genome.fa --model_cfg eudicotyledons \
--proteins proteins.faa --stringtie stringtie.gtf
# Evidence for an existing Tiberius prediction (GFF3 or GTF); the gene finder does not run
paludamentum --nf_config local --genome genome.fa --result tiberius.gff3 \
--proteins proteins.faa --rnaseq_paired "/abs/path/rnaseq/*_{1,2}.fastq.gz"
--nf_config takes a path or the name of a config in conf/
(local, slurm_generic, ...); local sizes the tasks to the machine it
runs on, slurm_generic needs your GPU partition (see
Containers and HPC). Evidence can be given on the command line
(--proteins, --odb12Partitions, --rnaseq_paired, --rnaseq_single,
--isoseq, --stringtie, --rnaseq_sra_paired, --rnaseq_sra_single, --isoseq_sra) or
in the params file; command line values override the file. Useful options:
--dry_run writes the params file and validates inputs and executables
without starting Nextflow, --resume continues a previous run, --work_dir
sets the Nextflow work directory, --cleanup deletes the task directories of
the run from the work directory once it has finished successfully (see
docs/hpc.md). Arguments after -- go to Nextflow.
paludamentum --help lists everything.
Start from conf/parameters.yaml. Minimal example:
genome: /abs/path/genome.fa
proteins: /abs/path/proteins.faa
rnaseq_paired: "/abs/path/rnaseq/*_{1,2}.fastq.gz"
outdir: results
tiberius:
run: true
model_cfg: eudicotyledons
The launcher expands ~ and environment variables and resolves relative
paths against the launch directory, not against the params file; it writes
the merged parameters of a run with absolute paths to <outdir>/params.yaml.
Paths must not contain spaces. All parameters are documented in
docs/parameters.md.
| Parameter | Content |
|---|---|
genome | genome FASTA, optionally gzipped (required) |
tiberius.result, vipsania.result (--result) | existing prediction of the gene finder, GFF3 or GTF, used instead of running it, see Existing predictions |
proteins | one protein FASTA or a list; lists are concatenated |
odb12Partitions | OrthoDB v12 partitions to download: Metazoa, Vertebrata, Viridiplantae, Arthropoda, Fungi, Alveolata, Stramenopiles, Amoebozoa, Euglenozoa, Eukaryota |
rnaseq_paired, rnaseq_single | short read FASTQ files (glob or list) |
rnaseq_bam | aligned short reads, for example from VARUS |
stringtie | StringTie assembly (GTF) made outside the pipeline, one file, a list or a glob; instead of or in addition to reads, see Existing StringTie assemblies |
rnaseq_varus, isoseq_varus, mixed_varus | pyVARUS output directories, which bring their StringTie assembly and intron hints, see docs/parameters.md |
isoseq | Iso-Seq FASTQ files |
rnaseq_sra_paired, rnaseq_sra_single, isoseq_sra | SRA run accessions, downloaded by the pipeline; an accession whose download fails twice is dropped with an Error is ignored note, and -resume tries it again |
keep_downloads | copy the reads downloaded from SRA to sra_downloads/ in outdir; default false, they stay in the work directory only |
min_alignment_rate | libraries whose alignment rate (percent mapped) is below this value are dropped; default 80 |
The mode is inferred from the inputs and can be forced with mode
(--mode). A forced mode without its inputs is an error, and so is
transcript evidence without proteins outside the Drusilla flow:
| Mode | Inputs |
|---|---|
abinitio (historic name: tiberius) | genome only |
proteins | proteins |
rnaseq | short reads or a StringTie assembly, and proteins |
isoseq | Iso-Seq, and proteins |
mixed | short reads and Iso-Seq, and proteins |
The TransDecoder HC genes need protein evidence. The Drusilla flow
does not: for a clade with a Drusilla model in
conf/hc_genes.yaml (vertebrates, mammals, insects) the
proteins of the modes rnaseq, isoseq and mixed are optional.
If the transcripts are already assembled, pass the StringTie GTF with
--stringtie (stringtie in the params file). The pipeline then neither
maps reads nor runs StringTie for them; the assembly goes straight to the
HC gene step. Proteins are still required, except in the
Drusilla flow.
paludamentum --nf_config local --genome genome.fa --model_cfg eudicotyledons \
--proteins proteins.faa --stringtie stringtie.gtf
stringtie: /abs/path/stringtie.gtf # or a list, or a glob such as "/abs/path/*.gtf"
The assembly may come from short reads, Iso-Seq or both (stringtie --mix),
and it must be an assembly of this genome FASTA (same sequence names). It
combines with --result: an existing prediction and an existing assembly
need no GPU, no mapping and no assembly step. Notes:
hc: drusilla in conf/hc_genes.yaml) the Drusilla flow
runs, which filters transcripts by the coverage and TPM that StringTie
writes. It takes exactly one assembly of all reads and no other RNA-Seq
or Iso-Seq input, and the GTF must come from stringtie on the reads,
not from stringtie --merge (which drops coverage and TPM). Set
drusilla.run: false to merge several assemblies in the TransDecoder flow
instead.rnaseq, whatever reads
the assembly was made from. hintsfile.gff then has protein hints only
(none without proteins); intron hints from reads do not influence the
annotation.All files are written to outdir (default <genefinder>_results). <tool>
is tiberius or vipsania.
| File | Content |
|---|---|
<tool>_evidence.gff3 | final annotation: ab initio predictions merged with HC genes, sanity filtered, with UTRs in modes with transcripts |
<tool>_evidence.gtf | the final annotation as GTF |
<tool>_evidence_proteins.fa | protein sequences of all transcripts of the final annotation |
<tool>_evidence_cds.fa | coding sequences of the final annotation |
<tool>_ab_initio.gff3 | mode abinitio only: the final annotation (sanity filtered, with .gtf, _proteins.fa and _cds.fa as above) |
<tool>_evidence_with_ncRNA.gff3 | final annotation plus rRNA, tRNA, Rfam and lncRNA genes (ncrna.run) |
<tool>_evidence_go.gff3, <tool>_evidence_with_ncRNA_go.gff3 | the same with GO terms (fantasia.run) |
report.html | methods, gene set statistics, completeness, evidence support, sanity filter, UTRs, ncRNA, versions and references of the run |
qc/ | sanity filter and UTR reports, gene set statistics and plots, hint support, completeness, OMArk, gffcompare, FANTASIA, software versions, see docs/postprocessing.md |
ncrna/ | rRNA, tRNA, Rfam and lncRNA annotations (ncrna.run) |
intermediate/<tool>_ab_initio.gff3 | ab initio predictions before the sanity filter, in every mode; the file to give to --result of a later run |
intermediate/<tool>_merged.gff3 | ab initio predictions merged with the HC genes, before the sanity filter |
intermediate/<stem>_sanity_filtered.gff3 | the annotation after the sanity filter, before the UTRs |
intermediate/hc.gff3 | high-confidence genes derived from the evidence (TransDecoder) |
intermediate/drusilla_orfs.gtf | Drusilla ORFs, the HC genes of the Drusilla flow |
intermediate/<tool>_lgb_filtered.gtf | ab initio predictions kept by the LightGBM filter (Drusilla flow) |
intermediate/<tool>_lgb_scores.tsv | LightGBM class probabilities of all ab initio transcripts (Drusilla flow) |
intermediate/hint_rescue.gtf | ab initio genes predicted again with protein hints (Drusilla flow; missing if the rescue was skipped) |
hintsfile.gff | protein, RNA-Seq and Iso-Seq hints |
sra_downloads/ | reads downloaded from SRA, with keep_downloads: true only |
params.yaml | the merged parameters of this run, written by the launcher |
citations.md | references of the gene finder and the tools that this run used, see Citation |
methods.md | a methods section for this run: the steps that ran, their main parameters and inline citations of citations.md, see Citation |
Nextflow's timeline, trace and report files are written as well.
--genefinder tiberius|vipsania selects the gene finder. Without it, the
launcher takes genefinder from the params file, else the block with
run: true, else Vipsania if --model is given, else Tiberius. Only one
gene finder runs per pipeline run.
| Gene finder | Model | Parameters |
|---|---|---|
| Tiberius | --model_cfg, a name in tiberius/model_cfg of the submodule (for example eudicotyledons) or a path | docs/parameters.md |
| Vipsania | --model, a clade name (for example Fungi) or a model id | docs/vipsania.md |
Model weights are downloaded once on the submitting host, so the GPU nodes
need no internet; model_dir takes weights that you downloaded yourself.
Vipsania finetuning on the target genome is off by default (--finetune).
If the genome is already annotated with Tiberius or Vipsania, give that
file to the pipeline instead of predicting again. The file may be the GFF3
or the GTF that tiberius.py or vipsania annotate wrote, or the
intermediate/<tool>_ab_initio.gff3 of an earlier Paludamentum run (the
predictions before the sanity filter; <tool>_ab_initio.gff3 in the output
directory of mode abinitio is the filtered final annotation). It must
belong to the genome FASTA of this run (same sequence names).
# Tiberius prediction
paludamentum --nf_config local --genome genome.fa --result tiberius.gff3 \
--proteins proteins.faa --rnaseq_paired "/abs/path/rnaseq/*_{1,2}.fastq.gz"
# Vipsania prediction
paludamentum --genefinder vipsania --nf_config local --genome genome.fa --result vipsania.gff \
--proteins proteins.faa --isoseq isoseq.fastq.gz
In a params file the option is result in the block of the gene finder:
tiberius:
run: true
result: /abs/path/tiberius.gff3
All other steps run as usual, and the outputs are the same as in a run that predicts itself. No model option is needed, and the gene finder does not run. Notes:
--genefinder names the gene finder that made the file (default:
Tiberius). It sets the names of the output files (tiberius_*,
vipsania_*).--model_cfg vertebrates for Tiberius, --model Vertebrata or
--model Insecta for Vipsania). The model is not run; it tells the pipeline to use the
Drusilla flow. Without it, runs with transcripts use the
TransDecoder HC genes. The hint rescue of the Drusilla flow runs Tiberius
on a GPU; all other steps of a run with --result need no GPU.gene_000001, gene_000001.t1, ...) and reads its exon, CDS and UTR
features.For vertebrate, mammal and insect gene finder models (clades with
hc: drusilla in conf/hc_genes.yaml), runs with
transcripts take another route through steps 4 and 5 of the overview:
Drusilla ORFs replace the TransDecoder HC genes. With protein evidence,
vertebrates and mammals also get a LightGBM filter of the ab initio
predictions, and Tiberius predicts partial genes again with protein hints.
The gene-level F1 is 80.70 on Takifugu rubripes with the Tiberius
vertebrates model (Paludamentum 0.5.0, gffcompare 0.12.10) and 79.71 on
Bos taurus with mammalia_softmasking_v2 (Paludamentum 0.4.0). The flow is
switched on automatically (drusilla.run: auto). Conditions, steps,
parameters and known issues are in docs/drusilla_flow.md.
The figure shows steps 3 to 5 of the overview for vertebrates and mammals with proteins; its numbers count the steps of this flow.
For insects, Paludamentum recommends RNA-Seq or Iso-Seq reads, Vipsania with
the model Insecta fine-tuned on the genome, and no protein evidence:
paludamentum --nf_config local --genome genome.fa --model Insecta --finetune \
--rnaseq_bam rnaseq.bam
The run then goes through the steps of the overview as follows; the numbers in the figure are those of the overview.
Insecta model on the
genome, then annotates the genome with it. This is one GPU task on the
whole genome (about 4 h on an A100), not one task per genome chunk.intermediate/drusilla_orfs.gtf).vipsania_evidence.gff3.On 11 insect genomes this flow reached a mean gene F1 of 75.2, as BRAKER3 with proteins (75.4), and more than Drusilla with Tiberius (66.0), Vipsania alone (60.4) or Tiberius alone (57.6) (evaluation of Lars Gabriel, gffcompare 0.12.10, see docs/drusilla_flow.md). On Drosophila melanogaster and Bombyx mori Paludamentum gives the same as his standalone merge, 84.88 and 74.12 against 84.49 and 73.85.
An insect run that differs from this flow still runs, but the Nextflow log
warns and names each difference: Tiberius instead of Vipsania (also the
Tiberius insecta and lepidoptera models, which run the Drusilla flow
too), Vipsania without fine-tuning, no RNA-Seq or Iso-Seq, or protein
evidence (then the ORFs get the codon fix, but there is still no LightGBM
filter). The recommendation is recommended of the clade Insecta in
conf/hc_genes.yaml.
The images are pinned in conf/base.config and listed in docs/containers.md.
--nf_config takes a path or the name of a config in conf/:
local runs everything on one machine, slurm_generic is a starting point
for SLURM. For your own cluster, copy
conf/user_hpc_template.config and set your
queues, GPU options and scratch paths, see docs/hpc.md.
Downloads (SRA reads, OrthoDB partitions, model weights, BUSCO lineages,
Rfam, the NCBI taxonomy for OMArk) run on the submitting host, which needs
internet access.
Running without containers, and other setups for experts, are described in docs/advanced_setup.md.
| Page | Content |
|---|---|
| docs/parameters.md | all parameters: inputs, gene finder blocks, Drusilla flow, mode |
| docs/vipsania.md | Vipsania as gene finder: models, finetuning, offline nodes |
| docs/drusilla_flow.md | Drusilla flow for vertebrate and insect models, with and without proteins: conditions, steps, known issues |
| docs/postprocessing.md | post-processing and quality control: sanity filter, UTRs, GFF3 contract, completeness, ncRNA, GO terms, report |
| docs/containers.md | container images and how they are pinned |
| docs/hpc.md | Nextflow config for your cluster, process labels |
| docs/advanced_setup.md | for experts: running without containers, location of the checkout |
| docs/orf_finder_comparison.md | TransDecoder, TD2 and Drusilla as ORF finder of the HC gene step |
| docs/hint_rescue_comparison.md | hint rescue compared with the original scripts |
| docs/development.md | submodules and status, repository layout, notes for maintainers, testing, roadmap |
Artistic License 1.0, see LICENSE, with three exceptions, each marked in the header of the file:
bin/ copied from Tiberius stay under its MIT License, see
LICENSE-Tiberius.bin/ copied or ported from BRAKER4 stay under its MIT License,
see LICENSE-BRAKER4.bin/fantasia_generate_embeddings.py is derived from
FANTASIA-Lite and is under the GNU
Affero General Public License v3.0, see
LICENSE-FANTASIA-Lite. It is only used when
--fantasia is on, where it is bound into the FANTASIA-Lite container.Every run writes citations.md to outdir. It lists the references of the
gene finder and of the tools that this run used, selected from its inputs and
parameters. Please cite them in a publication that uses the results.
methods.md next to it describes, in the style of a Methods section and in
the order of execution, what the run did (mode, gene finder and model,
evidence processing, high-confidence genes, post-processing, quality control,
ncRNA and GO terms as switched on), with inline citations of the references
in citations.md. report.html shows it as well. Check and adapt the text
before you use it in a publication.
Pipeline and gene finders
Protein evidence
Transcript evidence
High-confidence genes
Post-processing and quality control
Funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation), project number 552910312: "AI-GUSTUS: Eine cloud-native Pipeline für genaue Genom-Annotation" (AI-GUSTUS: a cloud-native pipeline for accurate genome annotation).
Paludamentum is the coat of the emperor - evidence processing pipeline
Python
11
173 commits
updated Oct 11, 2026

$\color{lightgray}{\tiny\textsf{Logo generated by Gemini}}$
Authors: Lars Gabriel & Katharina J. Hoff
The paludamentum was the cloak worn by Roman emperors and commanders. This repository is the cloak around the emperors of the Gaius-Augustus gene finder family: a Nextflow pipeline that prepares extrinsic evidence (proteins, RNA-Seq, Iso-Seq), derives high-confidence genes from it, and integrates them with the ab initio predictions of the deep learning gene finder Tiberius or Vipsania.
The numbers in the figure are the steps below.
--result
and this step is skipped, see
Existing predictions.--stringtie instead of
the reads, see Existing StringTie assemblies.transdecoder: td1). ORFs that are supported by
protein homology (DIAMOND) and by the scored protein alignments become the
high-confidence (HC) gene set; a comparison of the ORF finders is in
docs/orf_finder_comparison.md.--busco_lineage), OMArk, a comparison with a
reference annotation (--reference_annotation), rRNA, tRNA, Rfam and
lncRNA genes (--ncrna) and GO terms with FANTASIA-Lite (--fantasia,
GPU). report.html sums it up. See
docs/postprocessing.md.Steps 4 and 5 run in one of three ways. The clade of the gene finder model and the inputs decide which (conf/hc_genes.yaml):
| HC genes (steps 4 and 5) | For | Proteins | Described in |
|---|---|---|---|
| TransDecoder flow: TD2 ORFs supported by the proteins | all other clades | required with reads | step 4 above |
| Drusilla flow with proteins: Drusilla ORFs, LightGBM filter and hint rescue of the ab initio genes | vertebrates, mammals | given | Drusilla flow |
| Drusilla flow without proteins: Drusilla ORFs merged with all ab initio genes | insects (recommended); any clade with a Drusilla model | not needed | Insects |
Without any evidence input the pipeline runs steps 1 and 6 only. That is useful to parallelize a gene finder over several GPUs.
Step 6 in detail: the color of a step says which data it needs, the label on it which option switches it on.
The pipeline runs with Singularity (or Apptainer): the gene finders and all tools run in container images that the pipeline pulls itself. You do not install HISAT2, miniprot, StringTie, Tiberius, Vipsania or any other tool.
You need:
git clone --recursive https://github.com/Gaius-Augustus/Paludamentum
cd Paludamentum
pip install -e .
This installs the launcher paludamentum. --recursive checks out the
submodules tiberius/, vipsania/ and drusilla/; in an existing clone run
git submodule update --init after git pull.
The first run pulls the images into ~/.cache/paludamentum/singularity,
later runs reuse them. Each gene finder image is about 9.4 GB, the image of
the evidence tools 0.6 GB. The images of BUSCO, FEELnc, OMArk and
FANTASIA-Lite are pulled only when their steps are switched on. On a cluster this directory must be on a file
system that the compute nodes can read; set NXF_SINGULARITY_CACHEDIR to
use another directory.
# Tiberius, ab initio only, parallelized over GPUs by Nextflow
paludamentum --nf_config slurm_generic --genome genome.fa --model_cfg eudicotyledons
# Tiberius with evidence, inputs from a params file
paludamentum --params_yaml params.yaml --nf_config slurm_generic
# Vipsania with evidence, inputs on the command line
paludamentum --genefinder vipsania --nf_config local --genome genome.fa --model Fungi \
--proteins proteins.faa --rnaseq_paired "/abs/path/rnaseq/*_{1,2}.fastq.gz"
# Tiberius with proteins and an existing StringTie assembly instead of reads
paludamentum --nf_config local --genome genome.fa --model_cfg eudicotyledons \
--proteins proteins.faa --stringtie stringtie.gtf
# Evidence for an existing Tiberius prediction (GFF3 or GTF); the gene finder does not run
paludamentum --nf_config local --genome genome.fa --result tiberius.gff3 \
--proteins proteins.faa --rnaseq_paired "/abs/path/rnaseq/*_{1,2}.fastq.gz"
--nf_config takes a path or the name of a config in conf/
(local, slurm_generic, ...); local sizes the tasks to the machine it
runs on, slurm_generic needs your GPU partition (see
Containers and HPC). Evidence can be given on the command line
(--proteins, --odb12Partitions, --rnaseq_paired, --rnaseq_single,
--isoseq, --stringtie, --rnaseq_sra_paired, --rnaseq_sra_single, --isoseq_sra) or
in the params file; command line values override the file. Useful options:
--dry_run writes the params file and validates inputs and executables
without starting Nextflow, --resume continues a previous run, --work_dir
sets the Nextflow work directory, --cleanup deletes the task directories of
the run from the work directory once it has finished successfully (see
docs/hpc.md). Arguments after -- go to Nextflow.
paludamentum --help lists everything.
Start from conf/parameters.yaml. Minimal example:
genome: /abs/path/genome.fa
proteins: /abs/path/proteins.faa
rnaseq_paired: "/abs/path/rnaseq/*_{1,2}.fastq.gz"
outdir: results
tiberius:
run: true
model_cfg: eudicotyledons
The launcher expands ~ and environment variables and resolves relative
paths against the launch directory, not against the params file; it writes
the merged parameters of a run with absolute paths to <outdir>/params.yaml.
Paths must not contain spaces. All parameters are documented in
docs/parameters.md.
| Parameter | Content |
|---|---|
genome | genome FASTA, optionally gzipped (required) |
tiberius.result, vipsania.result (--result) | existing prediction of the gene finder, GFF3 or GTF, used instead of running it, see Existing predictions |
proteins | one protein FASTA or a list; lists are concatenated |
odb12Partitions | OrthoDB v12 partitions to download: Metazoa, Vertebrata, Viridiplantae, Arthropoda, Fungi, Alveolata, Stramenopiles, Amoebozoa, Euglenozoa, Eukaryota |
rnaseq_paired, rnaseq_single | short read FASTQ files (glob or list) |
rnaseq_bam | aligned short reads, for example from VARUS |
stringtie | StringTie assembly (GTF) made outside the pipeline, one file, a list or a glob; instead of or in addition to reads, see Existing StringTie assemblies |
rnaseq_varus, isoseq_varus, mixed_varus | pyVARUS output directories, which bring their StringTie assembly and intron hints, see docs/parameters.md |
isoseq | Iso-Seq FASTQ files |
rnaseq_sra_paired, rnaseq_sra_single, isoseq_sra | SRA run accessions, downloaded by the pipeline; an accession whose download fails twice is dropped with an Error is ignored note, and -resume tries it again |
keep_downloads | copy the reads downloaded from SRA to sra_downloads/ in outdir; default false, they stay in the work directory only |
min_alignment_rate | libraries whose alignment rate (percent mapped) is below this value are dropped; default 80 |
The mode is inferred from the inputs and can be forced with mode
(--mode). A forced mode without its inputs is an error, and so is
transcript evidence without proteins outside the Drusilla flow:
| Mode | Inputs |
|---|---|
abinitio (historic name: tiberius) | genome only |
proteins | proteins |
rnaseq | short reads or a StringTie assembly, and proteins |
isoseq | Iso-Seq, and proteins |
mixed | short reads and Iso-Seq, and proteins |
The TransDecoder HC genes need protein evidence. The Drusilla flow
does not: for a clade with a Drusilla model in
conf/hc_genes.yaml (vertebrates, mammals, insects) the
proteins of the modes rnaseq, isoseq and mixed are optional.
If the transcripts are already assembled, pass the StringTie GTF with
--stringtie (stringtie in the params file). The pipeline then neither
maps reads nor runs StringTie for them; the assembly goes straight to the
HC gene step. Proteins are still required, except in the
Drusilla flow.
paludamentum --nf_config local --genome genome.fa --model_cfg eudicotyledons \
--proteins proteins.faa --stringtie stringtie.gtf
stringtie: /abs/path/stringtie.gtf # or a list, or a glob such as "/abs/path/*.gtf"
The assembly may come from short reads, Iso-Seq or both (stringtie --mix),
and it must be an assembly of this genome FASTA (same sequence names). It
combines with --result: an existing prediction and an existing assembly
need no GPU, no mapping and no assembly step. Notes:
hc: drusilla in conf/hc_genes.yaml) the Drusilla flow
runs, which filters transcripts by the coverage and TPM that StringTie
writes. It takes exactly one assembly of all reads and no other RNA-Seq
or Iso-Seq input, and the GTF must come from stringtie on the reads,
not from stringtie --merge (which drops coverage and TPM). Set
drusilla.run: false to merge several assemblies in the TransDecoder flow
instead.rnaseq, whatever reads
the assembly was made from. hintsfile.gff then has protein hints only
(none without proteins); intron hints from reads do not influence the
annotation.All files are written to outdir (default <genefinder>_results). <tool>
is tiberius or vipsania.
| File | Content |
|---|---|
<tool>_evidence.gff3 | final annotation: ab initio predictions merged with HC genes, sanity filtered, with UTRs in modes with transcripts |
<tool>_evidence.gtf | the final annotation as GTF |
<tool>_evidence_proteins.fa | protein sequences of all transcripts of the final annotation |
<tool>_evidence_cds.fa | coding sequences of the final annotation |
<tool>_ab_initio.gff3 | mode abinitio only: the final annotation (sanity filtered, with .gtf, _proteins.fa and _cds.fa as above) |
<tool>_evidence_with_ncRNA.gff3 | final annotation plus rRNA, tRNA, Rfam and lncRNA genes (ncrna.run) |
<tool>_evidence_go.gff3, <tool>_evidence_with_ncRNA_go.gff3 | the same with GO terms (fantasia.run) |
report.html | methods, gene set statistics, completeness, evidence support, sanity filter, UTRs, ncRNA, versions and references of the run |
qc/ | sanity filter and UTR reports, gene set statistics and plots, hint support, completeness, OMArk, gffcompare, FANTASIA, software versions, see docs/postprocessing.md |
ncrna/ | rRNA, tRNA, Rfam and lncRNA annotations (ncrna.run) |
intermediate/<tool>_ab_initio.gff3 | ab initio predictions before the sanity filter, in every mode; the file to give to --result of a later run |
intermediate/<tool>_merged.gff3 | ab initio predictions merged with the HC genes, before the sanity filter |
intermediate/<stem>_sanity_filtered.gff3 | the annotation after the sanity filter, before the UTRs |
intermediate/hc.gff3 | high-confidence genes derived from the evidence (TransDecoder) |
intermediate/drusilla_orfs.gtf | Drusilla ORFs, the HC genes of the Drusilla flow |
intermediate/<tool>_lgb_filtered.gtf | ab initio predictions kept by the LightGBM filter (Drusilla flow) |
intermediate/<tool>_lgb_scores.tsv | LightGBM class probabilities of all ab initio transcripts (Drusilla flow) |
intermediate/hint_rescue.gtf | ab initio genes predicted again with protein hints (Drusilla flow; missing if the rescue was skipped) |
hintsfile.gff | protein, RNA-Seq and Iso-Seq hints |
sra_downloads/ | reads downloaded from SRA, with keep_downloads: true only |
params.yaml | the merged parameters of this run, written by the launcher |
citations.md | references of the gene finder and the tools that this run used, see Citation |
methods.md | a methods section for this run: the steps that ran, their main parameters and inline citations of citations.md, see Citation |
Nextflow's timeline, trace and report files are written as well.
--genefinder tiberius|vipsania selects the gene finder. Without it, the
launcher takes genefinder from the params file, else the block with
run: true, else Vipsania if --model is given, else Tiberius. Only one
gene finder runs per pipeline run.
| Gene finder | Model | Parameters |
|---|---|---|
| Tiberius | --model_cfg, a name in tiberius/model_cfg of the submodule (for example eudicotyledons) or a path | docs/parameters.md |
| Vipsania | --model, a clade name (for example Fungi) or a model id | docs/vipsania.md |
Model weights are downloaded once on the submitting host, so the GPU nodes
need no internet; model_dir takes weights that you downloaded yourself.
Vipsania finetuning on the target genome is off by default (--finetune).
If the genome is already annotated with Tiberius or Vipsania, give that
file to the pipeline instead of predicting again. The file may be the GFF3
or the GTF that tiberius.py or vipsania annotate wrote, or the
intermediate/<tool>_ab_initio.gff3 of an earlier Paludamentum run (the
predictions before the sanity filter; <tool>_ab_initio.gff3 in the output
directory of mode abinitio is the filtered final annotation). It must
belong to the genome FASTA of this run (same sequence names).
# Tiberius prediction
paludamentum --nf_config local --genome genome.fa --result tiberius.gff3 \
--proteins proteins.faa --rnaseq_paired "/abs/path/rnaseq/*_{1,2}.fastq.gz"
# Vipsania prediction
paludamentum --genefinder vipsania --nf_config local --genome genome.fa --result vipsania.gff \
--proteins proteins.faa --isoseq isoseq.fastq.gz
In a params file the option is result in the block of the gene finder:
tiberius:
run: true
result: /abs/path/tiberius.gff3
All other steps run as usual, and the outputs are the same as in a run that predicts itself. No model option is needed, and the gene finder does not run. Notes:
--genefinder names the gene finder that made the file (default:
Tiberius). It sets the names of the output files (tiberius_*,
vipsania_*).--model_cfg vertebrates for Tiberius, --model Vertebrata or
--model Insecta for Vipsania). The model is not run; it tells the pipeline to use the
Drusilla flow. Without it, runs with transcripts use the
TransDecoder HC genes. The hint rescue of the Drusilla flow runs Tiberius
on a GPU; all other steps of a run with --result need no GPU.gene_000001, gene_000001.t1, ...) and reads its exon, CDS and UTR
features.For vertebrate, mammal and insect gene finder models (clades with
hc: drusilla in conf/hc_genes.yaml), runs with
transcripts take another route through steps 4 and 5 of the overview:
Drusilla ORFs replace the TransDecoder HC genes. With protein evidence,
vertebrates and mammals also get a LightGBM filter of the ab initio
predictions, and Tiberius predicts partial genes again with protein hints.
The gene-level F1 is 80.70 on Takifugu rubripes with the Tiberius
vertebrates model (Paludamentum 0.5.0, gffcompare 0.12.10) and 79.71 on
Bos taurus with mammalia_softmasking_v2 (Paludamentum 0.4.0). The flow is
switched on automatically (drusilla.run: auto). Conditions, steps,
parameters and known issues are in docs/drusilla_flow.md.
The figure shows steps 3 to 5 of the overview for vertebrates and mammals with proteins; its numbers count the steps of this flow.
For insects, Paludamentum recommends RNA-Seq or Iso-Seq reads, Vipsania with
the model Insecta fine-tuned on the genome, and no protein evidence:
paludamentum --nf_config local --genome genome.fa --model Insecta --finetune \
--rnaseq_bam rnaseq.bam
The run then goes through the steps of the overview as follows; the numbers in the figure are those of the overview.
Insecta model on the
genome, then annotates the genome with it. This is one GPU task on the
whole genome (about 4 h on an A100), not one task per genome chunk.intermediate/drusilla_orfs.gtf).vipsania_evidence.gff3.On 11 insect genomes this flow reached a mean gene F1 of 75.2, as BRAKER3 with proteins (75.4), and more than Drusilla with Tiberius (66.0), Vipsania alone (60.4) or Tiberius alone (57.6) (evaluation of Lars Gabriel, gffcompare 0.12.10, see docs/drusilla_flow.md). On Drosophila melanogaster and Bombyx mori Paludamentum gives the same as his standalone merge, 84.88 and 74.12 against 84.49 and 73.85.
An insect run that differs from this flow still runs, but the Nextflow log
warns and names each difference: Tiberius instead of Vipsania (also the
Tiberius insecta and lepidoptera models, which run the Drusilla flow
too), Vipsania without fine-tuning, no RNA-Seq or Iso-Seq, or protein
evidence (then the ORFs get the codon fix, but there is still no LightGBM
filter). The recommendation is recommended of the clade Insecta in
conf/hc_genes.yaml.
The images are pinned in conf/base.config and listed in docs/containers.md.
--nf_config takes a path or the name of a config in conf/:
local runs everything on one machine, slurm_generic is a starting point
for SLURM. For your own cluster, copy
conf/user_hpc_template.config and set your
queues, GPU options and scratch paths, see docs/hpc.md.
Downloads (SRA reads, OrthoDB partitions, model weights, BUSCO lineages,
Rfam, the NCBI taxonomy for OMArk) run on the submitting host, which needs
internet access.
Running without containers, and other setups for experts, are described in docs/advanced_setup.md.
| Page | Content |
|---|---|
| docs/parameters.md | all parameters: inputs, gene finder blocks, Drusilla flow, mode |
| docs/vipsania.md | Vipsania as gene finder: models, finetuning, offline nodes |
| docs/drusilla_flow.md | Drusilla flow for vertebrate and insect models, with and without proteins: conditions, steps, known issues |
| docs/postprocessing.md | post-processing and quality control: sanity filter, UTRs, GFF3 contract, completeness, ncRNA, GO terms, report |
| docs/containers.md | container images and how they are pinned |
| docs/hpc.md | Nextflow config for your cluster, process labels |
| docs/advanced_setup.md | for experts: running without containers, location of the checkout |
| docs/orf_finder_comparison.md | TransDecoder, TD2 and Drusilla as ORF finder of the HC gene step |
| docs/hint_rescue_comparison.md | hint rescue compared with the original scripts |
| docs/development.md | submodules and status, repository layout, notes for maintainers, testing, roadmap |
Artistic License 1.0, see LICENSE, with three exceptions, each marked in the header of the file:
bin/ copied from Tiberius stay under its MIT License, see
LICENSE-Tiberius.bin/ copied or ported from BRAKER4 stay under its MIT License,
see LICENSE-BRAKER4.bin/fantasia_generate_embeddings.py is derived from
FANTASIA-Lite and is under the GNU
Affero General Public License v3.0, see
LICENSE-FANTASIA-Lite. It is only used when
--fantasia is on, where it is bound into the FANTASIA-Lite container.Every run writes citations.md to outdir. It lists the references of the
gene finder and of the tools that this run used, selected from its inputs and
parameters. Please cite them in a publication that uses the results.
methods.md next to it describes, in the style of a Methods section and in
the order of execution, what the run did (mode, gene finder and model,
evidence processing, high-confidence genes, post-processing, quality control,
ncRNA and GO terms as switched on), with inline citations of the references
in citations.md. report.html shows it as well. Check and adapt the text
before you use it in a publication.
Pipeline and gene finders
Protein evidence
Transcript evidence
High-confidence genes
Post-processing and quality control
Funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation), project number 552910312: "AI-GUSTUS: Eine cloud-native Pipeline für genaue Genom-Annotation" (AI-GUSTUS: a cloud-native pipeline for accurate genome annotation).