viralrecon
nf-core/viralrecon
Assembly and intrahost/low-frequency variant calling for viral samples
Key tools
Run it
nfclaw run viralrecon --input samplesheet.csv --outdir results -profile dockernextflow run pipelines/viralrecon/upstream -profile docker --input samplesheet.csv --outdir resultsnfclaw run viralrecon --demo --outdir results # adds the upstream test profile (-profile test,docker)Inputs
| column | type | required | allowed values | constraints |
|---|---|---|---|---|
sample | string or integer | yes | matches ^\S+$ | |
fastq_1 | string (file path) | no | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ | |
fastq_2 | string (file path) | no | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ | |
barcode | integer | no |
--input must match ^\S+\.csv$.
The samplesheet is a CSV with this header (the columns the schema requires); fill each value per the table above and reference.md (no example value is invented here):
sampleAny of the optional columns above may be appended to the header when your data needs them: fastq_1, fastq_2, barcode.
From data files. --input may also be the data files — a directory (searched recursively), a quoted glob, or files (--input once per file) — from which nfclaw writes this samplesheet: sample from file names; fastq_1/fastq_2 from FastQ files (mates paired by _R1/_R2, or by _1/_2 when their read names show they are mates). Set other columns with --sheet-set COLUMN=VALUE. Preview it with --check; a run records it in <outdir>/provenance/ for replay.
Reference genome
No reference genome is set by default: supply your own reference. A genome name alone does not specify where reference files come from. Confirm the selected reference's paths and source in the pinned upstream/nextflow.config and upstream/conf/ before running. To supply your own reference, use e.g. --fasta; the reference_genome_options group in reference.md lists every reference option.
Resources
Resource requests follow the pipeline's configs and selected profiles. nf-core's resource labels often assume a server — a single step can request far more memory than a workstation has, and retry rules can increase requests. If a run fails with Process requirement exceeds available memory (or CPUs), cap every request, and every retry, at what this machine actually has:
nfclaw run viralrecon --input samplesheet.csv --outdir results -profile docker \ --limit-cpus 4 --limit-memory 15.GBnfclaw turns those into Nextflow's process.resourceLimits and passes them as a -c config — the mechanism nf-core prescribes for exactly this (docs). Set them to the machine's real capacity. --limit-time DURATION also caps how long any one task may run: a task that needs longer is stopped, and so is every retry, so set it only as a deliberate ceiling, never as a guess at how long the analysis takes. The generated config is kept in <outdir>/provenance/, so commands.sh replays the run under the same ceiling.
Nextflow engine
This release declares nextflowVersion = '!>=25.04.0'.
To pin this release's declared minimum engine — useful when a newer Nextflow has incompatible config parsing:
nfclaw run viralrecon ... --nxf-ver 25.04.0--nxf-ver is recorded in <outdir>/provenance/, so the replay uses the same engine. See known-issues.
Demo
nfclaw run viralrecon --demo --outdir results # adds the upstream test profile (-profile test,docker)Samplesheet
A CSV with this header (the columns the schema requires). Fill each value per the constraints below; optional columns from the table may be appended.
sample| Column | Type | Required | Allowed / constraints |
|---|---|---|---|
sample | string or integer | required | matches ^\S+$ |
fastq_1 | string (file path) | optional | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ |
fastq_2 | string (file path) | optional | matches ^([\S\s]*\/)?[^\s\/]+\.f(ast)?q\.gz$ |
barcode | integer | optional | — |
Required parameters
--outdirstring (directory path)The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
Parameter explorer
104 parameters · 9 groupsEvery parameter from the pinned nextflow_schema.json. nfclaw checks explicit values before launch; complex rules use the pinned pipeline's runtime validation. Search, filter by group, and expand any parameter for its default, allowed values and constraints.
86 parameters · 18 hidden
Generic options4
Display the help message.
Display the full detailed help message.
Custom MultiQC yaml file containing HTML including a methods description.
Display hidden parameters in the help message (only works when --help or --help_full are provided).
Illumina De Novo Assembly options14
Specify which assembly algorithms you would like to use. Available options are 'spades', 'unicycler' and 'minia'.
Path to directory or tar.gz archive for pre-built BLAST database.
Minimum contig length to filter from BLAST results.
Minimum percentage of contig aligned to filter from BLAST results.
Skip ABACAS process for assembly contiguation.
Specify this parameter to skip all of the de novo assembly steps in the pipeline.
Skip generation of QUAST aggregated report for assemblies.
Skip Bandage image creation for assembly visualisation.
Skip blastn of assemblies relative to reference genome.
Set this parameter to false to add an X at the begining or end of the primer's fasta sequence to specify cutadapt that they are non-internal 5' or 3' adapters, respectively.
Skip assembly report generation by PlasmidID.
Path to profile HMMs specific for gene/organism to enhance SPAdes assembly.
Specify the SPAdes mode you would like to run (default: 'rnaviral').
Set this parameter to true when the primer's for cutadapt are 3' adapters. Default value is false, as default primers are 5' adapters.
Illumina Qc Read Trimming And Filtering options9
Remove host reads identified by Kraken2 before running aseembly steps in the pipeline.
Full path to Kraken2 database built from host genome.
Name for host genome as recognised by Kraken2 when using the 'kraken2 build' command.
Remove host reads identified by Kraken2 before running variant calling steps in the pipeline.
Save the trimmed FastQ files in the results directory.
Skip the amplicon trimming step with Cutadapt when using --protocol amplicon.
Skip the initial read trimming step peformed by fastp.
Skip FastQC.
Skip Kraken2 process for removing host classified reads.
Illumina Variant Calling options16
Specify which consensus calling algorithm you would like to use. Available options are 'bcftools' and 'ivar' (default: 'bcftools').
Filtered duplicates reads detected by Picard MarkDuplicates from alignments.
This option unsets the '-e' parameter in 'ivar trim' to discard reads without primers.
This option sets the '-x' parameter in 'ivar trim' so that reads that occur at the specified offset positions relative to primer positions will also be trimmed.
Minimum number of mapped reads below which samples are removed from further processing. Some downstream steps in the pipeline will fail if this threshold is too low.
Path to pangolin datadir.
Save mpileup files generated when calling variants with iVar variants or iVar consensus.
Save unaligned reads in FastQ format from Bowtie 2 to the results directory.
Skip genome consensus creation step and any downstream QC.
Skip creation of consensus base density plots.
Skip iVar primer trimming step. Not recommended for --protocol amplicon.
Skip picard MarkDuplicates step.
Skip Picard CollectMultipleMetrics steps.
Skip SnpEff and SnpSift annotation of variants.
Specify this parameter to skip all of the variant calling and mapping steps in the pipeline.
Specify which variant calling algorithm you would like to use. Available options are 'ivar' (default for '--protocol amplicon') and 'bcftools' (default for '--protocol metagenomic').
Input Output options6
Email address for completion summary.
Path to comma-separated file containing information about the samples you would like to analyse.
MultiQC report title. Printed as page header, used for filename if not otherwise specified.
The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
NGS platform used to sequence the samples.
Specifies the type of protocol used for sequencing.
Nanopore Illumina options16
Lineage defining barcodes, default is most recent from UShER database.
Specify the name where to store UShER database (default: 'freyja_db').
Specify a coverage depth minimum which excludes sites with coverage less than the specified value
Metadata of lineages that match barcode, default is most recent from UShER database.
Specify the number of bootstrap repeats to do.
Full path to Nextclade dataset required for 'nextclade run' command.
Name of Nextclade dataset to retrieve. A list of available datasets can be obtained using the 'nextclade dataset list' command.
Version tag of the dataset to download. A list of available datasets can be obtained using the 'nextclade dataset list' command.
Skip freyja deep SARS-CoV-2 variant analysis using a depth weighted approach.
Skip the bootstrapping module of Freyja
Skip genome-wide and amplicon coverage plot generation from mosdepth output.
Skip MultiQC.
Skip Nextclade clade assignment, mutation calling, and sequence quality checks for genome consensus sequence.
Skip Pangolin lineage analysis for genome consensus sequence.
Skip long table generation for reporting variants.
Skip generation of QUAST aggregated report for consensus sequences.
Nanopore options9
Clair3 model to use. If not provided the pipeline will attempt to determine the appropriate model based on the basecall_model_version_id field in the input FASTQ header (recommended)
Path containing clair3 models. Defaults to models packaged with conda installation
Primer scheme recognised by the artic minion command.
Path to a folder containing fastq files from the Nanopore run.
Minimum number of raw reads required per sample/barcode in order to be considered for the downstream processing steps.
Minimum number of reads required after the artic guppyplex process per sample/barcode in order to be considered for the downstream processing steps.
Sequencing summary file generated after Nanopore run completion.
Skip NanoPlot.
Skip pycoQC.
Reference Genome options12
Full path to additional annotation file in GTF or GFF format.
Path to directory or tar.gz archive for pre-built Bowtie2 index.
Path to FASTA genome file.
Name of viral reference genome.
Full path to GFF annotation file.
If the '--protocol amplicon' parameter is provided then iVar is used to trim primer sequences after read alignment and before variant calling.
If the '--protocol amplicon' parameter is provided then Cutadapt is used to trim primer sequences from FastQ files before de novo assembly.
Suffix used in name field of '--primer_bed' to indicate left primer position.
Suffix used in name field of '--primer_bed' to indicate right primer position.
The primer set to be used for the data analysis.
Version of the primer set e.g. '--primer_set artic --primer_set_version 3'.
If generated by the pipeline save reference genome related files to the results folder.
Outputs
Results land in --outdir; the files and directory layout depend on the selected workflow, parameters and publication settings. Run metadata is normally placed in <outdir>/pipeline_info/ (execution report, software versions), when those outputs are enabled. The pinned tree includes MultiQC support; a report is produced only when its workflow step runs. --skip-multiqc true disables that report. nfclaw run also writes <outdir>/provenance/ with the exact params file and the run log, <outdir>/provenance/logs/run.log — the whole launch, whose last line states the outcome (Nextflow's own log is <outdir>/.nextflow.log); unless --no-provenance it adds a run manifest (pinned version, commit and exact command), input/output SHA-256 checksums, and a replayable commands.sh.
The exact output files and directory layout for this release are documented upstream: github.com/nf-core/viralrecon/blob/3.0.0/docs/output.md
Check a run — in the foreground or the background — with nfclaw status <outdir>: success, still running, how it ended (with the error), or stopped without an outcome; exit 0 success, 3 running, 1 otherwise.
Chaining
Run viralrecon as one stage of a chain: nfclaw chain run starts each stage only after the one before it succeeded, and prepares its inputs from that stage's outputs. Every rule is checked against both pinned schemas.
Fed by
- fetchngs — fetchngs writes a viralrecon samplesheet (sample, fastq_1, fastq_2) with --nf-core-pipeline viralrecon. Runs whose ENA instrument_platform is not a short-read platform (the ones nf-core/mag accepts as short reads: ILLUMINA, BGISEQ, DNBSEQ, ELEMENT, ULTIMA, ION_TORRENT, LS454, …) are refused: viralrecon analyses short reads, and long-read, capillary or colour-space runs would be processed as if they were. Pass --platform illumina: viralrecon's nanopore mode does not read this samplesheet.
nfclaw chain edges viralrecon