Cerberus transforms raw sequencing (i.e. genomic, transcriptomics, metagenomics, metatranscriptomic) data into knowledge. It is a start to finish python code for versatile analysis of the Functional Ontology Assignments for Metagenomes (FOAM), KEGG, CAZy/dbCAN, VOG, pVOG, PHROG, COG, and a variety of other databases including user customized databases via Hidden Markov Models (HMM) for functional annotation for complete metabolic analysis across the tree of life (i.e., bacteria, archaea, phage, viruses, eukaryotes, and whole ecosystems). Cerberus also provides automatic differential statistics using DESeq2/EdgeR, pathway enrichments with GAGE, and pathway visualization with Pathview R.

Art by Andra Buchan

• Mamba install from bioconda with all dependencies:

1. Install mamba using conda

conda install mamba

2. Install Cerberus with mamba

mamba create -n cerberus -c conda-forge -c bioconda cerberus
conda activate cerberus
cerberus.py --setup
cerberus.py --download

1. Set up conda environment

conda create -y -n cerberus
conda activate cerberus
conda config --env --set subdir osx-64

2. Install mamba, python, and pydantic inside the environment

conda install -y -c conda-forge mamba python=3.10 "pydantic<2"

3. Install Cerberus with mamba

mamba install -y -c conda-forge -c bioconda cerberus
cerberus.py --setup
cerberus.py --download

• Anaconda install from bioconda with all dependencies:

conda create -n cerberus -c conda-forge -c bioconda cerberus -y
conda activate cerberus
cerberus.py --setup
cerberus.py --download

git clone https://github.com/raw-lab/cerberus.git 
cd cerberus
bash install_cerberus.sh
conda activate Cerberus
cerberus.py --download

• Cerberus has three basic modes:
  1. Quality Control (QC) for raw reads
  2. Formatting/gene prediction
  3. Annotation
• Cerberus can use three different input files:
  1. Raw read data from any sequencing platform (Illumina, PacBio, or Oxford Nanopore)
  2. Assembled contigs, as MAGs, vMAGs, isolate genomes, or a collection of contigs
  3. Amino acid fasta (.faa), previously called pORFs

• We offer customization, including running all databases together, individually or specifying select databases. For example, if a user wants to run prokaryotic or eukaryotic-specific KOfams, or an individual database alone such as dbCAN, both are easily customized within Cerberus.

• In QC mode, raw reads are quality controlled via FastQC prior and post trim FastQC. Raw reads are then trimmed via data type; if the data is Illumina or PacBio, fastp is called, otherwise it assumes the data is Oxford Nanopore, then PoreChop is utilized.

• If Illumina reads are utilized, an optional bbmap step to remove the phiX174 genome is available or user provided contaminate genome. Phage phiX174 is a common contaminant within the Illumina platform as their library spike-in control. We highly recommend this removal if viral analysis is conducted, as it would provide false positives to ssDNA microviruses within a sample.

• We include a --skip_decon option to skip the filtration of phiX174, which may remove common k-mers that are shared in ssDNA phages.

• In the formatting and gene prediction stage, contigs and genomes are checked for N repeats. These N repeats are removed by default.

• We impute contig/genome statistics (e.g., N50, N90, max contig) via our custom module Metaome Stats.

• Contigs can be converted to pORFs using Prodigal, FragGeneScanRs , and Prodigal-gv as specified by user preference.

• Scaffold annotation is not recommended due to N's providing ambiguous annotation.

• Both Prodigal and FragGeneScanRs can be used via our --super option, and we recommend using FragGeneScanRs for samples rich in eukaryotes.

• FragGeneScanRs found more ORFs and KOs than Prodigal for a stimulated eukaryote rich metagenome. HMMER searches against the above databases via user specified bitscore and e-values or our minimum defaults (i.e., bitscore = 25, e-value = 1 x 10^-9 ).

• From any NextGen sequencing technology (from Illumina, PacBio, Oxford Nanopore)
• type 1 raw reads (.fastq format)
• type 2 nucleotide fasta (.fasta, .fa, .fna, .ffn format), assembled raw reads into contigs
• type 3 protein fasta (.faa format), assembled contigs which genes are converted to amino acid sequence

