Interactive HTML Report

Every viralunity consensus run writes a single self-contained report.html to the output directory (alongside benchmark.tsv), giving a quick visual overview of a run without opening the raw CSV and coverage tables. The file embeds everything it needs — it opens offline in any browser, with no network access and no external dependencies.

The report covers the four consensus entry points (illumina / nanopore, segmented and unsegmented). It is not generated for viralunity meta.

The report is designed to stay legible from a single sample up to ~96 (≈96×8 per-segment rows for segmented viruses), so every panel scales instead of crowding.

What it shows

  • Summary tiles — samples analyzed, how many reach the pass-coverage threshold (default 90%, with the percentage of the run), how many fall below the warn threshold (default 70%; this tile turns red when any do), the median horizontal coverage, and the mean depth. On segmented runs a Global | Per-segment switch recomputes the tiles for one segment.

  • Assembly statistics — assembly/assembly_stats_summary.csv as a filterable table: search by sample (or segment), a “low coverage only” filter, a live row count, and a worst-coverage-first default sort so problems surface first. Each row carries a coloured status dot and an inline coverage bar. Segmented runs collapse to one row per sample that expands to its per-segment rows, with a chip row to focus a single segment.

  • Sequencing throughput — one horizontal stacked bar per sample: mapped reads, QC-passed-but-unmapped reads, and reads removed by QC, summing to the sample’s total. An Absolute/Percent toggle normalises each bar to 100% to compare QC loss across samples of different depth.

  • Coverage heatmap — samples on the y-axis, sorted worst-coverage-first. For amplicon (single-segment) runs the colour is sequencing depth along the genome (with a Natural/Log10 toggle); for segmented runs an “All segments” grid shows each segment’s horizontal coverage %, and a chip switches to the depth view for one segment. This replaces per-sample line overlays, which become unreadable past a handful of samples.

  • By sample — a searchable, worst-first list (each row with a status dot and coverage badge) beside the selected sample’s per-base coverage/depth plot, with 20× and 100× depth guides. Segmented samples default to an “All (concatenated)” view across segments, with a per-segment selector.

Optional gene (GFF3) and primer-scheme (BED) annotation tracks are drawn beneath the by-sample plot and the position-mode heatmap, with Genes / Primers toggles. The report finds them in order: files staged into <output>/annotation/ by the run, then the paths in the run config (scheme / gene_annotation — pass --config-file when regenerating an older run), and finally, for a missing gene track, a lookup on NCBI by the reference accession (on by default for viralunity report; use --no-fetch-annotation to stay fully offline). Fetched annotations are cached next to the run so later renders need no network.

Charts use a colourblind-safe palette and support a light/dark toggle (top right) and print/PDF. Per-base coverage is downsampled with min-pooling before plotting, so coverage dips are preserved rather than averaged away. The pass/warn coverage thresholds and the accent colour can be tuned with viralunity report --pass-threshold / --warn-threshold / --chart-color / --colorbar-thickness.

Regenerating the report

The report can be (re)built from an existing consensus output directory at any time, without rerunning the pipeline:

viralunity report --input <consensus-output-dir>
# writes <consensus-output-dir>/report.html

# or choose an explicit destination:
viralunity report --input <consensus-output-dir> --output my_report.html

This reads assembly/assembly_stats_summary.csv and the per-base coverage tables under assembly/[<segment>/]coverage_stats/ — the same inputs the pipeline rule uses — so the CLI and the automatic run-end report are identical.

Disabling the report

The report is generated by default. To skip it (for example, on very large runs), pass --no-generate-html-report:

viralunity consensus illumina ... --no-generate-html-report

This sets generate_html_report: false in the generated config; the Snakemake report.html target is then dropped from the run. You can still produce the report afterwards with viralunity report.