# 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:

```bash
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`:

```bash
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`.