█▀▀█ █░░█ █▀▀█ █▀▀▀ █▀▀ 　 █▀▀ █▀▀█ █▀▀▄ ▀▀█▀▀ ░▀░ █▀▀▀ 　 █▀▀█ █▀▀▄ █▀▀▄ █▀▀█ ▀▀█▀▀ █▀▀█ ▀▀█▀▀ █▀▀█ █▀▀█ 
█░░█ █▀▀█ █▄▄█ █░▀█ █▀▀ 　 █░░ █░░█ █░░█ ░░█░░ ▀█▀ █░▀█ 　 █▄▄█ █░░█ █░░█ █░░█ ░░█░░ █▄▄█ ░░█░░ █░░█ █▄▄▀ 
█▀▀▀ ▀░░▀ ▀░░▀ ▀▀▀▀ ▀▀▀ 　 ▀▀▀ ▀▀▀▀ ▀░░▀ ░░▀░░ ▀▀▀ ▀▀▀▀ 　 ▀░░▀ ▀░░▀ ▀░░▀ ▀▀▀▀ ░░▀░░ ▀░░▀ ░░▀░░ ▀▀▀▀ ▀░▀▀

Annotates genes on putative phage contigs with a database of hidden Markov models (HMMs) based on PHROGs. This tool was built to support visual confirmation of predictions made by Jaeger.

The pipeline is managed by Snakemake, uses pyrodigal-gv for gene calling by default, pyhmmer for HMM search, and tRNAscan-SE for tRNA prediction. PHANOTATE and PHANOTATE-rs are also supported as alternative gene callers.

Requirements

• Python >= 3.11
• Conda (recommended for installing tRNAscan-SE)

Quick install (macOS/Linux)

If you already have Conda installed, run:

