README.md

Metatropics result folders (detailed)

Paths below are relative to your pipeline --outdir. The pipeline also creates a Nextflow work/ directory; what follows is only what is published into outdir.

---

Overview

Group	Role
Basecalling/	Dorado basecalling and demultiplexing (optional).
Reads/	Read QC, trimming, human / optional host depletion.
Classification/	Virasign viral classification outputs and reports
Variant_calling/	Clair3 variant calls (VCFs) and reports.
Consensus/	Final consensus genomes produced by bcftools consensus.
Summary/	Final Metatropics report (Summary/metatropics/Metatropics_Summary_RVDB.html) listing all identified viruses, plus read-count summaries and pipeline provenance.

---

Basecalling/ (optional)

Path	Contents
Basecalling/basecalling	Intermediate FASTQ from Dorado before demultiplexing.
Basecalling/demultiplexing	Per-barcode FASTQ after demultiplexing (trims barcodes and adapters).

---

Reads/

This stage optionally performs rarefaction, then removes low-quality reads, short reads, and reads that match host background (e.g. human, pan). The host-depleted read set is fed to the rest of the pipeline.

Path	Contents
Reads/raw	Per-sample raw reads after naming / format fixes (*_fixed.fastq.gz).
Reads/rarefaction	Optional: Per-sample FASTQ after optional rarefaction subsampling.
Reads/nanoplot	Read-length and quality summaries (NanoPlot) on the raw reads.
Reads/fastplong	Trimmed, length-filtered reads (*.fastp.fastq.gz).
Reads/nohuman	Human-depleted reads only (*_human_depleted.fastq.gz). Mapped human reads are not written, to avoid storing identifiable human genetic data (privacy / GDPR — genetic data is special-category personal data under EU Regulation 2016/679).
Reads/nohost	Host-depleted reads (*_host_depleted.fastq.gz); mapped reads (*_host.fastq.gz).

---

Classification/

Host-depleted reads are mapped to the metagenomic database (e.g., Refseq, RVDB) and summarized so you can see which organisms (taxa) are present in each sample.

Path	Contents
Classification/virasign/	Virasign per-sample viral classification results.

Output	Meaning
*_unfiltered_all_references.json	All candidate viral hits.
*_final_selected_references.json	Final confident viral hits.
*.fasta	Best reference sequence(s) selected by Virasign.
mreads.fastq.gz	Reads mapped to the reference(s) for each virus.
*.bam	Read alignments against the best reference(s).
*.bai	BAM index for the alignments.
*coverage*.pdf	Coverage plots per virus/reference.

For more Virasign details, see DaanJansen94/virasign.

---

Variant_calling/

For each candidate virus, Clair3 performs haploid variant calling on the Virasign-produced BAM (reads aligned to the selected viral reference) and emits a VCF describing differences from that reference. Metatropics then applies a uniform post-processing step that re-counts allele support from the BAM (with mapping/base-quality filters), labels variants as major/minor, and produces a VCF + HTML report.

Path	Contents
Variant_calling/clair3	Variant calls and report (*.variants.filtered.vcf, *.variants.unfiltered.vcf, *.variants.html).

Example

---

Consensus/

Consensus building starts from the Virasign-selected reference FASTA and then applies only the variants called by Clair3 to produce the final consensus with bcftools consensus. By default, only variants labelled major and with VAF ≥ --agreement are applied; everything else remains as the reference base.

Path	Contents
Consensus/bcftools	Final consensus FASTA produced by bcftools consensus.

---

Summary/

Metatropics reports, run-wide summaries, and provenance.

Path	Contents
Summary/readcount	Read distribution (read_distribution.html).
Summary/metatropics	Final Metatropics HTML report (Metatropics_Summary_*.html).
Summary/pipeline_info	Nextflow trace/reports and software versions (software_versions.yml).

Open the final HTML report at Summary/metatropics/Metatropics_Summary_RVDB.html for fast interpretation of whether a virus is likely truly present.

Interpretation

As a rough guide, hits that match the patterns below are more in favour of true positives.

Indicator	Typical / rule of thumb	Notes
Mapped reads	≥100–1000+	More reads → stronger support, but do not interpret mapped reads alone.
Coverage depth	~1–10×	Higher better; when ~1-5×, rely more on consensus breadth + NOGR.
Consensus breadth	≥20–30%	≥20–30% is often already a decent hit; below that, lean more on NOGR (and the coverage plots) to interpret.
NOGR (#/bases)	≥3 regions if consensus breadth <20%	If consensus breadth is <20% and NOGR is 1–2, treat as high contamination/carryover risk (confirm with Z-score and the coverage plot). See NOGR.md.
Z-score	~2–3+ vs controls	Helps flag negative-control-like background / carryover. See Z_SCORE.md.

Note: Coverage breadth (%) is the fraction of reference positions covered by ≥1 read, while Consensus breadth (%) is the fraction of positions with a called (non-N) consensus base after consensus building. Consensus breadth is therefore the higher-stringency “HQ breadth” and is the better breadth number to use for interpretation. See ../submission/all_options.md.

Example