Workflow Type: Snakemake

Logo Snakemake Deploy Docker image Tests Mega-Linter License: Apache-2.0

V-pipe is a workflow designed for the analysis of next generation sequencing (NGS) data from viral pathogens. It produces a number of results in a curated format (e.g., consensus sequences, SNV calls, local/global haplotypes). V-pipe is written using the Snakemake workflow management system.


Different ways of initializing V-pipe are presented below. We strongly encourage you to deploy it using the quick install script, as this is our preferred method.

To configure V-pipe refer to the documentation present in config/

V-pipe expects the input samples to be organized in a two-level directory hierarchy, and the sequencing reads must be provided in a sub-folder named raw_data. Further details can be found on the website. Check the utils subdirectory for mass-importers tools that can assist you in generating this hierarchy.

We provide virus-specific base configuration files which contain handy defaults for, e.g., HIV and SARS-CoV-2. Set the virus in the general section of the configuration file:

  virus_base_config: hiv

Also see snakemake's documentation to learn more about the command-line options available when executing the workflow.


Tutorials for your first steps with V-pipe for different scenarios are available in the docs/ subdirectory.

Using quick install script

To deploy V-pipe, use the installation script with the following parameters:

curl -O ''
./ -w work

This script will download and install miniconda, checkout the V-pipe git repository (use -b to specify which branch/tag) and setup a work directory (specified with -w) with an executable script that will execute the workflow:

cd work
# edit config.yaml and provide samples/ directory
./vpipe --jobs 4 --printshellcmds --dry-run

Test data to test your installation is available with the tutorials provided in the docs/ subdirectory.

Using Docker

Note: the docker image is only setup with components to run the workflow for HIV and SARS-CoV-2 virus base configurations. Using V-pipe with other viruses or configurations might require internet connectivity for additional software components.

Create config.yaml or vpipe.config and then populate the samples/ directory. For example, the following config file could be used:

  virus_base_config: hiv

  snv: true
  local: true
  global: false
  visualization: true
  QA: true

Then execute:

docker run --rm -it -v $PWD:/work --jobs 4 --printshellcmds --dry-run

Using Snakedeploy

First install mamba, then create and activate an environment with Snakemake and Snakedeploy:

mamba create -c conda-forge -c bioconda --name snakemake snakemake snakedeploy
conda activate snakemake

Snakemake's official workflow installer Snakedeploy can now be used:

snakedeploy deploy-workflow --tag master .
# edit config/config.yaml and provide samples/ directory
snakemake --use-conda --jobs 4 --printshellcmds --dry-run


  • Conda

    Conda is a cross-platform package management system and an environment manager application. Snakemake uses mamba as a package manager.

  • Snakemake

    Snakemake is the central workflow and dependency manager of V-pipe. It determines the order in which individual tools are invoked and checks that programs do not exit unexpectedly.


    VICUNA is a de novo assembly software designed for populations with high mutation rates. It is used to build an initial reference for mapping reads with ngshmmalign aligner when a references/cohort_consensus.fasta file is not provided. Further details can be found in the wiki pages.

Computational tools

Other dependencies are managed by using isolated conda environments per rule, and below we list some of the computational tools integrated in V-pipe:

  • FastQC

    FastQC gives an overview of the raw sequencing data. Flowcells that have been overloaded or otherwise fail during sequencing can easily be determined with FastQC.


    Trimming and clipping of reads is performed by PRINSEQ. It is currently the most versatile raw read processor with many customization options.

  • ngshmmalign

    We perform the alignment of the curated NGS data using our custom ngshmmalign that takes structural variants into account. It produces multiple consensus sequences that include either majority bases or ambiguous bases.

  • bwa

    In order to detect specific cross-contaminations with other probes, the Burrows-Wheeler aligner is used. It quickly yields estimates for foreign genomic material in an experiment. Additionally, It can be used as an alternative aligner to ngshmmalign.


    To standardise multiple samples to the same reference genome (say HXB2 for HIV-1), the multiple sequence aligner MAFFT is employed. The multiple sequence alignment helps in determining regions of low conservation and thus makes standardisation of alignments more robust.

  • Samtools and bcftools

    The Swiss Army knife of alignment postprocessing and diagnostics. bcftools is also used to generate consensus sequence with indels.

  • SmallGenomeUtilities

    We perform genomic liftovers to standardised reference genomes using our in-house developed python library of utilities for rewriting alignments.

  • ShoRAH

    ShoRAh performs SNV calling and local haplotype reconstruction by using bayesian clustering.

  • LoFreq

    LoFreq (version 2) is SNVs and indels caller from next-generation sequencing data, and can be used as an alternative engine for SNV calling.

  • SAVAGE and Haploclique

    We use HaploClique or SAVAGE to perform global haplotype reconstruction for heterogeneous viral populations by using an overlap graph.


If you use this software in your research, please cite:

Fuhrmann, L., Jablonski, K. P., Topolsky, I., Batavia, A. A., Borgsmueller, N., Icer Baykal, P., Carrara, M. ... & Beerenwinkel, (2023). "V-Pipe 3.0: A Sustainable Pipeline for Within-Sample Viral Genetic Diversity Estimation." bioRxiv, doi:10.1101/2023.10.16.562462.


* software maintainer ; ** group leader


We encourage users to use the issue tracker. For further enquiries, you can also contact the V-pipe Dev Team .

Version History

v3.0.0.pre1 (latest) Created 10th Jun 2024 at 19:38 by Ivan Topolsky

Disable linter for templates

Frozen v3.0.0.pre1 7013890

v3.0.0.pre0 Created 2nd Nov 2023 at 09:55 by Ivan Topolsky

Keep the linter happy

Frozen v3.0.0.pre0 8ad191f

v2.99.3 Created 6th Nov 2022 at 11:12 by Ivan Topolsky

Tutorial tweaks

  • tipos
  • make the cluster step testable in jupytext
  • configure installer to use strict channel priorities

Co-authored-by: Anika John Co-authored-by: Lara Fuhrmann

Frozen v2.99.3 1df85e9

v2.99.2 Created 30th Mar 2022 at 17:51 by Ivan Topolsky

polishing the mass-importer staging

  • make it an option (-g, --staging)
  • play nicely with --append
  • typo fixes

Frozen v2.99.2 5054a3a

master @ 5054a3a (earliest) Created 30th Mar 2022 at 17:50 by Ivan Topolsky

polishing the mass-importer staging

  • make it an option (-g, --staging)
  • play nicely with --append
  • typo fixes

Frozen master 5054a3a
help Creators and Submitter
Topolsky, I., & Jablonski, K. P. (2024). V-pipe (main multi-virus version). WorkflowHub.

Views: 4429   Downloads: 603

Created: 30th Mar 2022 at 17:50

Last updated: 10th Jun 2024 at 19:38

help Attributions


Total size: 28.4 MB
Powered by
Copyright © 2008 - 2024 The University of Manchester and HITS gGmbH