Output Layout
Consensus pipeline (viralunity consensus)
After a successful run, the output directory is organised as follows:
{output}/
├── assembly/
│ ├── assembly_stats_summary.csv # per-sample QC metrics
│ ├── consensus/ # non-segmented
│ │ └── final_consensus/
│ │ └── samples_alignment.fasta
│ └── {segment}/ # segmented (one per segment)
│ └── consensus/
│ └── final_consensus/
│ └── samples_alignment.fasta
├── reference/
│ └── reference.sanitized.fasta # reference with sanitised headers (nanopore)
├── samples/
│ └── {sample_name}/
│ ├── consensus.fasta
│ ├── consensus.vcf.gz
│ ├── raw.vcf.gz
│ ├── table_cov_basewise.txt
│ ├── raw_mapped_reads.bam
│ └── trimmed_mapped_reads.bam
└── benchmark.tsv # per-task runtime
Key files
File |
Description |
|---|---|
|
Depth of coverage, breadth of coverage, mapped reads per sample/segment |
|
Final consensus sequence |
|
Per-base coverage table |
|
Reads mapped to the reference |
|
Runtime and resource usage per task |
Metagenomics pipeline (viralunity meta)
{output}/{run_name}/
├── qc/ # Illumina only
│ ├── trim.{sample}_fastp.html
│ ├── trim.{sample}_fastp.json
│ └── reports/multiqc_report.html
├── host_filtered/ # when host removal is enabled
│ ├── {sample}.R1.filtered.fastq.gz
│ ├── {sample}.R2.filtered.fastq.gz
│ └── {sample}.merged.fastq.gz
├── metagenomics/
│ └── taxonomic_assignments/
│ └── <track>/ # track = kraken2_reads | kraken2_contigs | diamond_reads | diamond_contigs
│ ├── results/{sample}.* # per-sample reports / krona / diamond hits
│ ├── reports/{sample}.*.krona.html # per-sample Krona plots
│ └── summaries/ # all taxa-summary tables live here
│ ├── family/ <track>_family_taxa_summary_<chain>.tsv # ── user-facing deliverable ──
│ ├── genus/ <track>_genus_taxa_summary_<chain>.tsv (genus table gains a family column)
│ ├── species/ <track>_species_taxa_summary_<chain>.tsv (species table gains family + genus columns)
│ └── full/ # internal: the combined cumulative filter chain (all ranks)
│ ├── <track>_taxa_summary.tsv # raw counts
│ ├── <track>_taxa_summary_{RPM|RPKM}.tsv # + RPM (RPKM with --viral-genomes)
│ └── <track>_taxa_summary_{RPM|RPKM}[.nr][.ctgstats].bleed[.neg][.ictv].tsv # see below
├── denovo_assembly/ # when --run-denovo-assembly
│ ├── megahit/{sample}/final.contigs.fa
│ └── viral_contigs/{sample}.viral_contigs.fa
├── assembly/ # when --run-reference-assembly
│ └── {ref_key}/ # unique key: {family}_{accession}
│ ├── references/{sample}.fasta # extracted reference genome
│ ├── mapped_reads/
│ │ ├── raw/{sample}.sorted.bam
│ │ └── trimmed/{sample}.sorted.bam
│ ├── isnvs/{sample}.isnvs.vcf.gz # Illumina only, when --run-isnv
│ └── consensus/final_consensus/
│ ├── {sample}.consensus.fasta
│ └── {sample}.consensus.vcf.gz
├── reference_targets.tsv # checkpoint: selected references per sample/ref_key
├── reference_assembly_done.txt # sentinel: reference assembly completed
├── samples/ # per-sample symlinks for convenience
│ └── {sample}/
│ ├── fastp.html
│ ├── host_filtered_R1.fastq.gz
│ ├── host_filtered_R2.fastq.gz
│ ├── kraken2_reads.report.txt
│ ├── kraken2_reads.krona.html
│ ├── diamond_reads.tsv
│ ├── denovo_contigs.fasta
│ ├── kraken2_contigs.report.txt
│ ├── diamond_contigs_supported.tsv
│ └── viral_mapped_reads.bam
└── benchmark.tsv # runtime and resources per task
Per-rank output layout
The browsable deliverable for each track is a set of per-rank tables under
<track>/summaries/family/, <track>/summaries/genus/, and <track>/summaries/species/. Higher-rank names are
propagated down as columns so each table is self-contained: the species table gains
family and genus columns, and the genus table gains a family column. Most users
want the species/ table.
The cumulative filter chain that produces these is computed on one combined per-track
table kept internally under <track>/summaries/full/ — useful for auditing the step-by-step
filtering, but not the primary output. (This is a breaking change from ≤1.3.1, where
the combined chain files sat directly under <track>/.)
The taxa-summary filename chain (internal, under <track>/summaries/full/)
Each track computes its taxa summary through one cumulative chain: every enabled step appends exactly one suffix, so the fully-filtered table is always the file with the longest name, and disabled options never appear.
<track>_taxa_summary.tsv raw counts
└─ _RPM.tsv + reads-per-million
└─ _RPKM.tsv + RPKM (only with --viral-genomes)
└─ .nr NR validation (contig tracks only; --run-nr-validation)
└─ .ctgstats largest-contig size + median depth (contig tracks, with --viral-genomes)
└─ .bleed max bleed filter (always; adds bleed_pass)
└─ .neg negative-control enrichment (with negative controls; adds neg_pass)
└─ .ictv ICTV vertebrate-host filter (--run-ictv-host-filter)
The active metric token is _RPKM when --viral-genomes is set, else _RPM, and it
is carried consistently through the whole chain. Row-removing steps (.nr, .ictv)
also write a *.dropped.tsv audit sidecar; .bleed/.neg/.ctgstats add columns rather
than removing rows. Example fully-filtered names: contigs
diamond_contigs_taxa_summary_RPKM.nr.ctgstats.bleed.neg.ictv.tsv; reads
kraken2_reads_taxa_summary_RPKM.bleed.neg.ictv.tsv.
Key files
File |
Description |
|---|---|
|
User-facing deliverable: per-rank tables with higher-rank names propagated down (species gains |
|
Internal: raw per-taxon counts (base of the chain) |
|
Internal: the cumulative filter chain; the longest-named file is the fully-filtered combined summary that the per-rank tables are split from. |
|
Rows removed by a row-removing step ( |
|
Maps each sample × ref_key to the selected reference accession |
|
Reference-guided consensus sequence per sample and ref_key |
|
Symlinks to every per-sample output for convenience |
|
Runtime and resource usage per task |