4  Linux Setup for Viromics on Ubuntu

Think of this chapter as preparing your viromics laboratory bench. In a wet lab you would never pour RNA extraction, DNA extraction, PCR, and sequencing reagents into one messy box — each protocol needs its own clean space and its own reagents. Bioinformatics is the same. Many viral tools depend on different versions of Python, R, HMMER, DIAMOND, or TensorFlow, and databases that assume specific layouts.

The rule for this book: one clean core environment, then a separate environment per complex viral tool.

Installing everything into base is the fastest way to spend days untangling dependency conflicts. Bioconda recommends the bioconda and conda-forge channels with strict channel priority, and Miniforge is the lightweight, conda-forge-based installer that replaced Mambaforge for Ubuntu workstations.

Learning objectives — by the end of this chapter you will be able to:

• install Miniforge and configure Bioconda channels with strict priority;
• explain why viromics tools live in separate conda environments and design that layout;
• build a reproducible project folder structure and set the shared environment variables the book relies on;
• install and version-check the full viromics toolchain, from QC and assembly to host prediction; and
• set up the tool databases (VirSorter2, geNomad, CheckV, DRAM, eggNOG, iPHoP) and verify the whole install with one script.

4.1 Recommended computer resources

Viromics is disk- and memory-hungry, mostly because of the reference databases. For teaching and small practice datasets:

Component	Minimum	Better
RAM	16 GB	32–64 GB
CPU	4 cores	8–32 cores
Disk	200 GB	1–2 TB
OS	Ubuntu 22.04 / 24.04	Ubuntu server / HPC
Internet	Stable	Very stable

Full databases need much more disk. Some tools — iPHoP, DRAM, and large host databases — can each require hundreds of GB. On a student laptop you can demonstrate the commands; run them for real on a workstation, server, or HPC.

4.2 System preparation

Update the base system and install compilers and common utilities.

sudo apt update
sudo apt upgrade -y
sudo apt install -y \
  build-essential wget curl git unzip zip tar gzip pigz tree htop \
  nano vim cmake make gcc g++ default-jre default-jdk

Check versions.

gcc --version
g++ --version
java -version
git --version

4.3 Install Miniforge

Skip this section only if you already have a working conda/mamba installation.

cd ~

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh \
  -O Miniforge3-Linux-x86_64.sh

bash Miniforge3-Linux-x86_64.sh
source ~/.bashrc

During installation accept the license (yes), keep the default path, and answer yes to initialize conda. Then confirm and update the base tools.

conda --version
mamba --version
mamba update -n base -c conda-forge conda mamba -y

Configure channels with strict priority.

conda config --add channels bioconda
conda config --add channels conda-forge
conda config --set channel_priority strict
conda config --show channels

4.4 Project folder structure

mkdir -p ~/viromics_course
cd ~/viromics_course

mkdir -p raw_reads trimmed_reads qc_reports assemblies assembly_qc \
  viral_identification checkv votus taxonomy annotation abundance \
  host_prediction phylogeny diversity visualization metadata databases \
  logs scripts env_yamls code images

tree -L 1 ~/viromics_course

Set the shared paths and thread count once, in your shell profile, so every later command can reuse them.

cat >> ~/.bashrc << 'EOF'

# Viromics course paths
export VIROME=$HOME/viromics_course
export VIROME_DB=$HOME/viromics_course/databases
export THREADS=12
EOF

source ~/.bashrc
echo "$VIROME | $VIROME_DB | $THREADS"

4.5 Environment strategy

This looks like many environments, but it is professional practice: it stops one tool from breaking another and makes every step reproducible.

Environment	Purpose
viromics-core	QC, trimming, assembly, mapping, general utilities, R/Python visualization
virsorter2	Virus identification
genomad	Virus/plasmid identification and taxonomy
checkv	Viral genome quality and completeness
virfinder	R-based viral prediction
deepvirfinder	Deep-learning viral prediction
vclust	ANI-based viral clustering and vOTUs
cd-hit	Fast sequence clustering / dereplication
vcontact2	Gene-sharing network taxonomy
vibrant	Viral identification and functional annotation
dramv	DRAM-v viral functional annotation
eggnog	eggNOG functional annotation
iphop	Host prediction
phabox	PhaGCN/PhaBOX taxonomy, host, and lifestyle tools
wish	WIsH host prediction from viral contigs