• If an output directory is given, that folder will be created where all files are stored.
• If no output directory is specified, the 'results_cerberus' subfolder will be created in the current directory.
• Gage/Pathview R analysis provided as separate scripts within R.

• We use Plotly to visualize the data
• Once the program is finished running, the html reports containing the visuals will be saved to the last step of the pipeline.
• The HTML files require plotly.js to be present. One has been provided in the package and is saved to the report folder.

• Rule 1 is for finding high quality matches across databases. It is a score pre-filtering module for pORFs thresholds: which states that each pORF match to an HMM is recorded by default or a user-selected cut-off (i.e., e-value/bit scores) per database independently, or across all default databases (e.g, finding best hit), or per user specification of the selected database.
• Rule 2 is to avoid missing genes encoding proteins with dual domains that are not overlapping. It is imputed for non-overlapping dual domain module pORF threshold: if two HMM hits are non-overlapping from the same database, both are counted as long as they are within the default or user selected score (i.e., e-value/bit scores).
• Rule 3 is to ensure overlapping dual domains are not missed. This is the dual independent overlapping domain module for convergent binary domain pORFs. If two domains within a pORF are overlapping <10 amino acids (e.g, COG1 and COG4) then both domains are counted and reported due to the dual domain issue within a single pORF. If a function hits multiple pathways within an accession, both are counted, in pathway roll-up, as many proteins function in multiple pathways.
• Rule 4 is the equal match counter to avoid missing high quality matches within the same protein. This is an independent accession module for a single pORF: if both hits within the same database have equal values for both e-value and bit score but are different accessions from the same database (e.g., KO1 and KO3) then both are reported.
• Rule 5 is the ‘winner take all’ match rule for providing the best match. It is computed as the winner takes all module for overlapping pORFs: if two HMM hits are overlapping (>10 amino acids) from the same database the lowest resulting e-value and highest bit score wins.
• Rule 6 is to avoid partial or fractional hits being counted. This ensures that only whole discrete integer counting (e.g., 0, 1, 2 to n) are computed and that partial or fractional counting is excluded.

conda activate cerberus
cerberus.py --prodigal lambda.fna --hmm ALL --dir_out lambda_dir

conda activate cerberus
cerberus.py --prodigal lambda.fna --hmm KOFam_all --dir_out lambda_ko-only_dir

conda activate cerberus
cerberus.py --prodigal ecoli.fna --hmm KOFam_prokaryote --dir_out ecoli_ko-only_dir

conda activate cerberus
cerberus.py --fraggenescan human.fna --hmm KOFam_eukaryote --dir_out human_ko-only_dir

conda activate cerberus
cerberus.py --prodigal lambda.fna --hmm VOG, PHROG --dir_out lambda_vir-only_dir

• NOTE: You can pick any single database you want for your analysis including KOFam_all, COG, VOG, PHROG, CAZy or specific KO databases for eukaryotes and prokaryotes (KOFam_eukaryote or KOFam_prokaryote).

conda activate cerberus
cerberus.py --prodigal lambda.fna --hmm Custom.hmm --dir_out lambda_vir-only_dir

conda activate cerberus
cerberus.py --prodigal [input_folder] --illumina --meta --dir_out [out_folder] 

conda activate cerberus
cerberus.py --fraggenescan [input_folder] --illumina --meta --dir_out [out_folder] 

conda activate cerberus
cerberus.py --fraggenescan [input_folder] --nanopore --dir_out [out_folder] 

conda activate cerberus
cerberus.py --fraggenescan [input_folder] --pacbio --dir_out [out_folder]

conda activate cerberus
cerberus.py --super [input_folder] --pacbio/--nanopore/--illumina --dir_out [out_folder]

• Note: Fraggenescan will work for prokaryotes and viruses/bacteriophage but prodigal will not work well for eukaryotes.

• python >= 3.8

All pre-formatted databases are present at OSF.

To run a custom database, you need a HMM containing the protein family of interest and a metadata sheet describing the HMM required for look-up tables and downstream analysis. For the metadata information you need an ID that matches the HMM and a function or hierarchy. See example below.

• Run cerberus.py with the options required for your project.

