# 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
├── input_references/                 # segmented: per-segment reference FASTAs split
│   │                                 #   from a multi-record --reference (+ aligner index)
│   └── annotation/                   # split per-segment GFF3/BED (auto-split annotation)
├── 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
├── report.html                      # interactive HTML report (unless --no-generate-html-report)
└── benchmark.tsv                    # per-task runtime
```

### Key files

| File | Description |
|------|-------------|
| `assembly/assembly_stats_summary.csv` | Depth of coverage, breadth of coverage, mapped reads per sample/segment |
| `samples/{sample}/consensus.fasta` | Final consensus sequence |
| `samples/{sample}/table_cov_basewise.txt` | Per-base coverage table |
| `samples/{sample}/raw_mapped_reads.bam` | Reads mapped to the reference |
| `report.html` | Interactive self-contained report — see [Interactive HTML Report](report.md) |
| `benchmark.tsv` | 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 |
|------|-------------|
| `metagenomics/taxonomic_assignments/<track>/summaries/{family,genus,species}/<track>_<rank>_taxa_summary_<chain>.tsv` | **User-facing deliverable**: per-rank tables with higher-rank names propagated down (species gains `family`+`genus`; genus gains `family`). Most users want `species/`. |
| `metagenomics/taxonomic_assignments/<track>/summaries/full/<track>_taxa_summary.tsv` | Internal: raw per-taxon counts (base of the chain) |
| `metagenomics/taxonomic_assignments/<track>/summaries/full/<track>_taxa_summary_{RPM\|RPKM}[.nr][.ctgstats].bleed[.neg][.ictv].tsv` | Internal: the cumulative filter chain; the longest-named file is the fully-filtered combined summary that the per-rank tables are split from. `.nr` is contig-tracks only; `.ctgstats` (largest_contig_bp + largest_contig_ref_coverage_pct + largest_contig_median_depth) is on both contig tracks and requires `--viral-genomes`. `bleed_pass`/`neg_pass` columns flag cross-sample and negative-control status |
| `metagenomics/taxonomic_assignments/<track>/summaries/full/*.dropped.tsv` | Rows removed by a row-removing step (`.nr`, `.ictv`), for audit |
| `reference_targets.tsv` | Maps each sample × ref_key to the selected reference accession |
| `assembly/{ref_key}/consensus/final_consensus/{sample}.consensus.fasta` | Reference-guided consensus sequence per sample and ref_key |
| `samples/{sample}/` | Symlinks to every per-sample output for convenience |
| `benchmark.tsv` | Runtime and resource usage per task |