4.6 Fast path: create environments from files

If you would rather not type every mamba create command, ready-made environment.yml files are provided for the most important environments. Create each one with a single command (databases are still downloaded separately, as shown in the tool sections below).

⬇ viromics-core.yml ⬇ virsorter2.yml ⬇ genomad.yml ⬇ checkv.yml ⬇ eggnog.yml

conda env create -f envs/viromics-core.yml
conda env create -f envs/virsorter2.yml
conda env create -f envs/genomad.yml
conda env create -f envs/checkv.yml
conda env create -f envs/eggnog.yml

The sections below still explain each tool and its database, and cover the extra environments (VirFinder, DeepVirFinder, vClust, vConTACT2, VIBRANT, DRAM-v, iPHoP, PhaBOX, WIsH) that you install as you need them.

4.7 Core environment

This environment handles QC, trimming, assembly, mapping, plotting, and general utilities (Shen et al. 2016; Hyatt et al. 2010; Langmead and Salzberg 2012; Danecek et al. 2021).

Hyatt, Doug, Gwo-Liang Chen, Philip F. LoCascio, Miriam L. Land, Frank W. Larimer, and Loren J. Hauser. 2010. “Prodigal: Prokaryotic Gene Recognition and Translation Initiation Site Identification.” BMC Bioinformatics 11: 119. https://doi.org/10.1186/1471-2105-11-119.

Langmead, Ben, and Steven L. Salzberg. 2012. “Fast Gapped-Read Alignment with Bowtie 2.” Nature Methods 9 (4): 357–59. https://doi.org/10.1038/nmeth.1923.

Danecek, Petr, James K. Bonfield, Jennifer Liddle, John Marshall, Valeriu Ohan, Martin O. Pollard, Andrew Whitwham, et al. 2021. “Twelve Years of SAMtools and BCFtools.” GigaScience 10 (2): giab008. https://doi.org/10.1093/gigascience/giab008.

mamba create -n viromics-core -y \
  -c conda-forge -c bioconda \
  python=3.11 r-base r-essentials r-tidyverse r-ggplot2 r-pheatmap \
  r-vegan r-ape bioconductor-phyloseq fastqc multiqc fastp trimmomatic \
  megahit spades quast sra-tools seqkit csvtk blast diamond hmmer \
  mmseqs2 prodigal cd-hit mafft iqtree bowtie2 samtools coverm bedtools \
  pandas numpy scipy matplotlib seaborn jupyterlab

Activate and check the key tools.

conda activate viromics-core
fastqc --version
multiqc --version
fastp --version
megahit --version
spades.py --version
quast.py --version
seqkit version
bowtie2 --version | head -n 1
samtools --version | head -n 1
coverm --version
R --version
python --version

Save a reproducible copy of the environment. Do this for every environment you build.

conda env export --no-builds > $VIROME/env_yamls/viromics-core.yml

4.8 Viral tool environments

4.8.1 VirSorter2

VirSorter2 detects diverse DNA and RNA viruses using a multi-classifier approach (Guo et al. 2021).

mamba create -n virsorter2 -y -c conda-forge -c bioconda virsorter=2
conda activate virsorter2
virsorter --version

mkdir -p $VIROME_DB/virsorter2
virsorter setup -d $VIROME_DB/virsorter2 -j $THREADS
conda env export --no-builds > $VIROME/env_yamls/virsorter2.yml

4.8.2 geNomad

geNomad identifies viruses and plasmids and provides taxonomy and annotation outputs (Camargo et al. 2024).

mamba create -n genomad -y -c conda-forge -c bioconda genomad
conda activate genomad
genomad --version

mkdir -p $VIROME_DB/genomad
genomad download-database $VIROME_DB/genomad
conda env export --no-builds > $VIROME/env_yamls/genomad.yml

4.8.3 CheckV

CheckV estimates viral contig quality, completeness, and contamination, and trims host flanks from proviruses (Nayfach et al. 2021). The database is downloaded separately, and its folder name varies by version, so locate it and export CHECKVDB into your profile.

mamba create -n checkv -y -c conda-forge -c bioconda checkv
conda activate checkv

mkdir -p $VIROME_DB/checkv
checkv download_database $VIROME_DB/checkv

