/prokka-genome-annotation

name: "prokka-genome-annotation"
description: "Annotate prokaryotic genomes (bacteria, archaea, viruses) via Prokka's BLAST/HMM pipeline. Identifies CDS, rRNA, tRNA, tmRNA, signal peptides against Pfam, TIGRFAMs, RefSeq. Outputs GFF3, GenBank, FASTA, TSV. Use PGAP for NCBI GenBank submission; Bakta for faster NCBI-compatible annotation."
license: "GPL-3.0"

Prokka Genome Annotation

Overview

Prokka is a command-line pipeline for rapid annotation of prokaryotic genomes (bacteria, archaea, and viruses). It uses a tiered search strategy: protein-coding genes (CDS) are predicted with Prodigal and searched first against a genus-specific database, then RefSeq proteins, then Pfam/TIGRFAMs HMMs. Non-coding RNA genes (rRNA, tRNA, tmRNA) are identified with Barrnap, Aragorn, and Infernal. Prokka processes a single FASTA assembly in minutes and outputs a comprehensive annotation in GFF3, GenBank, FASTA, and tabular formats.

When to Use

• Annotating a newly assembled bacterial or archaeal genome from Illumina, PacBio, or Nanopore assemblies
• Getting functional protein annotations (CDS with product names, EC numbers, GO terms) from a draft or complete genome
• Preparing annotation files for downstream comparative genomics (Roary pan-genome, OrthoFinder)
• Annotating viral or phage genomes when kingdom-specific databases are important
• Performing metagenome-assembled genome (MAG) annotation with the `--metagenome` flag
• Parsing annotated outputs in Python with BioPython for downstream sequence or feature analysis
• Use **PGAP** (NCBI Prokaryotic Genome Annotation Pipeline) instead when the goal is NCBI GenBank submission with standards compliance
• Use **Bakta** instead for faster annotation with built-in NCBI-compatible outputs and a more regularly updated database

Prerequisites

• **Software**: Prokka ≥ 1.14, Perl 5, Prodigal, Barrnap, HMMER3, BLAST+, Aragorn, Infernal, tbl2asn
• **Python packages** (for output parsing): `biopython`, `pandas`, `matplotlib`
• **Input**: assembled genome in FASTA format (complete or draft with multiple contigs)
• **Environment**: conda strongly recommended to handle the Perl and C dependency stack

> **Check before installing**: The tool may already be available in the current environment (e.g., inside a `pixi` / `conda` env). Run `command -v prokka` first and skip the install commands below if it returns a path. When running inside a pixi project, invoke the tool via `pixi run prokka` rather than bare `prokka`.

# Install Prokka via conda/mamba (recommended)
conda install -c conda-forge -c bioconda prokka

# Or with mamba (faster)
mamba install -c conda-forge -c bioconda prokka

# Verify installation and database setup
prokka --version
# prokka 1.14.6

# Check that required tools are on PATH
prokka --depends
# prokka needs: awk, sed, grep, makeblastdb, blastp, hmmscan, ...

# Install Python parsing dependencies
pip install biopython pandas matplotlib

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: kingdom
    kind: required
    source: user
    ask: "Is this a bacterial, archaeal, viral, or mitochondrial assembly?"
    default: "Bacteria"

  - id: D2
    param: organismMetadata
    kind: required
    source: user
    ask: "Which genus, species, and strain should be recorded, and used to prioritise a genus-specific protein database?"
    default: null

  - id: D3
    param: assemblyOrigin
    kind: required
    source: data
    ask: "Is this an isolate genome, or a bin recovered from a metagenome?"
    default: "isolate - gene prediction trains on the assembly itself"

  - id: D4
    param: rnaPrediction
    kind: optional
    source: user
    ask: "Should rRNA, tRNA, and other non-coding RNA be predicted alongside coding genes?"
    default: "tRNA and rRNA predicted; Rfam search off as it is slow"

  - id: D5
    param: customProteins
    kind: optional
    source: user
    ask: "Is there a curated protein set that should be searched before the general reference database?"
    default: "none"

  - id: D6
    param: hitEvalue
    kind: optional
    source: user
    ask: "How confident must a database hit be before it names a gene?"
    default: "1e-6"

  - id: D7
    param: minContigLength
    kind: optional_conditional
    source: data
    ask: "Should short contigs be skipped - and does the assembly have enough of them to matter?"
    default: "no minimum"

  - id: D8
    param: cpus
    kind: never_ask
    source: data
    reason: "Affects runtime only, not the annotation"
    default: "min(8, available_cores)"

D3 changes how genes are predicted rather than how they are named. Prodigal trains its model on the input; a metagenomic bin holding more than one organism trains a blended model, and the resulting gene boundaries are wrong in a way that no downstream step flags.

Quick Start

# Annotate a bacterial genome assembly — results in results/ directory
prokka genome.fasta \
    --outdir results/ \
    --prefix sample1 \
    --kingdom Bacteria \
    --cpus 4

# Check output summary
cat results/sample1.txt
# Organism: Genus species strain
# Contigs: 1
# Bases: 4639675
# CDS: 4140
# rRNA: 22
# tRNA: 86

echo "Annotation complete. Key output files:"
ls results/sample1.{gff,gbk,faa,ffn,tsv}

Workflow

Step 1: Install and Verify Prokka

Install Prokka and confirm all dependent tools are accessible in the current environment.

# Create a dedicated conda environment
conda create -n prokka_env -c conda-forge -c bioconda prokka python=3.10 -y
conda activate prokka_env

# Verify Prokka version and all tool dependencies
prokka --version
# prokka 1.14.6

prokka --depends
# Checking that required tools are installed...
# OK: makeblastdb is installed (2.13.0+)
# OK: blastp is installed (2.13.0+)
# OK: hmmscan is installed (3.3.2)
# OK: prodigal is installed (2.6.3)
# OK: barrnap is installed (0.9)

# Check available genus-speci