The viralmetagenome template follows an nf-core/viralmetagenome run from metagenomic reads to viral consensus genomes and their variants:
- Overview: the run in four key figures, live findings and a link to every tab
MultiQC: reads, trimming, host removal, mapping, duplicates and coverage from the MultiQC report- Samples: how many reads of each sample reach assembly
- Contigs: the de novo contigs, their taxonomic call and their clusters
- Consensus: each genome's identity to its reference, ambiguous bases and CheckV tier
- Mapping: depth and breadth of coverage per genome
- Variants: the iVar calls on a genome view, by allele frequency and depth
The persistent Sample filters sit in the collapsed left panel, and the Sample
sheet is pinned, collapsed, to the bottom of every child tab.
The MultiQC report must be regenerated
viralmetagenome 1.2.0 ships MultiQC 1.27, which writes no parquet, and Depictio
reads only multiqc.parquet (MultiQC 1.31 and later). Rebuild the report from
the run's own tool outputs before ingesting, or the MultiQC tab stays empty:
Quick start¶
depictio ingest /path/to/viralmetagenome_results \
--template nf-core/viralmetagenome/latest \
--var METADATA_FILE=/path/to/metadata.tsv
METADATA_FILE is optional: the table given to --metadata, which the pipeline
merges into its samples overview but does not publish. Its sample id is in a
column named sample (or the first column) and every other column is a factor;
the first factor becomes the group (GROUP_COL). Without it the samples carry one
constant group, and --var GROUP_COL=<column> still finds a factor of the
overview.
depictio config nextflow --install # once per machine
nextflow run nf-core/viralmetagenome -r 1.2.0 -profile docker --outdir results
No depictio ingest, and no template named: the pipeline ingests its own
output directory when it finishes and resolves this template from its own
manifest. The MultiQC tab stays empty until the report is regenerated as above. See Nextflow trigger.
Reference¶
The template reads the pipeline's overview tables (samples, contigs, refinement steps and constraint mappings), the contig classes and clusters, CheckV, the raw iVar tables, the mosdepth depth tables and the regenerated MultiQC report. A run takes the de novo route, the constraint route or both, and every collection a route does not write is optional: the tiles that read it are pruned.
Self-adapting layout
The dashboard adapts to whatever the run actually produced: components bound to pruned or unparsed data collections are hidden, tabs left with no real visualizations are dropped entirely, and the remaining components are re-packed so there are no empty rows.
Template variables¶
Variables you provide when running the template: DATA_ROOT is the results directory given to depictio ingest, the others are set with --var NAME=value:
| Variable | Required | Description |
|---|---|---|
DATA_ROOT |
✓ | Root directory of one viralmetagenome run (overview-tables/, preprocessing/, assembly/, consensus/, variants/, multiqc/, pipeline_info/). |
METADATA_FILE |
— | Optional sample metadata table (TSV), the one given to --metadata: sample id in a column named sample (or in the first column), one column per factor. Enables the design filters and grouping. |
METADATA_ID_COL |
— | Metadata sample-id column. Auto-detected as the first column; defaults to 'sample'. |
GROUP_COL |
— | Column the dashboards group and filter samples by. Auto-detected as the first factor column of METADATA_FILE; without it, any factor of the samples overview's metadata block. |
Auto-detected (set from the run's metadata / params.json; the route flags drive Conditional routes below): GROUP_COL_DISPLAY
Data collections¶
16 data collections — 5 required 11 optional · 12 direct 4 derived.
Origin tells you whether a collection is real pipeline data or a reshape of it: direct = a pipeline output (scanned, or a recipe that reads raw files); derived = a recipe that reshapes one or more direct collections into the layout a visualization needs (no new measurement). Reads shows what produces it: a recipe .py transform, or a raw file scanned off disk. (A direct collection can still have a recipe — one that merely parses/cleans the raw file; derived means the recipe reshapes another collection.)
| Tag | Origin | Type | Reads | Status |
|---|---|---|---|---|
metadata |
direct | Table | file |
optional |
multiqc_data |
direct |  MultiQC |
file |
required |
vmg_samples_overview |
direct | Table | recipe |
required |
samples |
derived | Table | recipe |
required |
read_funnel |
derived | Table | recipe |
required |
vmg_contig_classes |
direct | Table | recipe |
optional |
vmg_clusters |
direct | Table | recipe |
optional |
vmg_contigs |
derived | Table | recipe |
optional |
vmg_contigs_overview |
direct | Table | recipe |
optional |
vmg_contig_iterations |
direct | Table | recipe |
optional |
vmg_mapping_overview |
direct | Table | recipe |
optional |
checkv_quality |
direct | Table | recipe |
optional |
genomes |
derived | Table | recipe |
required |
ivar_variants |
direct | Table | recipe |
optional |
coverage_bins |
direct | Table | recipe |
optional |
coverage_cumulative |
direct | Table | recipe |
optional |
Conditional routes¶
Rows are data collections; columns are the variables you set or params.json flags auto-detected from the run. Each filled cell is the effect of setting that variable; an empty cell means that variable leaves the collection unchanged. (15 collections are unaffected by any variable — present on every run.)
+ included− removed⇄ repointed
| Data collection | METADATA_FILE |
|---|---|
metadata |
+ |
Cross-DC links¶
16 links — selecting a value in the source collection filters the target. The join column is shown after the source.
| Source · column | Target | Filters | |
|---|---|---|---|
samples · sample |
→ | multiqc_data |
Filter the MultiQC panels by the samples picked in the left panel |
samples · sample |
→ | read_funnel |
Filter the read funnel by the selected samples |
samples · sample |
→ | vmg_contigs |
Filter the de novo contigs by the selected samples |
samples · sample |
→ | vmg_clusters |
Filter the contig clusters by the selected samples |
samples · sample |
→ | genomes |
Filter the consensus genomes by the selected samples |
samples · sample |
→ | vmg_contig_iterations |
Filter the refinement steps by the selected samples |
samples · sample |
→ | checkv_quality |
Filter the CheckV calls by the selected samples |
samples · sample |
→ | ivar_variants |
Filter the variant calls by the selected samples |
samples · sample |
→ | coverage_bins |
Filter the depth profiles by the selected samples |
samples · sample |
→ | coverage_cumulative |
Filter the cumulative coverage curves by the selected samples |
genomes · genome_id |
→ | ivar_variants |
Filter the variant calls by the selected genomes |
genomes · genome_id |
→ | coverage_bins |
Filter the depth profiles by the selected genomes |
genomes · genome_id |
→ | coverage_cumulative |
Filter the cumulative coverage curves by the selected genomes |
genomes · genome_id |
→ | vmg_contig_iterations |
Filter the refinement steps by the selected genomes |
genomes · sample |
→ | samples |
Narrow the sample hub to the samples of the genomes selected on the genome tiles |
vmg_contigs · sample |
→ | samples |
Narrow the sample hub to the samples of the contigs selected on the contig tiles |
Recipes¶
Each recipe reshapes raw pipeline output into a tidy table. The name links to its source; Output lists the validated OUTPUT_SCHEMA columns.
| Recipe | Transforms | Output |
|---|---|---|
checkv/quality_summary.py |
One row per viral sequence from CheckV's quality_summary.tsv. |
sample, checkv_run, contig_id, contig_length, provirus, proviral_length, gene_count, viral_genes, host_genes, checkv_quality, miuvig_quality, completeness, completeness_method, contamination, kmer_freq, warnings |
ivar/variants_tsv.py |
One row per variant from the raw iVar variants table, one file per mapping. |
sample, reference, route, genome_id, chrom, pos, ref, alt, variant_type, variant_key, ref_dp, alt_dp, total_dp, af, frequency_class, alt_qual, pval, filter, gff_feature, aa_change |
mosdepth/cumulative_coverage.py |
Cumulative coverage curve per mapping, from mosdepth's global.dist.txt. |
sample, reference, genome_id, depth, bases_pct |
mosdepth/per_base_bins.py |
Read depth along each reference, binned, from mosdepth's per-base.bed.gz. |
sample, reference, genome_id, chrom, start, end, position, mean_depth, min_depth |
nf-core/viralmetagenome/genomes.py |
Consensus genome hub for nf-core/viralmetagenome: one row per final consensus. | genome_id, sample, reference, route, step, virus, consensus_length, n_bases, n_pct, annotation_identity_pct, annotation_aligned_pct, annotation_mismatches, blast_identity_pct, blast_aligned_bp, blast_bitscore, checkv_contamination, checkv_genes, checkv_viral_genes, checkv_host_genes, mapped_reads, mapped_pct, properly_paired_pct, error_rate, insert_size, dup_read_pairs, dup_pct, dedup_mapped_reads, mean_depth, median_depth, max_depth, cov_1x_pct, cov_10x_pct, cov_50x_pct, cov_100x_pct, snps, indels, variant_records, transitions, transversions, ts_tv, mash_identity, cluster_members, annotation_name, annotation_acronym, annotation_level, annotation_taxid, annotation_segment, annotation_host, annotation_subject, blast_hit, checkv_quality, miuvig_quality, checkv_warnings, mash_reference, mash_shared_hashes, cluster_centroid, constraint_species, constraint_segment, constraint_definition, blast_query_cover_pct, checkv_completeness, completeness_method |
nf-core/viralmetagenome/read_funnel.py |
Read pairs per sample at each preprocessing stage, long, for the read funnel figure. | sample, stage, stage_order, read_pairs, pct_of_raw |
nf-core/viralmetagenome/samples.py |
Sample hub for nf-core/viralmetagenome: one row per sample, its reads and its assembly. | sample, raw_read_pairs, raw_gc_pct, raw_dup_pct, trimmed_reads, q30_pct, fastp_dup_pct, adapter_pct, trimmed_read_pairs, host_pct, host_filtered_read_pairs, retained_pct, assembly_length, assembly_n50, clusters, removed_clusters, mean_cluster_size, singletons, denovo_consensus |
viralmetagenome/clusters.py |
One row per contig cluster, from the viralmetagenome clustering step. | sample, cluster, taxid, centroid, cluster_type, members, member_bp, read_depth_pct, member_ids, status |
viralmetagenome/contig_classes.py |
Taxonomic call of every de novo contig before clustering. | sample, contig, classification, taxid |
viralmetagenome/contig_iterations.py |
One row per de novo consensus and refinement step, from the viralmetagenome contigs overview with iterations. | genome_id, sample, reference, route, step, virus, consensus_length, n_bases, n_pct, annotation_identity_pct, annotation_aligned_pct, annotation_mismatches, blast_identity_pct, blast_aligned_bp, blast_bitscore, checkv_contamination, checkv_genes, checkv_viral_genes, checkv_host_genes, mapped_reads, mapped_pct, properly_paired_pct, error_rate, insert_size, dup_read_pairs, dup_pct, dedup_mapped_reads, mean_depth, median_depth, max_depth, cov_1x_pct, cov_10x_pct, cov_50x_pct, cov_100x_pct, snps, indels, variant_records, transitions, transversions, ts_tv, mash_identity, cluster_members, annotation_name, annotation_acronym, annotation_level, annotation_taxid, annotation_segment, annotation_host, annotation_subject, blast_hit, checkv_quality, miuvig_quality, checkv_warnings, mash_reference, mash_shared_hashes, cluster_centroid, constraint_species, constraint_segment, constraint_definition, blast_query_cover_pct, step_order |
viralmetagenome/contigs.py |
One row per de novo contig: its length, its reads, its taxonomic call and its cluster. | sample, assembler, contig, length_bp, length_class, mapped_reads, read_share_pct, reads_per_kb, classification, taxid, cluster, cluster_role |
viralmetagenome/contigs_overview.py |
One row per final de novo consensus genome, from the viralmetagenome contigs overview. | genome_id, sample, reference, route, step, virus, consensus_length, n_bases, n_pct, annotation_identity_pct, annotation_aligned_pct, annotation_mismatches, blast_identity_pct, blast_aligned_bp, blast_bitscore, checkv_contamination, checkv_genes, checkv_viral_genes, checkv_host_genes, mapped_reads, mapped_pct, properly_paired_pct, error_rate, insert_size, dup_read_pairs, dup_pct, dedup_mapped_reads, mean_depth, median_depth, max_depth, cov_1x_pct, cov_10x_pct, cov_50x_pct, cov_100x_pct, snps, indels, variant_records, transitions, transversions, ts_tv, mash_identity, cluster_members, annotation_name, annotation_acronym, annotation_level, annotation_taxid, annotation_segment, annotation_host, annotation_subject, blast_hit, checkv_quality, miuvig_quality, checkv_warnings, mash_reference, mash_shared_hashes, cluster_centroid, constraint_species, constraint_segment, constraint_definition, blast_query_cover_pct |
viralmetagenome/mapping_overview.py |
One row per constraint mapping, from the viralmetagenome mapping overview. | genome_id, sample, reference, route, step, virus, consensus_length, n_bases, n_pct, annotation_identity_pct, annotation_aligned_pct, annotation_mismatches, blast_identity_pct, blast_aligned_bp, blast_bitscore, checkv_contamination, checkv_genes, checkv_viral_genes, checkv_host_genes, mapped_reads, mapped_pct, properly_paired_pct, error_rate, insert_size, dup_read_pairs, dup_pct, dedup_mapped_reads, mean_depth, median_depth, max_depth, cov_1x_pct, cov_10x_pct, cov_50x_pct, cov_100x_pct, snps, indels, variant_records, transitions, transversions, ts_tv, mash_identity, cluster_members, annotation_name, annotation_acronym, annotation_level, annotation_taxid, annotation_segment, annotation_host, annotation_subject, blast_hit, checkv_quality, miuvig_quality, checkv_warnings, mash_reference, mash_shared_hashes, cluster_centroid, constraint_species, constraint_segment, constraint_definition, blast_query_cover_pct |
viralmetagenome/samples_overview.py |
One row per sample from the viralmetagenome samples overview table. | sample, raw_read_pairs, raw_gc_pct, raw_dup_pct, trimmed_reads, q30_pct, fastp_dup_pct, adapter_pct, trimmed_read_pairs, host_pct, host_filtered_read_pairs, retained_pct, assembly_length, assembly_n50, clusters, removed_clusters, mean_cluster_size, singletons, denovo_consensus |
Dashboard tabs¶
One dashboard: the Overview, then six child tabs in three groups, read as a funnel from the reads to the variants. Each tab below carries the same icon and colour the dashboard gives it.
| Group | Tabs |
|---|---|
| Data & QC | MultiQC, Samples |
| Assembly | Contigs, Consensus, Mapping |
| Variants | Variants |
Viral genomes from metagenomic reads, to consensus and variants.
A hero, About and The run cards and a six-step pipeline flow. Four key figures (samples, clean read pairs, consensus genomes, breadth at 10X) have their own group and sample filter bar. Four findings (contigs, consensus, mapping, variants) each link to their tab.
Data & QC · What does the MultiQC report say about reads and mappings?
FastQC reads per run, fastp's kept and removed reads, base quality and the Kraken2 host taxa. Then, one row per mapping, samtools percent mapped, Picard duplicates, mosdepth cumulative coverage and the bcftools substitution types.
Data & QC · How many reads of each sample reach assembly?
Four cards: the read funnel, the host share, Q30 bases against Illumina's 80 % floor and FastQC's duplicate share. Then the read pairs of every sample at each stage, and a sample plane of raw read pairs against the share retained, coloured by the group. The per-stage table is collapsed.
Assembly · Which contigs did the assembly build, and what are they?
Cards for the contigs by taxonomic call, the assembled bases by length band, the reads on contigs by cluster role and the clusters refined or filtered out. Then every contig by length and the reads that map back to it, and the read depth share of the clusters per sample. The tab exists only on the de novo route.
Assembly · How close to a reference and how complete is each genome?
Cards for the genomes by route, the ambiguous bases (5 % N passes, 20 % warns), the identity to the closest reference and the CheckV tier. Then every genome by ambiguous bases and identity, coloured by route, with the record of the picked one, and the ambiguous bases of each de novo consensus along its refinement.
Assembly · How deep and how evenly do the reads cover each genome?
Cards for the reads mapped, the mean depth, the breadth at 10X (90 % passes, 50 % warns) and the duplicate pairs. Then the depth along each genome in bins (log), and the depth against the breadth per genome beside the cumulative coverage curves.
Variants · Which variants does each genome carry, and how fixed are they?
Cards for the passing calls by allele frequency band (fixed at 0.9 or more, major from 0.5, minor below), the minor calls kept or filtered, the call depth and the genomes carrying a passing call. Then every call on a genome view, one lane per genome, and the allele frequency against the depth.
Tables are collapsed at the bottom of their tab.
Running the pipeline¶
Depictio reads the output of nf-core/viralmetagenome, it does not run the pipeline. Run the pipeline first, with a metadata table if you want a design group:
nextflow run nf-core/viralmetagenome -r 1.2.0 \
--input samplesheet.csv --metadata metadata.tsv \
-profile docker --outdir results
Then rebuild the MultiQC report and point Depictio at the results:
python -m depictio.dev_scripts.multiqc_reprocess --src results/ --dest results/ --exclude '*_mqc.tsv'
depictio ingest results/ --template nf-core/viralmetagenome/latest \
--var METADATA_FILE=metadata.tsv
See nf-co.re/viralmetagenome/usage for full pipeline documentation.
Required data structure¶
Point depictio ingest at the directory holding the pipeline output. Depictio scans
recursively and matches on file name. Every published file name carries the run's
--global_prefix, so the template matches on the suffix and reads a run whatever
its prefix.
<DATA_ROOT>/
├── overview-tables/
│ └── *{samples,contigs,mapping}_overview.tsv # the pipeline's own merge of its MultiQC sections
├── assembly/
│ ├── assemblers/<assembler>/idxstats/*.idxstats
│ └── polishing/ # contig classes, clusters
├── consensus/quality_control/checkv/<sample>/<genome>/quality_summary.tsv
├── variants/
│ ├── ivar/<sample>/*.tsv
│ └── mapping-info/metrics/mosdepth/<sample>/ # per-base depth, cumulative coverage
├── multiqc/multiqc_data/multiqc.parquet # written by multiqc_reprocess
└── pipeline_info/software_versions.yml
Validation runs¶
The template was validated against the AWS megatest of the 1.2.0 release,
s3://nf-core-awsmegatests/viralmetagenome/results-74064a43f4b00c163c22bcfc9cf1d84a2a69e988/:
four paired-end metagenomic libraries of one virus, assembled with MEGAHIT,
clustered with CD-HIT-EST, refined for one iteration and called with iVar, then
mapped against a constraint sheet of three references. The metadata table is not
part of the published run: it is vendored with the template under input/, with
a specimen column as the group. CheckV ran on its minimal test database, so
every consensus reads Not-determined. megatest.yaml lists the subset the
template needs (about 20 MB):
DEST=/tmp/viralmetagenome_test
bash depictio/projects/nf-core/viralmetagenome/1.2.0/download_test_data.sh "$DEST"
python -m depictio.dev_scripts.multiqc_reprocess --src "$DEST" --dest "$DEST" --exclude '*_mqc.tsv'
depictio ingest "$DEST" --template nf-core/viralmetagenome/latest \
--var METADATA_FILE="$DEST/input/metadata.tsv" --var GROUP_COL=specimen
Do not pass --project when ingesting: the dashboard is attached to the
project by name, so renaming it breaks a later depictio dashboard import.
Re-ingesting accumulates dashboards, so delete the project before repeating a run.
Additional resources¶
- nf-co.re/viralmetagenome: official pipeline documentation
- nf-co.re/viralmetagenome/1.2.0/results: AWS test results
- Template System Reference: YAML format, variables, conditionals
- Recipes: how to read, test, and write recipes
Authorship¶
weber8thomas
Reviewing a template on your own data, or taking over a role here, is a contribution in itself: the contributing guide says what each one involves.