CHECKV_PATH=$(find $VIROME_DB/checkv -maxdepth 2 -type d -name "checkv-db*" | head -n 1)
ln -sfn "$CHECKV_PATH" $VIROME_DB/checkv-db          # stable path reused across the book
echo 'export CHECKVDB=$VIROME_DB/checkv-db' >> ~/.bashrc
source ~/.bashrc
echo "$CHECKVDB"
conda env export --no-builds > $VIROME/env_yamls/checkv.yml

4.8.4 VirFinder

VirFinder is an R package that scores contigs as viral using k-mer signatures learned from reference genomes (Ren et al. 2017).

Ren, Jie, Nathan A. Ahlgren, Yang Young Lu, Jed A. Fuhrman, and Fengzhu Sun. 2017. “VirFinder: A Novel k-Mer Based Tool for Identifying Viral Sequences from Assembled Metagenomic Data.” Microbiome 5: 69. https://doi.org/10.1186/s40168-017-0283-5.

mamba create -n virfinder -y -c conda-forge -c bioconda \
  r-base r-virfinder r-tidyverse
conda activate virfinder

# Load the package and print its version to confirm the install
R -q -e "library(VirFinder); packageVersion('VirFinder')"
conda env export --no-builds > $VIROME/env_yamls/virfinder.yml

4.8.5 DeepVirFinder

DeepVirFinder predicts viral sequences with a deep-learning model and was designed to work well on short contigs (Ren et al. 2020). It is older and dependency-sensitive, so keep it isolated. Two routes are shown; use the source route when the conda package fails to solve.

Ren, Jie, Kai Song, Chao Deng, Nathan A. Ahlgren, Jed A. Fuhrman, Yi Li, Xiaohui Xie, Ryan Poplin, and Fengzhu Sun. 2020. “Identifying Viruses from Metagenomic Data Using Deep Learning.” Quantitative Biology 8 (1): 64–77. https://doi.org/10.1007/s40484-019-0187-4.

Route A — conda package from the HCC channel:

mamba create -n deepvirfinder -y \
  -c hcc -c conda-forge -c bioconda deepvirfinder
conda activate deepvirfinder
dvf.py -h | head

Route B — GitHub source install:

mamba create -n deepvirfinder-src -y -c conda-forge -c bioconda \
  python=3.6 numpy theano keras scikit-learn biopython
conda activate deepvirfinder-src

mkdir -p $VIROME/software && cd $VIROME/software
git clone https://github.com/jessieren/DeepVirFinder.git
cd DeepVirFinder
python dvf.py -h
conda env export --no-builds > $VIROME/env_yamls/deepvirfinder.yml

NoteWhat we teach as the core method

For modern pipelines, treat VirSorter2 + geNomad + CheckV as the core viral-identification stack, then use VirFinder and DeepVirFinder as additional evidence layers rather than standalone verdicts.

4.8.6 vClust and CD-HIT

vClust calculates average nucleotide identity (ANI) and clusters viral genomes into vOTUs, typically at a 95% ANI threshold (Zielezinski et al. 2025). CD-HIT is already in viromics-core, but a dedicated environment keeps its version stable for teaching and dereplication (Fu et al. 2012).

Zielezinski, Andrzej, Adam Gudyś, Jakub Barylski, Krzysztof Siminski, Piotr Rozwalak, Bas E. Dutilh, and Sebastian Deorowicz. 2025. “Ultrafast and Accurate Sequence Alignment and Clustering of Viral Genomes.” Nature Methods 22: 1191–94. https://doi.org/10.1038/s41592-025-02701-7.

Fu, Limin, Beifang Niu, Zhengwei Zhu, Sitao Wu, and Weizhong Li. 2012. “CD-HIT: Accelerated for Clustering the Next-Generation Sequencing Data.” Bioinformatics 28 (23): 3150–52. https://doi.org/10.1093/bioinformatics/bts565.

mamba create -n vclust -y -c conda-forge -c bioconda vclust
conda activate vclust
vclust --help | head
conda env export --no-builds > $VIROME/env_yamls/vclust.yml

mamba create -n cd-hit -y -c conda-forge -c bioconda cd-hit
conda activate cd-hit
cd-hit -h | head
cd-hit-est -h | head
conda env export --no-builds > $VIROME/env_yamls/cd-hit.yml