bash <(curl -fsSL https://raw.githubusercontent.com/Yasas1994/phage_contig_annotator/main/install.sh)

Or, after cloning the repository:

git clone https://github.com/Yasas1994/phage_contig_annotator.git
cd phage_contig_annotator
bash install.sh

Manual installation

1. Clone the repository:

   git clone https://github.com/Yasas1994/phage_contig_annotator.git
   cd phage_contig_annotator

2. Create and activate the Conda environment:

   conda env create -f environment.yml
   conda activate phage_contig_annot

3. Install the package in editable mode:

   pip install -e ".[dev]"

4. Download the annotation database:

   phage_contig_annotator download-db

   The database is organized hierarchically under databases/:

   databases/
   ├── phrogs/                    # primary PHROG database
   │   ├── hmms/                  # HMM profiles (.hmm)
   │   ├── metadata/              # PHROG metadata (.csv)
   │   ├── diamond/               # optional DIAMOND database
   │   └── mmseqs/                # optional MMseqs database
   └── db_chkpt
   

   Additional databases can be added as sibling directories (e.g. databases/apis/). If you have an existing flat database layout, reorganize it with:

   phage_contig_annotator utils reorganize-db

Optional tools

The pipeline can run two optional external tools. They are installed by install.sh / environment.yml where a conda package exists, but each tool needs extra model databases and (for CRISPRCasFinder) a manual install step.

DefenseFinder (anti-phage defense systems)

The defense-finder conda package is included in environment.yml. install.sh downloads the latest DefenseFinder models with defense-finder update.

Enable it with:

phage_contig_annotator run --input test/bin.460.fna --output output_dir \
  --run-defensefinder --cpus 10

CRISPRCasFinder (CRISPR arrays and Cas genes)

environment.yml installs macsyfinder (required by CRISPRCasFinder) and install.sh downloads the CasFinder models with:

macsydata install -u CASFinder==3.1.0

CRISPRCasFinder itself is a Perl script that is not available on conda. Install it manually, for example:

CRISPR_DIR="$CONDA_PREFIX/share/crisprcasfinder"
mkdir -p "$CRISPR_DIR"
git clone --depth 1 https://github.com/dcouvin/CRISPRCasFinder.git "$CRISPR_DIR"
ln -s "$CRISPR_DIR/CRISPRCasFinder.pl" "$CONDA_PREFIX/bin/CRISPRCasFinder.pl"

Enable it with:

phage_contig_annotator run --input test/bin.460.fna --output output_dir \
  --run-crisprcasfinder --cpus 10

Usage

Activate the environment and run the full pipeline:

conda activate phage_contig_annot
phage_contig_annotator run --input test/bin.460.fna --output output_dir --cpus 10

By default the pipeline produces a semantically organized output directory:

output_dir/
├── annotations/
│   ├── annotations.gff   # annotated contigs in GFF3 format
│   └── annotations.gbk   # annotated contigs in GenBank format
├── genes/
│   ├── proteins.faa      # predicted protein sequences
│   └── proteins.gff      # predicted gene coordinates
├── hmm/
│   ├── hmmsearch.txt     # HMMER-style tblout
│   └── hmmsearch.csv     # parsed HMM hit summary
├── plots/
│   └── *.pdf             # static genome maps (one per contig)
└── trna/
    ├── trna.tsv          # tRNAscan-SE tabular output
    └── trna.gff          # tRNAscan-SE GFF output

Use an alternative gene caller (pyrodigal-gv is the default):

# Original Python PHANOTATE implementation
phage_contig_annotator run --input test/bin.460.fna --output output_dir --cpus 10 \
  --gene-caller phanotate

# Rust reimplementation of PHANOTATE (https://github.com/Yasas1994/PHANOTATE-rs)
phage_contig_annotator run --input test/bin.460.fna --output output_dir --cpus 10 \
  --gene-caller phanotate-rs

phanotate and phanotate-rs must be installed separately and available on PATH.

Output options

Generate interactive HTML plots in addition to PDFs:

phage_contig_annotator run --input test/bin.460.fna --output output_dir --cpus 10 \
  --plot-format pdf --plot-format html

Other plot formats: pdf (default), png, html. Specify --plot-format multiple times for multiple formats.

Skip tRNA prediction:

phage_contig_annotator run --input test/bin.460.fna --output output_dir --cpus 10 --skip-trna

Use a dark color theme for plots:

phage_contig_annotator run --input test/bin.460.fna --output output_dir --cpus 10 --theme dark

Run on an existing protein FASTA:

phage_contig_annotator run --input proteins.faa --output output_dir --type proteins --cpus 10

Override the gene-calling translation table (default is auto-selection in metagenomic mode):

phage_contig_annotator run --input test/bin.460.fna --output output_dir --cpus 10 --translation-table 4

Preview the Snakemake execution plan without running:

phage_contig_annotator run --input test/bin.460.fna --output output_dir --cpus 10 --dry-run

Development

Run the test suite:

pytest tests/ -v

Examples

A genome map of a contig from the included test data. The figure automatically switches between the light and dark theme versions when your system/browser toggles between light and dark modes.

Interactive HTML report

Generate an interactive HTML report in addition to (or instead of) static maps:

phage_contig_annotator run --input test/bin.460.fna --output output_dir \
  --plot-format pdf --plot-format html

The HTML report lets you pan and zoom along the contig, toggle gene labels, show/hide genes without PHROG hits, and switch between light and dark themes. It also shows GC content, GC skew, and cumulative GC skew tracks.

An example report is included at docs/examples/NODE_94_report.html. Open it locally after cloning, or enable GitHub Pages on the docs/ folder to view it directly in a browser.

Convert existing annotations to HTML

If you already have an annotated GenBank or GFF file, you can generate the same interactive HTML report without re-running the pipeline:

phage_contig_annotator utils report -i genome.gbk -o genome.html

For GFF files that do not contain embedded sequences, provide the nucleotide FASTA file with -f:

phage_contig_annotator utils report -i annotations.gff -f contigs.fna -o html_reports/

By default one HTML file is written per contig. When the input contains a single record, -o can be a single .html file; for multiple records, specify an output directory. Use --theme dark to generate the dark-themed version.