PathoGenOmics-Lab · Paururo · Jul 25, 2026 · Jul 19, 2026 · Jul 19, 2026 · Jul 19, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,53 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - main
+      - 1.0.1
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Cache MkDocs build
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ github.sha }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      # Cairo and pango are what the social-card plugin renders through.
+      - name: Install image libraries for social cards
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            libcairo2-dev libfreetype6-dev libffi-dev \
+            libjpeg-dev libpng-dev libz-dev
+
+      - name: Install dependencies
+        run: pip install -r docs/requirements.txt
+
+      # CI is set by GitHub Actions, which is what switches social cards on.
+      - name: Build (strict)
+        run: mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,7 @@
 /target/
 **/target/
 *.DS_Store
+
+# MkDocs build output & cache
+/site/
+.cache/
diff --git a/CITATION.cff b/CITATION.cff
@@ -11,7 +11,7 @@ authors:
     given-names: Mireia
     orcid: "https://orcid.org/0000-0003-2078-1032"
     affiliation: "Institute for Integrative Systems Biology (I2SysBio), CSIC - University of Valencia"
-version: 1.0.0
+version: 1.0.1
 date-released: 2026-03-24
 license: AGPL-3.0-only
 repository-code: "https://github.com/PathoGenOmics-Lab/pathotypr"

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/algorithms/README.md b/docs/algorithms/README.md
@@ -1,6 +1,11 @@
-# Algorithm Documentation
+# Algorithm documentation
 
