Tutorial
This tutorial will walk you through the installation and usage of ViroProfiler. ViroProfiler is containerized with Docker, and can be used with multiple container engines, including Docker, Singularity, Podman, Shifter and Charliecloud (see docs). In this tutorial, we will use Singularity as an example.
Install ViroProfiler
ViroProfiler is built on Nextflow, which means it is very easy to install with a single command:
# Install ViroProfiler and set up the database
nextflow run deng-lab/viroprofiler -r main -profile singularity --mode "setup"
By default, database will be downloaded to the $HOME/viroprofiler directory. You can change database path using the --db parameter. For example, if you want to download the database to /db/path directory, you can run the following command,
- It is recommended to set the
NXF_SINGULARITY_CACHEDIRorsingularity.cacheDirNextflow options when using the Singularity profile, so that singularity images can be stored and re-used from a central location for future pipeline runs.- If you are using
Docker, please replace the-profile singularitywith-profile docker.
When you run the above command, Nextflow automatically pulls the pipeline code from GitHub and stores it as a cached version. When running the pipeline after this, it will always use the cached version if available. To make sure that you're running the latest version of the pipeline, make sure that you regularly update the cached version of the pipeline:
Run the ViroProfiler pipeline
Prepare input files
Samplesheet input
To execute the pipeline users must provide sequencing reads as input. You will need to create a samplesheet with information about the samples you would like to analyse before running the pipeline.
The samplesheet is a comma-separated file with 3 columns. The first column is the sample name, the second column is the full path to the first read file, and the third column is the full path to the second read file. The sample name can be any string, but it is recommended to use the sample ID. The sample name will be used as the prefix of the output files. The following is an example of a samplesheet with three samples:
sample,fastq_1,fastq_2
sampleID1,AEG588A1_S1_L002_R1_001.fastq.gz,AEG588A1_S1_L002_R2_001.fastq.gz
sampleID2,AEG588A2_S2_L002_R1_001.fastq.gz,AEG588A2_S2_L002_R2_001.fastq.gz
sampleID3,AEG588A3_S3_L002_R1_001.fastq.gz,AEG588A3_S3_L002_R2_001.fastq.gz
| Column | Description |
|---|---|
sample |
Custom sample name. This entry will be identical for multiple sequencing libraries/runs from the same sample. |
fastq_1 |
Full path to FastQ file for Illumina short reads 1. File has to be gzipped and have the extension ".fastq.gz" or ".fq.gz". |
fastq_2 |
Full path to FastQ file for Illumina short reads 2. File has to be gzipped and have the extension ".fastq.gz" or ".fq.gz". |
An example samplesheet
has been provided with the pipeline, under assets/.
Use the --input parameter to specify its location, or set input in the params.yml file.
The sequencing reads can be raw reads or cleaned reads. By default, ViroProfiler will assume the input reads are raw reads. If you want to use cleaned reads, you can set parameter --reads_type "clean" in command line, or set reads_type: "clean" in the params.yml file. If the input reads are cleaned reads, the pipeline will skip the cleaning step (removing adapters, low quality reads and contaminant reads).
If you already have assembled contigs, you can skip the assembly step by setting --input_contigs parameter to specify the path to the contigs file. The contigs file should be in FASTA format.
Run the pipeline
The typical command for running the pipeline is as follows:
This will launch the pipeline with the singularity configuration profile. See Selecting NF profiles for more information about profiles.
You may create a config file to customize the parameters of the pipeline and use -c to load the config. Please check custom.config for an example. You may also specify the parameters in a file and use -params-file to load the parameters. Please check params.yml for an example. Then the command for running the pipeline is as follows:
nextflow run deng-lab/viroprofiler \
--input samplesheet.csv \
-profile singularity \
-c custom.config \
-params-file params.yml
Note that the pipeline will create the following files in your working directory:
work # Directory containing the nextflow working files
output # Output folder (can be modified with `--outdir` parameter)
.nextflow.log # Log file from Nextflow
# Other nextflow hidden files, eg. history of pipeline runs and old logs.
Reproducible data analysis
For reproducibility, we recommend using a specific version of ViroProfiler. You can always run a specific version of ViroProfiler by specifying the version number. This ensures that a specific version of the pipeline code and software are used when you run your pipeline. If you keep using the same tag, you'll be running the same version of the pipeline, even if there have been changes to the code since. First, go to the deng-lab/viroprofiler releases page and find the latest version number (eg. v1.0.1). Then specify this when running the pipeline with -r (one hyphen) - eg. -r v1.0.1. This version number will be logged in reports when you run the pipeline, so that you'll know what you used when you look back in the future. For example, to run version v1.0.1 of the pipeline:
nextflow run deng-lab/viroprofiler -r v1.0.1 -profile singularity \
--input samplesheet.csv --db /path/to/db
If the pipeline fails, you can resume the pipeline from the last successful step by adding -resume to the command. For example:
nextflow run deng-lab/viroprofiler -r v1.0.1 -profile singularity -resume \
--input samplesheet.csv --db /path/to/db
Description of pipeline options and parameters
To get a list of pipeline options and parameters, run the pipeline with the --help flag:
nextflow run deng-lab/viroprofiler --help
# get full list of options and parameters
nextflow run deng-lab/viroprofiler --help --show_hidden_params
Tip
All these parameters are configurable through a configuration file. We encourage users to use the configuration file since it will keep your execution cleaner and more readable. See a config example.
Core Nextflow options
NB: These options are part of Nextflow and use a single hyphen (pipeline parameters use a double-hyphen).
-profile
Use this parameter to choose a configuration profile. Profiles can give configuration presets for different compute environments. See profile for more information.
-resume
Specify this when restarting a pipeline. Nextflow will use cached results from any pipeline steps where the inputs are the same, continuing from where it got to previously. For input to be considered the same, not only the names must be identical but the files' contents as well. For more info about this parameter, see this blog post.
You can also supply a run name to resume a specific run: -resume [run-name]. Use the nextflow log command to show previous run names.
-c
Specify the path to a specific config file (this is a core Nextflow command). See the nf-core website documentation for more information.
Custom pipeline parameters
Input/output options
Parameter |
Required | Default | Description |
|---|---|---|---|
--input |
NA | Input samplesheet describing all the samples to be analysed | |
--outdir |
output | Name of directory to store output values | |
--db |
${HOME}/viroprofiler | Path containing required ViroProfiler databases | |
--mode |
all | Last stage to run. setup builds the databases and reads no samplesheet; the others are cumulative, so contiglib runs everything fastp runs and then assembles, cleans and dereplicates. fastqc and fastp are incompatible with --reads_type clean, which skips both |
|
--input_contigs |
false | Path to pre-assembled contigs (skips assembly) | |
--single_end |
false | Set to true for single-end reads |
|
--reads_type |
raw | Input reads type: raw or clean (skip trimming) |
On/Off processes
Parameter |
Required | Default | Description |
|---|---|---|---|
--use_checkamg |
true | Use CheckAMG to curate auxiliary genes (AMG/AReG/APG) | |
--use_vibrant |
true | Run VIBRANT. It contributes a third opinion to the candidate-virus union and a genome quality call to the TSE; geNomad does detection and CheckAMG does auxiliary genes | |
--use_dram |
true | Use DRAM-v for functional annotation | |
--use_iphop |
true | Use iPHoP for viral-host prediction | |
--use_abricate |
false | Use abricate for AMR gene detection | |
--use_decontam |
false | Remove host contamination from reads | |
--use_eggnog |
false | Use eggNOG-mapper for protein annotation | |
--use_kraken2 |
false | Use Kraken2 for read classification | |
--use_phamb |
false | Download the VOGDB and miComplete HMM sets that PHAMB's features are computed from. Only affects --mode setup; the binner itself is selected with --binning |
Other parameters
Parameter |
Required | Default | Description |
|---|---|---|---|
--prot_cluster_min_similarity |
0.7 | Minimum similarity of protein seqs in the same cluster | |
--prot_cluster_min_coverage |
0.9 | Minimum similarity of protein seqs in the same cluster | |
--binning |
false | Which binning tool to use: vrhyme, phamb or false. phamb is amd64-only, because it classifies VAMB's clusters and VAMB has no linux-aarch64 build; it is also approximate, because its random forest was fitted on DeepVirFinder scores and is fed geNomad's instead |
|
--binning_minlen_contig |
5000 | Contigs shorter than this value will not be used for binning | |
--binning_minlen_bin |
5000 | Bins shorter than this value will be removed from downstream analyses | |
--genomad_preset |
"default" | geNomad post-classification filtering: default, conservative or relaxed |
|
--genomad_splits |
0 | Split geNomad's MMseqs2 marker search into this many chunks to cap memory use; 0 leaves it unsplit | |
--checkamg_min_weight |
0.6 | Minimum CheckAMG AMG weight for an auxiliary gene to be reported; higher is more conservative | |
--virsorter2_groups |
"dsDNAphage" | Viral category detected by VirSorter2, could be any combination of dsDNAphage,NCLDV,RNA,ssDNA,lavidaviridae |
|
--contig_minlen_vcontact3 |
10000 | Contigs/Bins short than this value will not be used in vConTACT3 |
|
--vcontact3_db_version |
232 | vConTACT3 reference database version. Each vConTACT3 release accepts exactly one version | |
--replicyc |
"bacphlip" | Viral replication cycle prediction method, could be either replidec or bacphlip |
Max job request options
Set the top limit for requested resources for any single job. If you are running on a smaller system, a pipeline step requesting more resources than are available may cause the Nextflow to stop the run with an error. These options allow you to cap the maximum resources requested by any single job so that the pipeline will run on your system.
Note
Note that you can not increase the resources requested by any job using these options. For that you will need your own configuration file. See the nf-core website for details.
| Parameter | Default | Description |
|---|---|---|
--max_cpus |
16 | Maximum number of CPUs that can be requested for any single job |
--max_memory |
128.GB | Maximum amount of memory that can be requested for any single job |
--max_time |
120.h | Maximum amount of time that can be requested for any single job |
Outputs
A glimpse over the main outputs produced by ViroProfiler is given at output section.