4.8.7 vConTACT2

vConTACT2 classifies prokaryotic viruses using gene-sharing networks; the official install pairs it with mcl, blast, and diamond (Bin Jang et al. 2019).

Bin Jang, Ho, Benjamin Bolduc, Olivier Zablocki, Jens H. Kuhn, Simon Roux, Evelien M. Adriaenssens, J. Rodney Brister, et al. 2019. “Taxonomic Assignment of Uncultivated Prokaryotic Virus Genomes Is Enabled by Gene-Sharing Networks.” Nature Biotechnology 37: 632–39. https://doi.org/10.1038/s41587-019-0100-8.

mamba create -n vcontact2 -y -c conda-forge -c bioconda \
  python=3 vcontact2 mcl blast diamond prodigal
conda activate vcontact2
vcontact2 --help | head
conda env export --no-builds > $VIROME/env_yamls/vcontact2.yml

4.8.8 VIBRANT

VIBRANT recovers and annotates bacterial and archaeal viruses from metagenomic assemblies (Kieft, Zhou, and Anantharaman 2020). Its database is prepared with download-db.sh.

Kieft, Kristopher, Zhichao Zhou, and Karthik Anantharaman. 2020. “VIBRANT: Automated Recovery, Annotation and Curation of Microbial Viruses, and Evaluation of Viral Community Function from Genomic Sequences.” Microbiome 8: 90. https://doi.org/10.1186/s40168-020-00867-0.

mamba create -n vibrant -y -c conda-forge -c bioconda vibrant
conda activate vibrant
VIBRANT_run.py -h | head

mkdir -p $VIROME_DB/vibrant
cd $VIROME_DB/vibrant
download-db.sh
conda env export --no-builds > $VIROME/env_yamls/vibrant.yml

4.8.9 DRAM / DRAM-v

DRAM annotates microbial and viral genomes; DRAM-v is especially useful for viral functional annotation and auxiliary metabolic gene interpretation (Shaffer et al. 2020). DRAM ships its own environment.yaml, and databases are prepared with DRAM-setup.py.

Shaffer, Michael, Mikayla A. Borton, Brendan B. McGivern, Ahmed A. Zayed, Sabina L. La Rosa, Lindsey M. Solden, Pengfei Liu, et al. 2020. “DRAM for Distilling Microbial Metabolism to Automate the Curation of Microbiome Function.” Nucleic Acids Research 48 (16): 8883–8900. https://doi.org/10.1093/nar/gkaa621.

mkdir -p $VIROME/software && cd $VIROME/software
wget https://raw.githubusercontent.com/WrightonLabCSU/DRAM/master/environment.yaml \
  -O DRAM_environment.yaml

mamba env create -f DRAM_environment.yaml -n dramv
conda activate dramv
DRAM-setup.py --help | head

Prepare the databases. On a workstation, add --skip_uniref: UniRef90 is enormous and pushes memory far beyond a typical machine, and DRAM works well for viral annotation without it. Then confirm the configuration.

mkdir -p $VIROME_DB/DRAM_data

DRAM-setup.py prepare_databases \
  --output_dir $VIROME_DB/DRAM_data \
  --skip_uniref \
  --threads $THREADS \
  --verbose

DRAM-setup.py print_config
conda env export --no-builds > $VIROME/env_yamls/dramv.yml

WarningDRAM database setup is heavy

Even with --skip_uniref, DRAM database preparation is one of the most resource-intensive steps in this book. On student laptops, demonstrate the commands; run them for real on a workstation, server, or HPC.

4.8.10 eggNOG-mapper

eggNOG-mapper annotates predicted proteins by orthology (Cantalapiedra et al. 2021). Define EGGNOG_DATA_DIR before downloading, and persist it to your profile so every run finds the same database.

mamba create -n eggnog -y -c conda-forge -c bioconda eggnog-mapper
conda activate eggnog
emapper.py --version

mkdir -p $VIROME_DB/eggnog
export EGGNOG_DATA_DIR=$VIROME_DB/eggnog
download_eggnog_data.py --data_dir $EGGNOG_DATA_DIR   # answer y when prompted

echo "export EGGNOG_DATA_DIR=$VIROME_DB/eggnog" >> ~/.bashrc
source ~/.bashrc
conda env export --no-builds > $VIROME/env_yamls/eggnog.yml

