config.sh.example

#!/usr/bin/env bash
# config.sh — external paths for the RaPDTool benchmark kit.
#
# Copy to config.sh, edit for your machine, and `source config.sh` before running any
# script that touches the reference databases (the full re-run path). The figure/table
# verification path needs only $TAXONKIT_DB.
#
#   cp config.sh.example config.sh   &&   $EDITOR config.sh   &&   source config.sh
#
# config.sh is git-ignored; only this template is committed. Every variable is read by
# the scripts via the environment, so nothing else needs editing.
#
# NOTE ON THE ASSIGNMENTS BELOW. They are plain `export VAR=value`, deliberately not
# `export VAR="${VAR:-value}"`. The defensive form lets a value already sitting in your
# shell silently override this file, so two people with an identical config.sh can
# benchmark against different databases with no warning — the failure mode is a complete
# run that produces plausible, wrong numbers. Here the file wins: source it and you know
# what you are pointing at. Editing and re-sourcing therefore always takes effect, and no
# `unset` is ever needed. To override one path for a single run, put it on the command
# line, which still takes precedence:
#
#   KRAKEN_DB_FULL=/other/db scripts/run_benchmark.sh …
#
# Keep the `:-` out when you edit: `${VAR:value}` (a missing dash) is not a default at
# all — it expands to the empty string, in both bash and zsh, without an error.

# --- taxonomy (needed by every rollup: census, detection, profile→CAMI) --------------
# NCBI taxdump directory for taxonkit. Pin a dated dump for reproducibility; the study
# used the 2026-07-10 dump (SHA-256 c1b91199…). Download:
#   https://ftp.ncbi.nlm.nih.gov/pub/taxonomy/taxdump_archive/taxdmp_<YYYY-MM-DD>.zip
export TAXONKIT_DB=/path/to/taxonkit_dump

# --- RaPDTool reference set (only for the census / mirror-selection scripts) ----------
# Directory holding acc_taxid_strain.tsv, taxid_lineage.tsv and db/ (the type-material
# genomes). And the mash sketch DB (type_30209genomes.msh) used by the mirror-distance
# selection.
export FOCUS_DB=/path/to/focus_build
# NOTE: use the 30,209-sketch database. An earlier build (0726_30213genomes.msh)
# carried four extra sketches built from *_cds_from_genomic / *_rna_from_genomic
# files rather than genomes; the rRNA sketch is conserved enough to match unrelated
# samples at moderate distance and produced a spurious genus call in every dataset.
# The genome set is otherwise identical.
export MASH_DB=/path/to/type_30209genomes.msh
export MASH_BIN=mash                 # mash executable (on PATH is fine)

# --- competitor databases (only for the census and the full benchmark re-run) --------
# Give the DATABASE DIRECTORIES; everything else is derived from them.
export KRAKEN_STD_DB=/path/to/kraken2_db/standard
export KRAKEN_16_DB=/path/to/kraken2_db/standard16
export KRAKEN_8_DB=/path/to/kraken2_db/standard8
export MPA_DB=/path/to/metaphlan_db
export MPA_PKL_NAME=mpa_vJan26_CHOCOPhlAnSGB_202605.pkl
# derived — the census scripts read the inspect.txt / .pkl files:
export KRAKEN_STD_INSPECT="$KRAKEN_STD_DB/inspect.txt"
export KRAKEN_16_INSPECT="$KRAKEN_16_DB/inspect.txt"
export KRAKEN_8_INSPECT="$KRAKEN_8_DB/inspect.txt"
export MPA_PKL="$MPA_DB/$MPA_PKL_NAME"
# aliases run_benchmark.sh reads directly (Step 1 passes these as env):
export KRAKEN_DB_FULL="$KRAKEN_STD_DB"
export KRAKEN_DB_CAP16="$KRAKEN_16_DB"
export KRAKEN_DB_CAP8="$KRAKEN_8_DB"

# --- OPAL (accuracy step; installed in a separate Python 3.11 env — see README) -------
export OPAL_PY=/path/to/envs/opal/bin/python
export OPAL_BIN=/path/to/envs/opal/bin/opal.py

# --- where simulated read datasets live (regenerate with make_mock.sh --seed 42) ------
export MOCK_ROOT=/path/to/mock_datasets       # holds mock_<name>/
export MIRROR_FNA_DIR=/path/to/mirror_db/fna_dist  # datasets download dir
export ZYMO_DIR=/path/to/ZymoBIOMICS_db    # ENA PRJEB29504 reads

# --- tool launchers for run_benchmark.sh (see README Step 1) --------------------------
# BENCH_ENV_BIN is the bin/ of the conda env from Getting started A — the directory
# holding the COMPARED TOOLS' executables (kraken2, bracken, metaphlan, bowtie2, iss,
# megahit, taxonkit). It is NOT this kit's scripts/ directory: the kit's own scripts
# need no variable, you run them as `scripts/<name>` from the repository base.
#   $ ls "$BENCH_ENV_BIN"/{kraken2,bracken,metaphlan,bowtie2}   # all four must exist
# Typically: $HOME/miniconda3/envs/rapdtool_bench/bin  (`conda activate rapdtool_bench;
# dirname $(which kraken2)` prints it).
#
# Why absolute rather than PATH: run_benchmark.sh measures peak RAM and wall time, so it
# must pin exactly WHICH binary it measures. If a shell rc puts '.' or './bin' first,
# resolution depends on the current directory and every tool exits 126/127 in ~0 s — the
# matrix then completes with no data. Setting this also prepends the directory to PATH,
# because MetaPhlAn shells out to its sibling bowtie2 and otherwise dies AFTER loading
# ~7 GB, which looks like an unrelated failure.
export BENCH_ENV_BIN=/path/to/envs/rapdtool_bench/bin

# The RaPDTool launcher itself (the wrapper script, not a directory).
export RAPDTOOL=/path/to/RaPDTool/scripts/rapdtool

# --- MAG-recovery comparator (Step 5c; only for scripts/run_metawrap.sh) ---------------
# MetaWRAP + CheckM run from a biocontainer; the common-evaluator miComplete re-scoring
# runs inside RaPDTool's own SIF (so both bin sets are scored with the same tool).
#   apptainer pull docker://quay.io/biocontainers/metawrap-mg:1.3.0--hdfd78af_1
#   CheckM DB: https://data.ace.uq.edu.au/public/CheckM_databases/checkm_data_2015_01_16.tar.gz
export METAWRAP_SIF=/path/to/metawrap.sif        # metawrap-mg 1.3.0 biocontainer
export CHECKM_DB=/path/to/checkm_db                 # checkm_data_2015_01_16 (1.4 GB)
export RAPDTOOL_SIF=/path/to/rapdtool_v2.3.0.sif # provides miComplete for re-scoring