After processing the HMM files, Cerberus calculates a KO (KEGG Orthology) counts table from KEGG/FOAM for processing through GAGE and PathView. GAGE is recommended for pathway enrichment followed by PathView for visualize the metabolic pathways. A "class" file is required through the --class option to run this analysis.

The output is saved under the step_10-visualizeData/combined/pathview folder. Also, at least 4 samples need to be used for this type of analysis.

• GAGE and PathView also require internet access to be able to download information from a database.
• Cerberus will save a bash script run_pathview.sh in the step_10-visualizeData/combined/pathview directory along with the KO Counts tsv files and the class file for running manualy in case Cerberus was run on a cluster without access to the internet.

• Cerberus uses Ray for distributed processing. This is compatible with both multiprocessing on a single node (computer) or multiple nodes in a cluster.
• Cerberus has been tested on a cluster using Slurm.

sbatch example_script.sh

example script:

#!/usr/bin/env bash

#SBATCH --job-name=test-job
#SBATCH --nodes=3
#SBATCH --tasks-per-node=1
#SBATCH --cpus-per-task=16
#SBATCH --mem=128MB
#SBATCH -e slurm-%j.err
#SBATCH -o slurm-%j.out
#SBATCH --mail-type=END,FAIL,REQUEUE

echo "====================================================="
echo "Start Time  : $(date)"
echo "Submit Dir  : $SLURM_SUBMIT_DIR"
echo "Job ID/Name : $SLURM_JOBID / $SLURM_JOB_NAME"
echo "Node List   : $SLURM_JOB_NODELIST"
echo "Num Tasks   : $SLURM_NTASKS total [$SLURM_NNODES nodes @ $SLURM_CPUS_ON_NODE CPUs/node]"
echo "======================================================"
echo ""

# Load any modules or resources here
conda activate cerberus
# source the slurm script to initialize the Ray worker nodes
source ray-slurm-cerberus.sh
# run Cerberus
cerberus.py --prodigal [input_folder] --illumina --dir_out [out_folder]

echo ""
echo "======================================================"
echo "End Time   : $(date)"
echo "======================================================"
echo ""

Both edgeR and DeSeq2 R have the highest sensitivity when compared to other algorithms that control type-I error when the FDR was at or below 0.1. EdgeR and DESeq2 all perform fairly well in simulation and via data splitting (so no parametric assumptions). Typical benchmarks will show limma having stronger FDR control across all types of datasets (it’s hard to beat the moderated t-test), and edgeR and DESeq2 having higher sensitivity for low counts (makes sense as limma has to filter these out / down-weight them to use the normal model on log counts). Further information about type I errors are present from Mike Love's vignette here.

Cerberus as a community resource as recently acquired FunGene, we welcome contributions of other experts expanding annotation of all domains of life (viruses, bacteria, archaea, eukaryotes). Please send us an issue on our Cerberus GitHub open an issue; or email us we will fully annotate your genome, add suggested pathways/metabolisms of interest, make custom HMMs to be added to Cerberus and FunGene.

This is copyrighted by University of North Carolina at Charlotte, Jose L Figueroa III, Eliza Dhungal, Madeline Bellanger, Cory R Brouwer and Richard Allen White III. All rights reserved. Cerberus is a bioinformatic tool that can be distributed freely for academic use only. Please contact us for commerical use. The software is provided “as is” and the copyright owners or contributors are not liable for any direct, indirect, incidental, special, or consequential damages including but not limited to, procurement of goods or services, loss of use, data or profits arising in any way out of the use of this software.

If you are publishing results obtained using Cerberus, please cite:

Figueroa III JL, Dhungel E, Bellanger M, Brouwer CR, White III RA. 2024. Cerberus: distributed highly parallelized HMM-based processing for robust functional annotation across the tree of life. Bioinformatics

Figueroa III JL, Dhungel E, Brouwer CR, White III RA. 2023.
Cerberus: distributed highly parallelized HMM-based processing for robust functional annotation across the tree of life. bioRxiv

The informatics point-of-contact for this project is Dr. Richard Allen White III.
If you have any questions or feedback, please feel free to get in touch by email.
Dr. Richard Allen White III
Jose Luis Figueroa III
Or open an issue.