4.8.11 iPHoP

iPHoP predicts the host genus of uncultivated bacteriophages and archaeal viruses by integrating several host-prediction signals. It is available through Bioconda; the database is large.

mamba create -n iphop -y -c conda-forge -c bioconda iphop
conda activate iphop
iphop --help | head

mkdir -p $VIROME_DB/iphop
iphop download --db_dir $VIROME_DB/iphop

du -sh $VIROME_DB/iphop
conda env export --no-builds > $VIROME/env_yamls/iphop.yml

WarningThe iPHoP database is very large

The iPHoP host database runs to hundreds of GB. Confirm you have the disk space before downloading, and prefer server or HPC storage when teaching with real data.

4.8.12 PhaBOX / PhaGCN

PhaGCN moved into PhaBOX 2, which now covers taxonomy classification, host prediction, lifestyle prediction, vOTU grouping, tree building, and viral protein annotation (Shang et al. 2026). Install from Bioconda first; fall back to source if the package is unavailable or outdated, then download the database.

Shang, Jiayu, Cheng Peng, Jiaojiao Guan, Dehan Cai, Donglin Wang, and Yanni Sun. 2026. “PhaBOX2: An Enhanced Web Server for Discovering and Analyzing Viral Contigs in Metagenomic Data.” Nucleic Acids Research 54: W169–76. https://doi.org/10.1093/nar/gkag382.

mamba create -n phabox -y -c conda-forge -c bioconda phabox
conda activate phabox
phabox2 --help

Source install (only if the Bioconda package fails):

mkdir -p $VIROME/software && cd $VIROME/software
git clone https://github.com/KennthShang/PhaBOX.git
cd PhaBOX
python -m pip install -r requirements.txt
python -m pip install .

Download the PhaBOX database:

mkdir -p $VIROME_DB/phabox
cd $VIROME_DB/phabox
wget https://github.com/KennthShang/PhaBOX/releases/download/v2/phabox_db_v2_2.zip
unzip phabox_db_v2_2.zip
conda env export --no-builds > $VIROME/env_yamls/phabox.yml

4.8.13 WIsH

WIsH predicts prokaryotic hosts of phage contigs using Markov models and is compiled from source (Galiez et al. 2017). Build it inside a small environment that provides the compilers, then add the binary to your PATH.

Galiez, Clément, Matthias Siebert, François Enault, Jonathan Vincent, and Johannes Söding. 2017. “WIsH: Who Is the Host? Predicting Prokaryotic Hosts from Metagenomic Phage Contigs.” Bioinformatics 33 (19): 3113–14. https://doi.org/10.1093/bioinformatics/btx383.

mamba create -n wish -y -c conda-forge -c bioconda \
  cmake make gcc_linux-64 gxx_linux-64
conda activate wish

mkdir -p $VIROME/software && cd $VIROME/software
git clone https://github.com/soedinglab/WIsH.git
cd WIsH
cmake .
make

echo "export PATH=$VIROME/software/WIsH:\$PATH" >> ~/.bashrc
source ~/.bashrc
WIsH -h | head
conda env export --no-builds > $VIROME/env_yamls/wish.yml

4.8.14 CRISPR spacer tools

CRISPR-based host prediction needs only BLAST+, seqkit, bedtools, and samtools — all already in viromics-core. Bacterial and archaeal genomes record previous phage encounters as CRISPR spacers, so a high-identity BLAST match between a host spacer and a viral contig is evidence of a host relationship. In the complete pipeline chapter you will build a spacer database with makeblastdb and run a short-word blastn search against your viral contigs.

conda activate viromics-core
blastn -version
makeblastdb -version
seqkit version
bedtools --version

4.9 Tool map for the complete pipeline

