WEPP (Wastewater-Based Epidemiology using Phylogenetic Placements) is a pathogen-agnostic pipeline that enhances wastewater surveillance by leveraging the pathogen’s full phylogeny. It reports haplotype and lineage abundances, maps reads parsimoniously to selected haplotypes, and flags Unaccounted Alleles — those observed in the sample but unexplained by selected haplotypes, potentially indicating novel variants (Figure 1A). An interactive dashboard enables visualization of haplotypes in the global phylogenetic tree (Figure 1B(i)) and read-level analysis by selecting a haplotype (Figure 1B(ii)). Additional information about individual reads or haplotypes can be accessed by clicking on their corresponding objects (Figures 1B(iii-iv)), respectively.
WEPP performs parsimonious read placement on the mutation-annotated tree (MAT) to select a subset of haplotypes and adds their neighbors to form an initial candidate pool, which is passed to a deconvolution algorithm to estimate their relative abundances. WEPP retains haplotypes above an abundance threshold, and iteratively adds their neighbors and recomputes abundances until convergence or a maximum iteration count. An outlier detection algorithm flags Unaccounted Alleles from the deconvolution residue (Figure 1C).
WEPP offers multiple installation methods.
- Bioconda (Recommended)
- Docker image from DockerHub
- Dockerfile
- Shell Commands
Step 1: Create a new conda environment for WEPP.
conda create --name wepp-env
conda activate wepp-env
conda config --env --add channels bioconda
conda config --env --add channels conda-forge
conda config --env --set channel_priority flexible
conda install weppStep 2: Confirm proper working by running the following command. This should print WEPP's help menu.
run-wepp help --cores 1 --use-condaStep 3: Create a data directory and start analyzing your samples with WEPP. If you are running samples from multiple data directories, specify the .snakemake directory created in one run as the --conda-prefix for the others to avoid redundant creation of Snakemake conda environments.
All set to try the examples.
The Docker image includes all dependencies required to run WEPP.
Step 1: Get the image from DockerHub
docker pull pranavgangwar/wepp:latestStep 2: Start and run Docker container. The command below will take you inside the docker container with WEPP already installed.
# -p <host_port>:<container_port> → Maps container port to a port on your host (Accessing Dashboard, NOT needed otherwise)
# Replace <host_port> with your desired local port (e.g., 80 or 8080)
# Use this command if your datasets can be downloaded from the Web
docker run -it -p 80:80 pranavgangwar/wepp:latest
# Use this command if your datasets are present in your current directory
docker run -it -p 80:80 -v "$PWD":/WEPP -w /WEPP pranavgangwar/wepp:latestStep 3: Confirm proper working by running the following command. This should print WEPP's help menu.
run-wepp help --cores 1 --use-condaAll set to try the examples.
linux/amd64 platform. While it can run on arm64 systems (e.g., Apple Silicon or Linux aarch64) via emulation, this may lead to reduced performance.
The Dockerfile contains all dependencies required to run WEPP.
Step 1: Clone the repository
git clone --recurse-submodules https://github.com/TurakhiaLab/WEPP.git
cd WEPP
chmod +x run-weppStep 2: Build a Docker Image
cd docker
docker build -t wepp .
cd ..Step 3: Start and run Docker container. The command below will take you inside the docker container with the view of the current directory.
# -p <host_port>:<container_port> → Maps container port to a port on your host (Accessing Dashboard, NOT needed otherwise)
# Replace <host_port> with your desired local port (e.g., 80 or 8080)
docker run -it -p 80:80 -v "$PWD":/workspace -w /workspace weppAll set to try the examples.
Users without sudo access are advised to install WEPP via Docker Image.
Step 1: Clone the repository
git clone --recurse-submodules https://github.com/TurakhiaLab/WEPP.git
cd WEPP
chmod +x run-weppStep 2: Update ~/.bashrc for linux or ~/.zshrc for macOS
echo "
run-wepp() {
snakemake -s $PWD/workflow/Snakefile \"\$@\"
}
export -f run-wepp
" >> ~/.bashrc
source ~/.bashrcStep 3: Install dependencies (might require sudo access) WEPP depends on the following common system libraries, which are typically pre-installed on most development environments:
- wget
- curl
- pip
- build-essential
- python3-pandas
- pkg-config
- zip
- cmake
- libtbb-dev
- libprotobuf-dev
- protobuf-compiler
- libopenmpi-dev
- snakemake
- conda
- nodejs(v18+)
- nginx
For Ubuntu users with sudo access, if any of the required libraries are missing, you can install them with:
sudo apt-get update
sudo apt-get install -y wget pip curl python3-pip build-essential python3-pandas pkg-config zip cmake libtbb-dev libprotobuf-dev protobuf-compiler snakemake nginxNote: WEPP expects the python command to be available. If your system only provides python3, you can optionally set up a symlink:
update-alternatives --install /usr/bin/python python /usr/bin/python3 1If you do not have Node.js v18 or higher installed, follow these steps to install Node.js v22:
# Update and install prerequisites
apt-get install -y curl gnupg ca-certificates
# Add NodeSource Node.js 22 repo
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
# Install Node.js 22
apt-get install -y nodejs# Install Yarn package manager globally
npm install -g yarnIf your system doesn't have Conda, you can install it with:
wget -O Miniforge3.sh "https://github.com/conda-forge/miniforge/releases/download/24.11.3-2/Miniforge3-24.11.3-2-Linux-x86_64.sh"
bash Miniforge3.sh -b -p "${HOME}/conda"
source "${HOME}/conda/etc/profile.d/conda.sh"
source "${HOME}/conda/etc/profile.d/mamba.sh"All set to try the examples.
The following steps will download real wastewater datasets and analyze them using WEPP.
Step 1: Download the RSV-A test dataset
mkdir -p data/RSVA_real
cd data/RSVA_real
wget ftp://ftp.sra.ebi.ac.uk/vol1/fastq/ERR147/011/ERR14763711/ERR14763711_1.fastq.gz ftp://ftp.sra.ebi.ac.uk/vol1/fastq/ERR147/011/ERR14763711/ERR14763711_2.fastq.gz https://hgdownload.gi.ucsc.edu/hubs/GCF/002/815/475/GCF_002815475.1/UShER_RSV-A/2025/04/25/rsvA.2025-04-25.pb.gz https://ftp.ncbi.nlm.nih.gov/genomes/all/GCF/002/815/475/GCF_002815475.1_ASM281547v1/GCF_002815475.1_ASM281547v1_genomic.fna.gz
gunzip GCF_002815475.1_ASM281547v1_genomic.fna.gz
mv ERR14763711_1.fastq.gz ERR14763711_R1.fastq.gz
mv ERR14763711_2.fastq.gz ERR14763711_R2.fastq.gz
cd ../../This will save the datasets on a separate data/RSVA_real folder within the repository.
Step 2: Run the pipeline
run-wepp --config DIR=RSVA_real FILE_PREFIX=test_run TREE=rsvA.2025-04-25.pb.gz REF=GCF_002815475.1_ASM281547v1_genomic.fna CLADE_LIST=annotation_1 CLADE_IDX=0 DASHBOARD_ENABLED=True --cores 32 --use-condaStep 3: Analyze Results
All results generated by WEPP are available in the results/RSVA_real directory. These include haplotype and lineage abundances, associated uncertain haplotypes, and the potential haplotypes corresponding to each detected unaccounted allele.
Step 1: Download the SARS-CoV-2 test dataset
mkdir -p data/SARS_COV_2_real
cd data/SARS_COV_2_real
wget ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR185/041/SRR18541041/SRR18541041_1.fastq.gz ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR185/041/SRR18541041/SRR18541041_2.fastq.gz https://hgdownload.gi.ucsc.edu/goldenPath/wuhCor1/UShER_SARS-CoV-2/2021/12/05/public-2021-12-05.all.masked.pb.gz
mv SRR18541041_1.fastq.gz SRR18541041_R1.fastq.gz
mv SRR18541041_2.fastq.gz SRR18541041_R2.fastq.gz
cp ../../NC_045512v2.fa .
cd ../../This will save the datasets on a separate data/SARS_COV_2_real folder within the repository.
Step 2: Run the pipeline
run-wepp --config DIR=SARS_COV_2_real FILE_PREFIX=test_run TREE=public-2021-12-05.all.masked.pb.gz REF=NC_045512v2.fa DASHBOARD_ENABLED=True --cores 32 --use-condaStep 3: Analyze Results
All results generated by WEPP are available in the results/SARS_COV_2_real directory. These include haplotype and lineage abundances, associated uncertain haplotypes, and the potential haplotypes corresponding to each detected unaccounted allele.
We assume that all wastewater samples are organized in the data directory, each within its own subdirectory given by DIR argument (see Run Command). For each sample, WEPP generates intermediate and output files in corresponding subdirectories under intermediate and results, respectively.
Each created DIR inside data is expected to contain the following files:
- Sequencing Reads: Ending with
*_R{1/2}.fastq.gzfor paired-ended reads and*.fastq.gzfor single-ended. - Reference Genome in FASTA format
- Mutation-Annotated Tree (MAT)
- [OPTIONAL] Genome Masking File:
mask.bed, whose third column specifies sites to be excluded from analysis. - [OPTIONAL] Taxonium
.jsonlfile to be used for visualizing results in the WEPP dashboard.
Visualization of WEPP's workflow directories
📁 WEPP
└───📁data # [User Created] Contains data to analyze
├───📁SARS_COV_2_real # SARS-CoV-2 run wastewater samples - 1
├───sars_cov_2_reads_R1.fastq.gz # Paired-ended reads
├───sars_cov_2_reads_R2.fastq.gz
├───sars_cov_2_reference.fa
├───mask.bed # OPTIONAL
├───sars_cov_2_taxonium.jsonl.gz # OPTIONAL
└───sars_cov_2_mat.pb.gz
└───📁intermediate # [WEPP Generated] Contains intermediate stage files
├───📁SARS_COV_2_real
├───file_1
└───file_2
└───📁results # [WEPP Generated] Contains final WEPP results
├───📁SARS_COV_2_real
├───file_1
└───file_2
The WEPP Snakemake pipeline requires the following arguments, which can be provided either via the configuration file (config/config.yaml) or passed directly on the command line using the --config argument. The command line arguments take precedence over the config file.
DIR- Folder name containing the wastewater reads.FILE_PREFIX- File Prefix for all intermediate files.REF- Reference Genome in fasta.TREE- Mutation-Annotated Tree.SEQUENCING_TYPE- Sequencing read type (s:Illumina single-ended, d:Illumina double-ended, or n:ONT long reads).PRIMER_BED- BED file argument for primers, with few primers provided in theprimersfolder. Requires path to the file.MIN_AF- Alleles with an allele frequency below this threshold in the reads will be masked (Illumina: 0.5%, Ion Torrent: 1.5%, ONT: 2%).MIN_DEPTH- Sites with read depth below this threshold will be masked.MIN_Q- Alleles with a Phred score below this threshold in the reads will be masked.MIN_PROP- Minimum Proportion of haplotypes (Wastewater Samples: 0.5%, Clinical Samples: 5%).MIN_LEN- Minimum read length to be considered after ivar trim (Deafult: 80).MAX_READS- Maximum number of reads considered by WEPP from the sample. Helpful for reducing runtime.CLADE_LIST- List the clade annotation schemes used in the MAT. SARS-CoV-2 MAT uses both nextstrain and pango lineage naming systems, so use "nextstrain,pango" for it.CLADE_IDX- Index used for assigning clades to selected haplotypes from MAT. Use '1' for Pango naming and '0' for Nextstrain naming for SARS-CoV-2. Other pathogens usually follow a single lineage annotation system, so work with '0'. In case of NO lineage annotations, use '-1'. Lineage Annotations could be checked by running: "matUtils summary -i {TREE} -C {FILENAME}" -> Use '0' for annotation_1 and '1' for annotation_2.DASHBOARD_ENABLED- Set toTrueto enable the interactive dashboard for viewing WEPP results, orFalseto disable it.TAXONIUM_FILE[Optional] - Name of the user-provided Taxonium.jsonlfile for visualization. If specified, this file will be used instead of generating a new one from the given MAT. Ensure that the provided Taxonium file corresponds to the same MAT used for WEPP.
WEPP's snakemake workflow requires DIR and FILE_PREFIX as config arguments through the command line, while the remaining ones can be taken from the config file. It also requires --cores from the command line, which specifies the number of threads used by the workflow.
Examples:
- Using all the parameters from the config file.
run-wepp --config DIR=SARS_COV_2_real FILE_PREFIX=test_run TREE=sars_cov_2_mat.pb.gz REF=sars_cov_2_reference.fa --cores 32 --use-conda- Overriding MIN_Q and CLADE_IDX through command line.
run-wepp --config DIR=SARS_COV_2_real FILE_PREFIX=test_run TREE=sars_cov_2_mat.pb.gz REF=sars_cov_2_reference.fa MIN_Q=25 CLADE_IDX=1 --cores 32 --use-conda- To visualize results from a previous WEPP analysis that was run without the dashboard, set
DASHBOARD_ENABLEDtoTrueand re-run only the dashboard components, without reanalyzing the dataset.
run-wepp --config DIR=SARS_COV_2_real FILE_PREFIX=test_run TREE=sars_cov_2_mat.pb.gz REF=sars_cov_2_reference.fa MIN_Q=25 CLADE_IDX=1 DASHBOARD_ENABLED=True --cores 32 --use-conda --forcerun dashboard_serveMutation-annotated trees (MAT) for different pathogens are maintained by the UShER team, which can be found here. You can also create your own MAT for any pathogen from the consensus genome assemblies using viral_usher.
WEPP generates output files for each sample in its corresponding subdirectory under results. Some of the key files are described below:
-
lineage_abundance.csv- Reports the estimated abundance of different lineages detected in the wastewater sample. -
haplotype_abundance.csv- Provides the abundance and lineage information for each selected haplotype (internal nodes or clinical sequences) inferred from the wastewater sample. -
haplotype_uncertainty.csv- Lists the maximum single-nucleotide distance and all haplotypes that could not be distinguished from one another for each selected haplotype.- A non-zero nucleotide distance indicates that sequencing reads did not cover the distinguishing sites between haplotypes.
- A zero distance indicates that the haplotypes are identical.
-
haplotype_coverage.csv- Contains the fraction of each selected haplotype that is supported by parsimonious read-to-haplotype assignments. -
unaccounted_alleles.txt- Reports the residue, allele frequency, and sequencing depth for each unaccounted allele detected in the sample. Alleles with higher residue values are more likely to originate from a novel variant, as they were not adequately represente by the selected haplotypes.
The WEPP dashboard provides an interactive interface for exploring inferred haplotypes, lineage abundances, and unaccounted alleles. You can either run it as part of a WEPP analysis or launch it locally after completing a WEPP run on your server by copying the results directory.
Option 1: Run the dashboard during a WEPP run
Step 1: Enable the dashboard in your WEPP command.
run-wepp --config ... DASHBOARD_ENABLED=True --cores N --use-conda
Step 2: If you are running WEPP on a remote machine, use the SSH port forwarding to access the dashboard in your local browser.
ssh -L 8080:localhost:80 user@remote_host
Step 3: Open the dashboard in your browser at:
http://localhost:8080
Option 2: Visualize results on your local machine (requires Docker)
You can also analyze your samples with WEPP on a server and run the dashboard locally.
Step 1: Enable the dashboard in your WEPP command.
run-wepp --config ... DASHBOARD_ENABLED=True --cores N --use-conda
Step 2: Copy the results directory to your local machine.
Run the following command on your local computer.
scp -r user@remote_host:/path_to_WEPP/results /path_to_local_directory/
Step 3: Pull the WEPP dashboard Docker image.
docker pull pratikkatte7/wepp-dashboard
Step 4: Launch the dashboard by running the container and mounting the results directory.
docker run -it \
-v "/path_to_local_directory/results:/app/taxonium_backend/results" \
-p 8080:80 \
pratikkatte7/wepp-dashboard
Step 5: Open the dashboard in your browser at:
http://localhost:8080
In case of a failure or unexpected output, below are some common causes and possible solutions:
-
Run Failure- Check whether reads were successfully aligned by minimap2 by inspecting thealignment.samfile in theintermediatedirectory. If enough reads are present but thefilterrule crashes immediately, the sample may contain more reads than WEPP can efficiently handle. Use theMAX_READSparameter to downsample the input. For typical short-read datasets, setting this to ~3 million reads generally works well. -
Missing Lineages- If expected lineages are absent from thelineage_abundance.csvin theresultsdirectory, either the MAT does not contain any lineage annotations, or an incorrectCLADE_IDXargument was provided. -
Uncertainty in Lineages and Haplotypes- Uncertain lineage or haplotype assignments usually occur when:- Sequencing depth is low
- Entire genome is not sufficiently covered
- Read quality is poor and iVar trims and discards a large number of reads.
Check
lineage_abundance.csv,haplotype_abundance.csv, andhaplotype_uncertainty.csvin theresultsdirectory. You can also reviewalignment.samin theintermediatedirectory to see how many reads were used by WEPP and compare them with the reads provided as input. -
Long Runtimes- You can increase the number of threads using the--coresargument, or reduce the number of reads withMAX_READS(may affect results).
We welcome contributions from the community to enhance the capabilities of WEPP. If you encounter any issues or have suggestions for improvement, please open an issue on WEPP GitHub page. For general inquiries and support, reach out to our team.
If you use WEPP in your research or publications, please cite the following paper:
- Pranav Gangwar, Pratik Katte, Manu Bhatt, Yatish Turakhia, "WEPP: Phylogenetic Placement Achieves Near-Haplotype Resolution in Wastewater-Based Epidemiology", medRxiv 2025.06.09.25329287; doi: 10.1101/2025.06.09.25329287