-This directory describes the algorithms and data structures behind each pathotypr module. For CLI usage and options, see the [command docs](../).
+**This section explains the algorithms and data structures behind each pathotypr module — the core ideas, not the command-line switches.**
+
+Each page below focuses on a single module: the concept it implements, the data structures it relies on, and how the pieces fit together end to end. For command-line usage and options, see the command guides in [See also](#see-also).
+
+!!! tip
+    The table is ordered roughly along the pathotypr pipeline — from turning k-mers into feature vectors, through training and prediction, to marker- and reference-based calling. Reading it top to bottom is a good first pass.
 
 | Module | Document | Core Idea |
 |---|---|---|
@@ -11,3 +16,12 @@ This directory describes the algorithms and data structures behind each pathotyp
 | Marker Genotyping | [marker-genotyping.md](marker-genotyping.md) | Diagnostic k-mers + Bloom filter for FASTQ scanning |
 | Reference Matching | [reference-matching.md](reference-matching.md) | K-mer containment scoring with streaming batches |
 | Assembly Classification | [assembly-classification.md](assembly-classification.md) | Marker calling on FASTA assemblies with GFF annotation |
+
+## See also
+
+- [train](../train.md)
+- [predict](../predict.md)
+- [classify](../classify.md)
+- [split-fastq](../split-fastq.md)
+- [match](../match.md)
+- [Home](../index.md)
diff --git a/docs/algorithms/assembly-classification.md b/docs/algorithms/assembly-classification.md
@@ -1,12 +1,15 @@
-# Assembly-Based Marker Classification
+# Assembly-based marker classification
 
-## Overview
+**A walkthrough of how `classify` matches known variant markers in assembled genomes: diagnostic k-mer generation, genome scanning, optional GFF annotation, lineage classification, and output.**
 
-The `classify` command calls known variant markers in assembled genomes (FASTA). Unlike the FASTQ `split-fastq` approach (which uses diagnostic k-mers on raw reads), this module works on full-length assemblies and supports SNPs, MNVs, **and indels**.
+The `classify` command calls known variant markers directly in assembled genomes (FASTA), supporting SNPs, MNVs, and indels.
+
+!!! info "Assemblies, not reads"
+    Unlike the FASTQ `split-fastq` path, which screens raw reads with diagnostic k-mers, this module scans full-length assemblies — so it can call indels and, with a GFF, report amino-acid changes.
 
 ## Architecture
 
-```
+```text
 Marker TSV + Reference FASTA ──→ Generate marker k-mers ──→ MarkerIndex
                                                                 │
 Query FASTA(s) ──→ Scan each genome for markers ──────────────→ MarkerMatch results
@@ -18,95 +21,105 @@ Query FASTA(s) ──→ Scan each genome for markers ────────
                                                           Summary TSV + Excel
 ```
 
-## Step 1: Marker K-mer Generation
+## Step 1: Marker k-mer generation
 
 For each marker in the TSV (position, REF, ALT):
 
 1. Extract flanking sequence from the reference genome (minimum 10 bp each side, configurable via `--min-flank-bases`)
 2. Build a diagnostic k-mer centered on the variant:
-   - For SNPs/MNVs: k-mer contains the variant at the center with equal flanks
-   - For indels: separate ref and alt k-mers with adjusted flank lengths to maintain k-mer size
+   - For SNPs/MNVs: the k-mer holds the ALT allele at the center with equal flanks
+   - For indels: the ALT allele is placed in the k-mer and the flank lengths are adjusted so the k-mer keeps its length of k
 
 3. Index k-mers for fast lookup:
-   - **Encoded index** (`MarkerIndex::Encoded`): For k ≤ 32, k-mers are 2-bit encoded into `u64` keys using needletail's `BitNuclKmer`. Lookup is a single hash table query.
-   - **Text index** (`MarkerIndex::Text`): For k > 32, k-mers are stored as strings. Fallback for unusually long k-mers.
+   - **Encoded index** (`MarkerIndex::Encoded`): For k ≤ 32, marker k-mers are 2-bit encoded into `u64` keys with a hand-rolled `encode_kmer_2bit` (needletail's `bit_kmers` is used to generate the *query* k-mers during genome scanning). Lookup is a single hash table query.
+   - **Text index** (`MarkerIndex::Text`): Used when a marker k-mer contains a non-ACGT base that cannot be 2-bit encoded; k-mers are stored as strings. (The code also falls back for k > 32, but `validate_kmer_size` caps k at 31, so that branch is unreachable in practice.)
 
-### Index Structure
+### Index structure
 
 ```rust
 enum MarkerIndex {
     Encoded(FxHashMap<u64, MarkerKmerEntry>),   // k ≤ 32: 2-bit encoded
-    Text(FxHashMap<String, MarkerKmerEntry>),    // k > 32: string keys
+    Text(FxHashMap<String, MarkerKmerEntry>),    // k > 32 or non-ACGT: string keys
 }
 ```
 
-Each entry stores the marker metadata: position, alleles, lineage, gene name, and flanking information needed to distinguish REF from ALT matches.
+Each entry stores the marker metadata: position, alleles, lineage, gene name, and the flank lengths needed to locate the variant bases within a matching k-mer.
 
-## Step 2: Genome Scanning
+## Step 2: Genome scanning
 
 For each query genome (parallelized across genomes with rayon):
 
-1. Read the genome sequence with needletail
-2. Extract all k-mers (canonical, same k as the marker k-mers)
-3. Look up each k-mer in the MarkerIndex
-4. For matches, determine whether the match supports REF or ALT allele by comparing the variant-spanning region
+1. Read every record (contig) of the genome with needletail
+2. Scan each contig on **both strands** — the forward sequence and its reverse complement — because contig orientation in a draft assembly is arbitrary
+3. Extract every k-mer of the same size k used for the marker k-mers and look it up in the `MarkerIndex`; a marker seen on several contigs, or on both strands, counts once
+4. Because only the ALT (variant) k-mer is indexed, any hit means the genome carries the variant allele; the entry's flank lengths then locate the exact variant-spanning bases
 
-### Match Result
+### Match result
 
 ```rust
 struct MarkerMatch {
-    position: usize,       // Genomic position (1-based)
+    kmer: String,            // the diagnostic (ALT) k-mer that matched
+    genome_position: usize,  // 0-based start of the match in the genome
+    ref_position: usize,     // 1-based marker position in the reference
+    lineage: String,
+    ref_allele_len: usize,
+    alt_allele_len: usize,
+    left_flank_len: usize,   // flank bases before the variant in the k-mer
     ref_allele: String,
     alt_allele: String,
-    found_allele: String,  // What was actually observed
-    lineage: String,
     gene: Option<String>,
     mutation: Option<String>,
 }
 ```
 
-## Step 3: Annotation (Optional)
+## Step 3: Annotation (optional)
 
 When GFF files are provided, each called variant is annotated:
 
-1. **GFF parsing**: Extracts CDS features with strand, phase, and locus tags using an interval tree (`rust_lapper::Lapper`) for O(log n) position lookups
+1. **GFF parsing**: Reads `CDS` features and stores each one's strand and gene name (taken from the `gene`, `locus_tag`, `Name`, or `ID` attribute) in an interval tree (`rust_lapper::Lapper`) for O(log n) position lookups
 2. **Amino acid translation**: Determines the codon position, extracts the codon from the reference and query, translates both to amino acids
-3. **Output**: `gene_name:REF_AA{position}ALT_AA` notation (e.g., `rpoB:S450L`)
+3. **Output**: for each affected codon the change is written as `REF_AA{position}ALT_AA(REF_codon>ALT_codon)` using three-letter amino-acid codes (e.g. `Ser450Leu(TCG>TTG)`); synonymous changes get a trailing ` syn`, an MNV spanning several codons joins its per-codon changes with `;`, and a length-changing (indel) variant is reported as `frameshift_pos{N}`. The gene name and first affected codon are written to the separate `Gene` and `AA_Pos` columns.
 
 Supports:
+
 - Forward and reverse strand genes
 - Multi-nucleotide variants spanning codon boundaries
 - Synonymous vs. non-synonymous classification
 
-## Step 4: Lineage Classification
+## Step 4: Lineage classification
 
 Two modes:
 
 ### Simple (default)
-- Each marker votes for its deepest lineage level
-- The lineage with the most ALT-supporting markers wins
-- Resolves nested lineages by walking the lineage hierarchy
+- Each matched marker increments the count of its full lineage path **and of every ancestor prefix** (`L4`, `L4;L4.9`, `L4;L4.9;L4.9.1`)
+- The path with the highest count wins, which is normally the shallowest level
+- Ties are broken deterministically by lineage name
 
 ### Nested (`--nested-classification`)
 - Hierarchical classification: first resolves major lineage, then sub-lineage
 - Only considers markers belonging to the parent lineage when resolving sub-lineages
-- More robust for datasets with uneven marker distribution across lineages
+
+!!! note "Nested vs. simple"
+    Nested classification is more robust for datasets with an uneven marker distribution across lineages.
 
 ## Step 5: Output
 
 ### Summary TSV (`{prefix}_summary.tsv`)
-Per-genome: sample name, predicted lineage, marker counts (REF/ALT/missing), percentage resolved.
+Per genome, three columns: `genome`, `lineage:count` (marker tallies at **every** hierarchical level — each ancestor path prefix is counted separately, space-separated), and `major_lineage` (the final call).
 
-### Detailed TSV (`{prefix}_details.tsv`)
-Per-marker-per-genome: position, alleles, found allele, lineage, gene, amino acid change.
+### Detailed TSV (`{prefix}.tsv`)
+One row per matched marker per genome, with columns: `genome`, `k-mer`, `k-merPOS`, `SNPgenome`, `SNPreference`, `REF`, `ALT`, `lineage`, `Gene`, `Gene_Start`, `Gene_End`, `AA_Pos`, `AA_Change`.
 
 ### Masked FASTA (optional, `--output-masked-fasta`)
-Query sequences with marker positions replaced by `N`. Useful for downstream phylogenetic analysis where marker sites should be excluded (e.g., removing sites under selection before building neutral phylogenies).
+Query sequences with marker positions replaced by `N`, written as `<input-stem>_masked.fasta`. Only produced for sequences in reference coordinates (records whose length matches the reference).
+
+!!! tip "Masked output"
+    Useful for downstream phylogenetic analysis where marker sites should be excluded — for example, removing sites under selection before building neutral phylogenies.
 
 ### Excel (optional, `--excel`)
-Same data as TSV with conditional formatting for confidence metrics.
+Same data as the TSV outputs, with a frozen header row and an autofilter. No conditional formatting is applied — classify has no confidence column.
 
-## Key Differences from FASTQ Mode (`split-fastq`)
+## Key differences from FASTQ mode (`split-fastq`)
 
 | Aspect | `classify` (FASTA) | `split-fastq` (FASTQ) |
 |---|---|---|
@@ -126,3 +139,9 @@ Same data as TSV with conditional formatting for confidence metrics.
 | Scan one genome | O(L × log M) where L = genome length | O(L + M) |
 | GFF annotation | O(V × log G) where V = variants, G = genes | O(G) |
 | Total (N genomes) | O(N × L × log M) / num_threads | O(L + M + G) |
+
+## See also
+
+- [classify](../classify.md)
+- [Marker format](../marker_format.md)
+- [Input formats](../input-formats.md)
diff --git a/docs/algorithms/feature-hashing.md b/docs/algorithms/feature-hashing.md
@@ -1,14 +1,18 @@
-# Feature Hashing (The Hashing Trick)
+# Feature hashing (the hashing trick)
+
+**pathotypr converts each genome into a fixed-length numerical vector by hashing its k-mers into a fixed set of buckets — no explicit vocabulary required.**
+
+This page explains why a vocabulary-based encoding does not scale, how the hashing trick replaces it, and how important buckets can be traced back to the k-mers and genomic coordinates they came from.
 
 ## Problem
 
 Representing genomic sequences as numerical vectors for machine learning requires counting k-mers — short subsequences of length *k*. A naive vocabulary-based approach needs to enumerate all possible k-mers (4^k = 4 billion for k=16) or build a dictionary from the data (dataset-dependent, expensive to store).
 
-## Solution: Feature Hashing
+## Solution: feature hashing
 
 pathotypr uses the **hashing trick** (Weinberger et al., 2009): each k-mer is hashed into a fixed set of buckets using a bitmask, bypassing the need for an explicit vocabulary.
 
-```
+```text
 Sequence: ACTGACTGCTA...
     ↓ extract k-mers (k=21)
     ACTGACTGCTA... → hash → bucket_idx = hash & 0xFFFFF
@@ -20,37 +24,47 @@ Sparse vector: [(bucket_42, 3.0), (bucket_1087, 1.0), ...]
 
 1. **K-mer extraction**: Uses [needletail](https://github.com/onecodex/needletail)'s `bit_kmers()` which encodes each k-mer as a 2-bit packed `u64`. This handles canonical k-mers (choosing the lexicographically smaller of forward and reverse complement) automatically.
 
-2. **Hashing**: The bucket index is simply `bitkmer.0 & mask` where `mask = num_buckets - 1`. Since needletail's 2-bit encoding already acts as a hash function (deterministic, uniform for biological sequences), no additional hash function is needed.
+2. **Hashing**: The bucket index is simply `bitkmer.0 & mask` where `mask = num_buckets - 1`.
 
-3. **Bucket count**: 2^20 = 1,048,576 buckets. The power-of-two constraint enables bitmask indexing (`& mask` instead of `% modulus`).
+3. **Bucket count**: 2^20 = 1,048,576 buckets.
 
 4. **Sparse representation**: Each sequence produces a `Vec<(usize, f32)>` — only non-zero buckets are stored, sorted by bucket index. This is critical for efficiency: a typical 4.4 Mb genome at k=21 produces ~4.4M k-mers but only ~800K–1M unique bucket entries.
 
-### Why This Works
+!!! info "Why no extra hash function is needed"
+    Since needletail's 2-bit encoding already acts as a hash function (deterministic, uniform for biological sequences), no additional hash function is needed. The power-of-two constraint enables bitmask indexing (`& mask` instead of `% modulus`).
+
+### Why this works
 
 - **Stateless**: The same hash function is applied at train and predict time. No vocabulary to store or update.
-- **Collisions are acceptable**: Multiple k-mers can map to the same bucket. With 1M buckets and ~4M k-mers per genome, collisions occur but empirically don't degrade classification accuracy because the Random Forest learns on aggregate count patterns, not individual k-mers.
 - **Fixed dimensionality**: All genomes map to the same 1M-dimensional space, regardless of genome size or k-mer diversity.
 
-### Reverse Mapping
+!!! note "Collisions are acceptable"
+    Multiple k-mers can map to the same bucket. With 1M buckets and ~4M k-mers per genome, collisions occur but empirically don't degrade classification accuracy because the Random Forest learns on aggregate count patterns, not individual k-mers.
+
+### Reverse mapping
 
 For feature importance analysis, pathotypr can reverse-map important buckets back to the original k-mers and their genomic coordinates:
 
 1. **`reverse_map_buckets()`**: Re-scans all training sequences, collects k-mers that hash into important buckets. Used for the importance TSV.
 2. **`reverse_map_with_coords()`**: Same but also records (sequence_index, 1-based position) for each hit. Used for the genomic coordinates TSV.
 
-### Complexity
+## Complexity
 
 | Operation | Time | Space |
 |---|---|---|
 | Vectorize one sequence | O(L) where L = sequence length | O(min(4^k, B)) where B = buckets |
 | Vectorize N sequences | O(N × L), parallelized with rayon | O(N × nnz) sparse |
 | Reverse map | O(N × L × \|targets\|) | O(\|targets\| × hits) |
 
-### Parameters
+## Parameters
 
 | Parameter | Value | Rationale |
 |---|---|---|
 | `num_buckets` | 2^20 = 1,048,576 | Balances collision rate vs. model size. Bucket count >> number of classes ensures discriminative power |
 | Default k (train) | 21 | Long enough for specificity in bacterial genomes (4^21 ≈ 4.4 × 10^12 >> genome size), short enough that SNPs create distinguishable k-mer patterns |
 | Default k (genotyping) | 31 | Longer k for higher specificity in marker-based genotyping where false positives are costly |
+
+## See also
+
+- [train](../train.md)
+- [predict](../predict.md)