Step	Tool	Main input	Main output
Raw data download	SRA Toolkit	SRA accession	FASTQ files
QC	FastQC / MultiQC	FASTQ	HTML reports
Trimming	fastp / Trimmomatic	Raw FASTQ	Clean FASTQ
Assembly	MEGAHIT / metaSPAdes	Clean FASTQ	contigs FASTA
Assembly QC	QUAST	contigs FASTA	assembly report
Virus detection	VirSorter2 / geNomad / VirFinder / DeepVirFinder	contigs FASTA	viral candidates
Quality	CheckV	viral contigs FASTA	quality/completeness table
Dereplication	vClust / CD-HIT	viral FASTA	vOTU clusters
Taxonomy	vConTACT2 / geNomad / PhaBOX	viral FASTA / proteins	taxonomy table
Gene calling	Prodigal	viral FASTA	proteins / GFF
Annotation	DRAM-v / VIBRANT / eggNOG	viral FASTA / proteins	functional tables
Abundance	Bowtie2 / CoverM	reads + viral contigs	coverage table
Host prediction	iPHoP / WIsH / CRISPR BLAST	viral FASTA + host DB	host predictions
Phylogeny	MAFFT / IQ-TREE	marker genes	alignment / tree
Visualization	R / Python	tables	publication figures

4.10 Installation check

Rather than checking each environment by hand, run one script that reports every environment, core and viral tool versions, and database sizes. The book ships a ready-made version.

⬇ check_viromics_installation.sh

The core of that script is shown below; download the full copy above rather than retyping it.

cat > $VIROME/scripts/check_viromics_installation.sh << 'EOF'
#!/usr/bin/env bash
set -e

echo "Conda environments"
conda env list

echo "Core tools"
conda run -n viromics-core fastqc --version
conda run -n viromics-core fastp --version
conda run -n viromics-core megahit --version
conda run -n viromics-core spades.py --version
conda run -n viromics-core quast.py --version
conda run -n viromics-core seqkit version
conda run -n viromics-core bowtie2 --version | head -n 1
conda run -n viromics-core samtools --version | head -n 1
conda run -n viromics-core coverm --version

echo "Viral tools"
conda run -n virsorter2 virsorter --version || true
conda run -n genomad genomad --version || true
conda run -n checkv checkv -h | head -n 2 || true
conda run -n virfinder R -q -e "packageVersion('VirFinder')" || true
conda run -n vclust vclust --help | head -n 2 || true
conda run -n vcontact2 vcontact2 --help | head -n 2 || true
conda run -n vibrant VIBRANT_run.py -h | head -n 2 || true
conda run -n dramv DRAM.py --help | head -n 2 || true
conda run -n eggnog emapper.py --version || true
conda run -n iphop iphop --help | head -n 2 || true

