AnnotationQC

Snakemake workflow to generate QC metric tables for gff3 or gtf formatted genome annotation files.

Metrics

• Completeness (BUSCO) — assessed with compleasm at both the protein and transcript level, with score busco_score = 1 - (missing / total) (Missing BUSCOs / total in the lineage). Protein level runs compleasm protein; transcript level runs compleasm run on the extracted transcript FASTA. → results/qc/busco_completeness.tsv

• Structure & length (AGAT) — AGAT agat_sp_statistics.pl reports gene/transcript/exon/CDS/intron/UTR counts, per-gene and per-transcript ratios, feature-length distributions, and UTR presence, per biotype and for both the all-isoform and one-per-gene views. → results/qc/annotation_stats.tsv (tidy long form: annotation_id, feature_type, isoform_set, metric, value)

• Coding integrity (psauron) — psauron scores each CDS for being a real protein-coding sequence. The annotation-level score is the percentage of CDS classified as protein. → results/qc/psauron_scores.tsv, plus the per-transcript scoring table results/psauron/<annotation_id>_psauron_score.csv

Input validation (before any metric)

Each annotation is validated up front, and the workflow halts loudly on any failure (so no misleading numbers are produced). Validation runs on — and the metrics then use — the original annotation; nothing is rewritten.

• gt gff3validator (GenomeTools) — strict GFF3 syntax: malformed records, invalid coordinates, dangling Parent references, etc.
• Custom checks vs the genome — every seqid is present in the genome FASTA; every feature lies within 1..sequence_length; every CDS has a valid phase (0/1/2); required feature types are present (CDS, exon, mRNA/transcript).

Per-annotation reports go to results/validated/<id>_validation_report.txt, summarized in results/qc/validation_summary.tsv. Setting agat_advisory: true adds a non-fatal report of what AGAT's standardizer would change/drop (AGAT is not used to rewrite the annotation).

Layout

config/config.yaml            workflow settings
annotations.tsv               samplesheet: annotations to QC (+ their genomes)
workflow/Snakefile            entry point
workflow/rules/*.smk          rules (extract_sequences, compleasm, agat_stats, psauron)
workflow/envs/*.yml           per-tool conda environments
workflow/scripts/             helper/parsing scripts
profiles/slurm/config.yaml    per-rule threads/resources
my_runner.sh                  SLURM submission script (Cannon)

Configuration

1. annotations.tsv — one row per annotation, tab-separated:

   column	meaning
   annotation_id	short unique label (used in output)
   annotation_path	path to the gff3 or gtf annotation
   genome_path	genome FASTA the annotation was built on

   The annotation must contain CDS features (needed for protein/CDS extraction).

2. config/config.yaml

   • busco_lineage — BUSCO clade name, e.g. tetrapoda (see compleasm list --remote)
   • compleasm_odb — OrthoDB release (compleasm 0.2.8 default: odb12)
   • busco_downloads_dir — where the lineage database is stored/reused
   • extract_tool — gffread (default) or agat for sequence extraction
   • psauron_use_gpu / psauron_gpu_partition / psauron_gpus — see below
   • agat_advisory — true adds a non-fatal report of what AGAT would change (default false)

Running (Cannon)

Requires a global cannon Snakemake profile in $HOME/.config/snakemake/cannon/ and a conda environment containing Snakemake (referenced in my_runner.sh).

sbatch my_runner.sh

Running psauron on GPU (optional)

psauron's model runs far faster on a GPU. It is CPU-only by default so the workflow works everywhere. To use a GPU:

1. In config/config.yaml set psauron_use_gpu: true, psauron_gpu_partition to a partition you can access (Cannon: gpu, gpu_requeue, gpu_test, seas_gpu), and psauron_gpus (usually 1). The psauron job is then submitted to that partition with --gpus=N.
2. Because --use-conda builds environments on the (CPU) submit node, export CONDA_OVERRIDE_CUDA=12.4 (match your GPU's supported CUDA) before launching so the CUDA build of pytorch is selected for envs/psauron_gpu.yml. No module load cuda is needed — the conda package bundles the CUDA runtime.

CPU-only users leave psauron_use_gpu: false; nothing GPU-related is built or requested.

Output

Three QC tables under results/qc/:

file	contents
validation_summary.tsv	per annotation_id: validation result + features scanned
busco_completeness.tsv	one row per annotation_id × level (protein/transcript)
annotation_stats.tsv	tidy long AGAT metrics per annotation_id × biotype × isoform view
psauron_scores.tsv	one row per annotation_id: psauron score + CDS counts