echo "Database sizes"
du -sh $VIROME_DB/* 2>/dev/null || true
EOF

chmod +x $VIROME/scripts/check_viromics_installation.sh
bash $VIROME/scripts/check_viromics_installation.sh

Estimated resources on 12 threads and 32 GB RAM: the core environment usually installs in 20–60 minutes and 10–25 GB. Databases range from ~50 GB to more than 500 GB depending on the tools selected. CheckV and geNomad are moderate; DRAM and iPHoP are heavy.

4.10.1 Environment cheat sheet

Keep one short reference for which environment to activate for each task. A ready-made copy is included with the book.

⬇ env_cheatsheet.txt

Core tools:              conda activate viromics-core
Virus identification:    conda activate virsorter2 | genomad | virfinder | deepvirfinder
Quality:                 conda activate checkv
Clustering:              conda activate vclust | cd-hit
Taxonomy:                conda activate vcontact2 | phabox | genomad
Functional annotation:   conda activate vibrant | dramv | eggnog
Host prediction:         conda activate iphop | wish
Main course folder:      cd $VIROME
Database folder:         cd $VIROME_DB

WarningCommon mistakes

• Installing into base. Never install viromics tools into the base conda environment. Always mamba create -n toolname ... then conda activate toolname.
• Forgetting the database. A tool without its database fails at runtime, not at install: VirSorter2 with no setup database, CheckV with CHECKVDB unset, geNomad with no genomad_db, VIBRANT with no download-db.sh run.
• Mixing old and new tools in one environment. DeepVirFinder, VirFinder, DRAM, VirSorter2, and PhaBOX have conflicting dependencies. Keep them separate so one upgrade cannot silently break another.

NoteExercise 1: build a virome-test environment

Create a throwaway environment called virome-test containing fastqc, fastp, seqkit, and multiqc, confirm each tool runs, then export the environment file.

One solution:

mamba create -n virome-test -y -c conda-forge -c bioconda \
  fastqc fastp seqkit multiqc

conda activate virome-test
fastqc --version
fastp --version
seqkit version
multiqc --version

conda env export --no-builds > $VIROME/env_yamls/virome-test.yml

NoteExercise 2: a check_fastq_pairs.sh guard script

Write a small script that verifies both paired-end FASTQ files exist before an analysis starts, and prints a clear message if either is missing.

One solution:

cat > $VIROME/scripts/check_fastq_pairs.sh << 'EOF'
#!/usr/bin/env bash
R1=$VIROME/raw_reads/samples_R1.fastq.gz
R2=$VIROME/raw_reads/samples_R2.fastq.gz

if [[ -f "$R1" && -f "$R2" ]]; then
  echo "FASTQ pair found:"
  echo "$R1"
  echo "$R2"
else
  echo "Missing FASTQ file. Check the raw_reads folder."
fi
EOF

chmod +x $VIROME/scripts/check_fastq_pairs.sh
bash $VIROME/scripts/check_fastq_pairs.sh

Guard scripts like this are worth writing once and reusing: they turn a confusing mid-pipeline crash into a one-line, human-readable error.

4.11 Key takeaways

• Keep one clean viromics-core environment for QC, assembly, and mapping, and give every complex viral tool its own isolated conda environment so incompatible dependencies never collide.
• Install with Miniforge and mamba, enabling the conda-forge and bioconda channels with strict channel priority for fast, reproducible solves.
• A tool is only half-installed until its database is in place: VirSorter2 (Guo et al. 2021), geNomad (Camargo et al. 2024), CheckV (Nayfach et al. 2021), eggNOG-mapper (Cantalapiedra et al. 2021), and iPHoP (Roux et al. 2023) each need a separate download, and iPHoP and DRAM databases can each reach hundreds of GB.
• Store all databases in one central $VIROME_DB folder and persist paths such as CHECKVDB and EGGNOG_DATA_DIR in your shell profile so every step finds them.
• Export each environment with conda env export --no-builds and verify the whole stack with a single installation-check script before running any real analysis.

Cantalapiedra, Carlos P., Ana Hernandez-Plaza, Ivica Letunic, Peer Bork, and Jaime Huerta-Cepas. 2021. “eggNOG-Mapper V2: Functional Annotation, Orthology Assignments, and Domain Prediction at the Metagenomic Scale.” Molecular Biology and Evolution 38 (12): 5825–29. https://doi.org/10.1093/molbev/msab293.

Roux, Simon, Antonio Pedro Camargo, Felipe H. Coutinho, Shareef M. Dabdoub, Bas E. Dutilh, et al. 2023. “iPHoP: An Integrated Machine Learning Framework to Maximize Host Prediction for Metagenome-Derived Viruses of Archaea and Bacteria.” PLOS Biology 21 (4): e3002083. https://doi.org/10.1371/journal.pbio.3002083.

4.12 Further reading

• geNomad official documentation and GitHub for install, database download, and end-to-end usage (Camargo et al. 2024); project site: https://github.com/apcamargo/genomad.
• VirSorter2 for the multi-classifier setup and virsorter setup database step (Guo et al. 2021).
• CheckV for how the quality database is built and consumed by the pipeline (Nayfach et al. 2021).
• Bioconda channel configuration and package discovery, the backbone of every environment here (Shen et al. 2016).

Camargo, Antonio Pedro, Simon Roux, Frederik Schulz, Michal Babinski, Yan Xu, Bin Hu, Patrick S. G. Chain, Stephen Nayfach, and Nikos C. Kyrpides. 2024. “Identification of Mobile Genetic Elements with geNomad.” Nature Biotechnology 42: 1303–12. https://doi.org/10.1038/s41587-023-01953-y.

Guo, Jiarong, Benjamin Bolduc, Ahmed A. Zayed, Arvind Varsani, Gabriela Dominguez-Huerta, Tom O. Delmont, Akbar A. Pratama, et al. 2021. “VirSorter2: A Multi-Classifier, Expert-Guided Approach to Detect Diverse DNA and RNA Viruses.” Microbiome 9: 37. https://doi.org/10.1186/s40168-020-00990-y.

Nayfach, Stephen, Antonio Pedro Camargo, Frederik Schulz, Emiley Eloe-Fadrosh, Simon Roux, and Nikos C. Kyrpides. 2021. “CheckV Assesses the Quality and Completeness of Metagenome-Assembled Viral Genomes.” Nature Biotechnology 39: 578–85. https://doi.org/10.1038/s41587-020-00774-7.

Shen, Wei, Shuai Le, Yan Li, and Fuquan Hu. 2016. “SeqKit: A Cross-Platform and Ultrafast Toolkit for FASTA/q File Manipulation.” PLOS ONE 11 (10): e0163962. https://doi.org/10.1371/journal.pone.0163962.

4.13 Chapter figure

Figure 4.1: A Linux viromics workstation: Ubuntu and Miniforge at the base, a clean core environment beside isolated per-tool environments, and a central databases folder feeding the analysis pipeline.

Tip🎨 Generate this figure

Save as: images/ch03-workstation-setup.png · Aspect ratio: 16:9 · Style: clean flat vector infographic, Codanics palette (teal #008b8b, navy #05043b, white background), no photorealism.

Prompt: Create a clean educational infographic of a Linux bioinformatics workstation set up for viromics. At the bottom, show a foundation layer labelled “Ubuntu” with a “Miniforge / mamba” installer and three stacked channel labels “conda-forge”, “bioconda”, “strict priority”. Above it, draw a large clean box labelled “viromics-core (QC · assembly · mapping · R/Python)” next to a neat row of smaller isolated boxes labelled “virsorter2”, “genomad”, “checkv”, “vclust”, “vcontact2”, “dramv”, “eggnog”, “iphop”, “phabox”, “wish”, each drawn as a separate lab-bench station to emphasise isolation. On the right, show a folder tree icon for the project directory with sub-folders raw_reads, assemblies, viral_identification, checkv, taxonomy, host_prediction, visualization, and a highlighted central “databases” cylinder connected by arrows to several tool boxes. Add a small terminal window showing a green check mark labelled “installation check”. Use teal and navy Codanics branding, clear sans-serif labels, and a tidy left-to-right, bottom-to-top flow.

4.14 Quiz: Linux Setup

Q1. Why should tools be installed in separate environments?

A. to avoid dependency conflicts B. to increase read length C. to remove viruses D. to replace databases

Note

Answer: A. Many viral tools require different dependency versions.

Q2. Which database variable is commonly set for CheckV?

A. CHECKVDB B. FASTQDB C. TREEPATH D. PHAGEDIR

Note

Answer: A. CheckV needs a database path.

Q3. Which command exports a conda environment?

A. conda env export –no-builds B. conda delete all C. mamba tree D. fastqc export

Note

Answer: A. Environment export improves reproducibility.

Q4. Which environment should run FastQC and MEGAHIT in this book?

A. viromics-core B. checkv C. iphop D. wish

Note

Answer: A. The core environment contains general pipeline tools.

Q5. Why are databases stored in a central folder?

A. to document and reuse large data B. to delete outputs C. to trim reads D. to make the CPU faster

Note

Answer: A. Database paths must be documented for reproducibility.

4.15 Interactive quiz: Linux setup

How to use this quiz: Select one option, click Check answer, and read the explanation. Use the reset button if you want to try again.

1. What is the main advantage of mamba over conda for large bioinformatics installs?

A. It performs microscopy B. It solves environments faster C. It replaces FASTQ files D. It only works on Windows

Mamba is widely used because it resolves complex environments faster than standard conda in many cases.

2. Why is Bioconda important for this book?

A. It is a major package source for bioinformatics tools B. It is a sequence aligner C. It removes adapters automatically D. It is a file format

Bioconda provides many of the tools used in viromics workflows, including assembly, QC, annotation, and taxonomy software.

3. What is the best reason to separate environments by tool group?

A. It guarantees zero bugs forever B. It reduces dependency conflicts C. It increases read length D. It eliminates the need for databases

Some viromics tools have heavy or incompatible dependencies. Separate environments make the setup more stable and easier to maintain.

4. Which file is most useful for recreating an environment on another machine?

A. README only B. environment.yml export C. PNG image D. BAM index only

An exported environment file documents packages and versions and makes the setup more reproducible.

5. Why should databases be organized carefully?

A. They are often large and multiple tools need fixed paths B. They only matter for plotting C. They are always included in FASTQ files D. They remove the need for citations

Viromics databases can be large, tool-specific, and path-sensitive. A clear layout prevents many downstream errors.