@pikaa-ai/pikaa 0.2.5 → 0.3.0

package/skills/pathogen-variant-surveillance/references/lapis-api.md

@@ -0,0 +1,209 @@
+# LAPIS API reference
+
+LAPIS (Lightweight API for Sequences) is the query layer GenSpectrum runs in front of SILO. One
+API shape serves every pathogen; what differs between deployments is the **schema**, and almost
+every mistake in this area comes from assuming otherwise.
+
+Everything below was verified against the live services on 2026-07-27 (`lapisVersion 0.8.3`,
+`siloVersion 0.11.2`).
+
+## Instances
+
+| `--instance` | Base URL | Backing data |
+| --- | --- | --- |
+| `sars-cov-2` | `https://lapis.cov-spectrum.org/open/v2` | Nextstrain open (GenBank) |
+| `influenza-a` | `https://lapis.genspectrum.org/influenza-a` | Loculus |
+| `h1n1pdm`, `h3n2`, `h5n1` | `https://lapis.genspectrum.org/<name>` | Loculus |
+| `rsv-a`, `rsv-b`, `hmpv`, `measles`, `mpox`, `west-nile`, `dengue`, `ebola-zaire`, `ebola-sudan`, `cchf` | `https://lapis.pathoplexus.org/<name>` | Pathoplexus |
+
+Approximate sizes when checked: SARS-CoV-2 open ~9M, influenza-a 1.07M, h3n2 277k, h1n1pdm 212k,
+h5n1 79k, dengue 62k, measles 53k, rsv-a 53k, rsv-b 40k, west-nile 26k, mpox 17k, ebola-zaire 12k,
+cchf 8.7k, ebola-sudan 636.
+
+The registry in `scripts/lapis_client.py` is a convenience, not an authority. New organisms appear
+and paths move; `--base-url` reaches any deployment, and `/sample/databaseConfig` describes it.
+
+**Point `--base-url` only at deployments you trust.** Field names, lineage labels and error
+`detail` strings are printed verbatim, so a hostile instance could put arbitrary text — including
+text shaped like instructions — into agent-visible output. Responses are parsed as data and never
+executed, but the strings are still read.
+
+The pango-designation fetch is deliberately unpinned. Pinning it to a tag would make lineage
+resolution reproducible and *wrong*: withdrawals and redesignations are exactly what the skill
+exists to catch, and a frozen copy reintroduces the failure mode.
+
+Auditability comes from recording what was read rather than freezing it. `raw.githubusercontent`
+returns the git blob SHA as the `ETag`, so `resolve_lineage.py` prints the exact hash of both files
+at no extra request:
+
+```
+# source blobs lineage_notes.txt@b63582d49216 alias_key.json@0deb39eeac80
+```
+
+Keep that line with `dataVersion`; together they pin the result without staling the source.
+
+**GISAID.** `https://lapis.cov-spectrum.org/gisaid/v2` exists but requires credentials and its own
+data-use terms. This skill targets the open instances only. Open GenBank data is a subset of
+GISAID, so absolute counts here are lower than GISAID-derived figures — proportions are usually
+comparable, absolute counts are not.
+
+## Endpoints
+
+| Path | Use |
+| --- | --- |
+| `GET /sample/aggregated` | Counts, optionally grouped by `fields` |
+| `GET /sample/details` | Per-sequence metadata rows |
+| `GET /sample/aminoAcidMutations` | AA substitutions with per-site proportions |
+| `GET /sample/nucleotideMutations` | Nucleotide substitutions |
+| `GET /sample/aminoAcidInsertions`, `/sample/nucleotideInsertions` | Insertions |
+| `GET /sample/databaseConfig` | The schema: every metadata field and its type |
+| `GET /sample/referenceGenome` | Segment and gene names for mutation queries |
+| `GET /sample/lineageDefinition/{column}` | The lineage tree for an indexed column |
+| `GET /sample/info` | `dataVersion` — record it with any result you keep |
+| `GET /sample/unalignedNucleotideSequences`, `/sample/alignedNucleotideSequences`, `/sample/alignedAminoAcidSequences/{gene}` | FASTA download |
+| `GET /sample/mostRecentCommonAncestor`, `/sample/phyloSubtree` | Tree queries where a phylo field exists |
+| `POST /component/*OverTime` | Prebuilt time-series components |
+
+Every endpoint accepts GET and POST. Filters are query parameters; unknown ones are rejected.
+
+## Reading the schema first
+
+`/sample/databaseConfig` returns `schema.metadata[]` with a `name`, a `type`, and
+`generateLineageIndex`. Three things follow from it, and all three differ between instances:
+
+**1. Which column holds the lineage.** `schema.metadata[].generateLineageIndex` is true for
+`pangoLineage` and `nextcladePangoLineage` on SARS-CoV-2 and for nothing at all on H5N1, whose
+lineage-like column is a plain string `clade`.
+
+**2. Which date columns accept ranges.** LAPIS derives `<field>From` / `<field>To` from the
+declared type. Only `date`, `int` and `float` get them.
+
+| Instance | Collection date | Type | Range filter |
+| --- | --- | --- | --- |
+| `sars-cov-2` | `date` | date | `dateFrom` / `dateTo` |
+| `h5n1` | `sampleCollectionDate` | **string** | none |
+| `h5n1` | `sampleCollectionDateRangeLower` | date | `sampleCollectionDateRangeLowerFrom` / `...To` |
+
+`dateFrom=2025-01-01` against H5N1 is a 400. The error body lists every valid key for that
+instance, which is the fastest way to discover a schema by hand.
+
+**3. Which submission date exists.** `dateSubmitted` on SARS-CoV-2; `ncbiReleaseDate` on H5N1
+(`submittedDate` and `releasedDate` are there too, but typed string, so they cannot be ranged).
+
+`scripts/lapis_client.py` does this resolution in `describe_instance()`, `pick_date_field()` and
+`pick_lineage_field()`, and raises rather than guessing.
+
+## Lineage filters and the wildcard
+
+On a column with a lineage index, a trailing `*` means "this lineage and all descendants":
+
+```
+pangoLineage=XFG      ->   4 sequences   (sequences named exactly XFG)
+pangoLineage=XFG*     -> 640 sequences   (XFG and every descendant)
+```
+
+On a column **without** one, `*` is matched literally and finds nothing:
+
+```
+clade=2.3.4.4b        -> 62413 sequences
+clade=2.3.4.4b*       ->     0 sequences
+```
+
+Same syntax, opposite meaning, no warning either way. `lineage_filter()` refuses to build the
+second query.
+
+The index also decides how a bad name fails. On an indexed column an unknown lineage is rejected:
+
+```
+{"error":{"status":400,"detail":"Error from SILO: The lineage 'XFG.20' is not a valid lineage
+ for column 'pangoLineage'."}}
+```
+
+On an unindexed column the same typo returns `0` and looks like a finding. Validate names with
+`resolve_lineage.py` before reporting an absence.
+
+### The lineage definition endpoint
+
+`/sample/lineageDefinition/pangoLineage` returns roughly 5,500 entries of the form
+
+```json
+{"XFG.1.1": {"parents": ["XFG.1"], "aliases": ["xfg.1.1", ...]},
+ "PQ.17":   {"parents": ["NB.1.8.1"], "aliases": ["NB.1.8.1.17", ...]}}
+```
+
+**It roots recombinants.** `XFG` has no `parents` key, and no entry in the whole document has more
+than one parent. The recombinant parentage `XFG = LF.7 + LP.8.1.2` exists only in
+pango-designation's `alias_key.json`, where a recombinant's value is a *list*. Both sources are
+needed; neither is sufficient.
+
+Requesting the endpoint for an unindexed column returns 400.
+
+## Mutation queries
+
+`/sample/aminoAcidMutations` rows look like:
+
+```json
+{"mutation": "S:L452W", "count": 3793, "coverage": 5211, "proportion": 0.728,
+ "sequenceName": "S", "mutationFrom": "L", "mutationTo": "W", "position": 452}
+```
+
+`proportion = count / coverage`, and **`coverage` is the number of sequences that resolved that
+site**, not the number matching the filter. A site covered by 12 sequences can report
+`proportion: 1.000`. Always read `coverage` alongside it.
+
+`minProportion` (default 0.05) prunes the response server-side. For a diff between two lineages,
+fetch both at a low threshold and apply the reporting threshold client-side — otherwise a mutation
+absent from one side is indistinguishable from one pruned out of it. `mutation_profile.py` does
+exactly this.
+
+`sequenceName` is the gene on an unsegmented genome (`S`, `ORF1a`, `N`) and the gene or segment on
+a segmented one. Get the valid names from `/sample/referenceGenome`:
+
+- SARS-CoV-2: one sequence `main`; genes `E M N ORF1a ORF1b ORF3a ORF6 ORF7a ORF7b ORF8 ORF9b S`
+- H5N1: segments `seg1`–`seg8`; genes `PB2 PB1 PA PAX HA NP NA M1 M2 NS1 NS2`
+
+Nucleotide mutations on a segmented genome must be qualified by segment (`seg4:A123G`).
+
+## Aggregation
+
+`fields` on `/sample/aggregated` is the **group-by**, not a projection:
+
+```
+GET /sample/aggregated?fields=pangoLineage&country=USA&dateFrom=2026-04-01
+-> [{"count": 286, "pangoLineage": "XFG.1.1"}, ...]
+```
+
+`limit`, `offset` and `orderBy` are rejected here — the result has no inherent ordering:
+
+```
+"detail": "Offset and limit can only be applied if the output of the operation has some
+ ordering. ... Aggregated however produces unordered results."
+```
+
+Sort client-side. There is no ISO-week grouping; group by the date field and bin weeks yourself
+(`bin_weekly()`). Grouped rows carry nulls for sequences whose date was never reported — count
+them separately rather than dropping them silently.
+
+## Errors, versioning, and etiquette
+
+Two error envelopes are in use, both carrying `detail`:
+
+```json
+{"error": {"type": "about:blank", "title": "Bad request", "status": 400, "detail": "..."},
+ "info":  {"dataVersion": null, "requestId": "...", "lapisVersion": "0.8.3"}}
+```
+
+```json
+{"type": "about:blank", "title": "Bad Request", "status": 400, "instance": "/open/v2/query/parse"}
+```
+
+`_error_detail()` reads both. Always surface `detail` — on a bad filter key it enumerates every
+valid key for that instance.
+
+`info.dataVersion` accompanies every successful response and identifies the underlying snapshot.
+**Record it with any figure that will be quoted.** The same query returns different numbers on
+different days, and without the data version a result cannot be reproduced or audited.
+
+These are free public services with no API key. Ask for aggregates rather than per-sequence rows,
+send one query per question instead of paginating through sequences, and retry `429`/`5xx` with
+backoff (`MAX_ATTEMPTS = 3`, 1.5 s linear) rather than hammering.

package/skills/pathogen-variant-surveillance/references/lineage-nomenclature.md

@@ -0,0 +1,126 @@
+# Lineage nomenclature
+
+Naming systems are not interchangeable, are not stable, and several run side by side on the same
+instance. Values below were read from the live instances on 2026-07-27 and will have moved by the
+time you read this — the point is the *structure*, not the specific names.
+
+## SARS-CoV-2
+
+Four naming systems coexist on the open instance:
+
+| Column | Example values | What it is |
+| --- | --- | --- |
+| `pangoLineage` | `XFG.1.1`, `PQ.17`, `RE.2` | Pango designation; the fine-grained system |
+| `nextcladePangoLineage` | same vocabulary | Nextclade's own call, assigned by a versioned dataset |
+| `nextstrainClade` | `25C`, `25B`, `25I`, `recombinant` | Coarse year-plus-letter clades |
+| `whoClade` | `Omicron`, mostly null | WHO Greek labels |
+
+Two consequences worth knowing before choosing a column:
+
+- **`nextstrainClade` collapses every recombinant into one bucket.** 627 sequences collected in
+  2026 are labelled simply `recombinant`. Since the currently dominant lineages *are*
+  recombinants, `nextstrainClade` cannot distinguish XFG from XFJ. Use `pangoLineage` for anything
+  lineage-specific.
+- **`whoClade` is effectively retired.** It is null for the large majority of 2026 sequences; no
+  Greek letter has been assigned beyond Omicron. Do not expect a Greek label for a current lineage,
+  and do not invent one.
+
+### How Pango names are built
+
+Names root at `A` or `B` and extend by dots. Once a name would exceed three numeric levels it is
+**aliased** to a new letter prefix, and the alias key is the only way back:
+
+```
+PQ.17  = XDV.1.5.1.1.8.1.17
+RE.2   = BA.3.2.2.2 = B.1.1.529.3.2.2.2
+```
+
+`scripts/lapis_client.py:unalias_full()` walks this using the live `alias_key.json`. There is no
+way to derive it — the mapping is a file that changes.
+
+### Recombinants
+
+Names beginning `X` are recombinants. Their alias entry is a **list of parents**, not a path:
+
+```json
+{"XFG": ["LF.7", "LP.8.1.2"], "XFJ": ["LS.2.1.1", "LF.7.2"]}
+```
+
+LAPIS's own lineage definition does **not** carry this — it roots every `X*` lineage, and no entry
+in that document has more than one parent. Ask LAPIS for `XFG`'s parents and you get nothing. Both
+sources are required: LAPIS for the descendant index that queries use, `alias_key.json` for
+parentage.
+
+A recombinant's descendants alias normally (`XFG.1.1` → `XFG.1` → `XFG`), so ancestry *below* the
+recombination point behaves like any other lineage.
+
+### Designation churn
+
+`lineage_notes.txt` currently lists ~6,230 names, of which **294 are withdrawn or redesignated**.
+Entries are prefixed `*`:
+
+```
+*PC.2      Redesignated as LF.7.9, S:L441R, S:H445P, Wales/Scotland
+*XFG.20    Withdrawn: C10615T (didn't realize it was a dropout branch of XFG.3)
+*MC.34     Withdrawn: Alias of B.1.1.529.2.86.1.1.11.1.3.1.1.34
+```
+
+This is what makes a remembered lineage fact actively wrong rather than merely stale. Two
+follow-on effects:
+
+- **A withdrawn name can still be attached to sequences.** `PC.2` was redesignated `LF.7.9`
+  upstream, yet 25 sequences still carry `PC.2` because the instance's assignment pipeline lags
+  designation. Both facts are true; report the redesignation alongside the count.
+- **Nextclade calls depend on the dataset version.** The SARS-CoV-2 instance records
+  `nextcladeDatasetVersion` per sequence. Two sequences called on different dataset versions can
+  carry different lineage labels for identical genomes. Re-fetch the dataset
+  (`data.clades.nextstrain.org/v3`) before calling your own sequences, and record the version.
+
+## Influenza
+
+| Instance | Column | Live values |
+| --- | --- | --- |
+| `h3n2`, `h1n1pdm` | `cladeHA` (also `cladeNA`) | `K` (88.9% of 2025/26 H3N2), `J.2.4`, `J.2.3`, `J.2.2`, `unassigned` |
+| `h5n1` | `clade` | `2.3.4.4b` (essentially all of the current US data), `Am-nonGsGD` |
+| `influenza-a` | `subtypeHA` / `subtypeNA` | `H3`, `H5`, `H1`, `H9`, `H10` |
+
+Three cautions:
+
+- **HA and NA are called separately** and can disagree; a reassortant is normal, not an error.
+  `cladeHA` is the one antigenic and vaccine-strain discussion refers to, which is why the field
+  picker prefers it.
+- **`unassigned` is a real category**, not a null. Excluding it silently inflates every other
+  clade's proportion.
+- **H5N1 genotypes are not in this data.** The US genotype calls that dominate reporting — `B3.13`
+  (the dairy-cattle genotype) and `D1.1` (the poultry and wild-bird genotype) — describe the
+  reassortment pattern across all eight segments. The instance carries `clade` only, so both
+  genotypes appear identically as `2.3.4.4b`. Genotype must come from a whole-genome tool such as
+  GenoFLU, or from USDA/CDC reporting. Do not infer a genotype from a clade query, and do not
+  present `2.3.4.4b` counts as genotype counts. Host is often the more informative axis available
+  here: filtering US 2.3.4.4b by `hostNameScientific` separates `Bos taurus` from
+  `Gallus gallus` and wild birds directly.
+
+## Other pathogens
+
+| Instance | Columns | Notes |
+| --- | --- | --- |
+| `mpox` | `clade`, `outbreakLineage`, `lineage` | Two orthogonal systems: `clade` is `Ia`/`Ib`/`IIa`/`IIb`; `outbreakLineage` is `sh2023/A.1`-style. Only `outbreakLineage` is indexed. |
+| `rsv-a`, `rsv-b` | `lineage` (indexed), `subtype` | Post-2021 consensus lineage nomenclature (`A.D.5.2`-style) |
+| `dengue` | `lineage` (indexed), `serotype` | Serotype and lineage are different questions; pick deliberately |
+| `measles` | `genotype` | WHO genotypes (`B3`, `D8`, …), not indexed |
+| `west-nile` | `lineage` | Not indexed |
+| `cchf` | `lineage_S` | Named after the segment it is called on |
+| `hmpv` | `lineage` (indexed) | |
+| `ebola-zaire`, `ebola-sudan` | none | No lineage column exists; counts and lag still work |
+
+`resolve_lineage.py` prints the alternatives it did not pick, so run it once against an unfamiliar
+instance before committing to a column.
+
+## Choosing a column
+
+1. Prefer an **indexed** column when the question involves descendants — only those support `NAME*`.
+2. Prefer the **finest** system that answers the question. Coarse clades hide the distinction you
+   are usually asking about (`nextstrainClade` and recombinants being the clearest case).
+3. Say which column you used. "XFG.1.1 is 35% of US sequences" is ambiguous until you add
+   *`pangoLineage`, exact name, not including descendants* — three separate choices, each of which
+   changes the number.

package/skills/pathogen-variant-surveillance/references/surveillance-caveats.md

@@ -0,0 +1,149 @@
+# Surveillance caveats
+
+Genomic surveillance data is a convenience sample of a convenience sample: someone had to be
+tested, the specimen had to be selected for sequencing, the sequence had to pass QC, and a
+laboratory had to submit it. Every number below survives that funnel. The caveats here are the
+difference between a defensible statement and a confident wrong one.
+
+## Reporting lag is the dominant error
+
+**Recent weeks are not a sample of what was circulating. They are a sample of whoever reports
+fastest.** Measured on the open SARS-CoV-2 instance, US sequences, six monthly cohorts:
+
+| Days after collection | Share of the cohort that has arrived |
+| --- | --- |
+| 7 | 29% |
+| 14 | 46% |
+| 30 | 68% |
+| 60 | 87% |
+| 90 | 94% |
+| 180 | 100% |
+
+H5N1 is far slower: 0% at 14 days, 15% at 30 days, 85% at 60 days.
+
+Two things follow.
+
+**The denominator for the last several weeks is a fraction of its final size.** A collection week
+that will eventually hold 200 sequences may hold 20 today, and those 20 come disproportionately
+from the fastest-reporting laboratories — which are geographically and institutionally clustered.
+The resulting proportion is not merely noisy, it is *biased*, and no confidence interval accounts
+for that bias.
+
+**A "new variant" can be an artifact of who reported first.** A lineage that looks like it appeared
+last week may simply be the lineage of the laboratory with the shortest turnaround.
+
+Run `reporting_lag.py` for the instance and country in question — the curve differs sharply
+between them — and treat the cutoff it prints as the boundary of interpretable data.
+`lineage_prevalence.py` flags weeks whose denominator has not filled in and excludes them from
+growth fits by default.
+
+The measured curve is a **lower bound**: it uses each cohort's present-day total as the
+denominator, and even year-old cohorts still gain sequences.
+
+## Sampling and ascertainment bias
+
+Sequence counts are not case counts, and nothing in this data corrects for:
+
+- **Which specimens get sequenced.** Programmes variously prioritise travellers, hospitalised
+  patients, outbreak investigations, S-gene target failures, or a random subsample. The
+  SARS-CoV-2 instance carries a `samplingStrategy` field that is frequently null.
+- **Where.** Sequencing capacity is concentrated. A global proportion is close to a weighted
+  average of a handful of well-resourced countries. Filter to a geography you can interpret, and
+  say which.
+- **Who.** Host matters outside human pathogens. For H5N1 the same clade in `Bos taurus`,
+  `Gallus gallus`, and wild birds represents entirely different epidemiology; an unfiltered clade
+  count silently pools them.
+- **QC.** Sequences failing coverage thresholds are absent, and failure is not random with respect
+  to lineage — a lineage with a primer-dropout region is under-represented exactly where the
+  dropout matters.
+
+None of this is fixable from the API. It is reportable, and the honest form is "X% of *sequenced
+specimens meeting these filters*", never "X% of infections".
+
+## Denominators
+
+Decide explicitly, and state it:
+
+- **Exact name vs. including descendants.** `XFG` alone is 4 sequences; `XFG*` is 640. Almost
+  every question about a lineage's importance means the second.
+- **Geography.** `--where country=USA` and no filter answer different questions.
+- **Window.** A 26-week window and a 4-week window can invert the apparent ranking of two lineages.
+  Windows are widened to whole ISO weeks so every row covers the same number of days.
+- **Undated sequences.** Sequences with no usable collection date are excluded from weekly bins;
+  `lineage_prevalence.py` reports how many rather than dropping them silently. Note that they are
+  still counted by the descendant check, which is why that check compares two counts of the same
+  kind rather than a count against a sum of bins — mixing the two made every lineage with undated
+  sequences look as though it had descendants it does not.
+- **Unassigned calls.** The most frequent value in a lineage column is sometimes null or
+  `unassigned`. Discovery mode skips those, but they stay in the denominator, which is correct:
+  they were sequenced, they just were not classified.
+
+## Intervals
+
+Proportions carry **Wilson score intervals**. The normal-approximation (Wald) interval is wrong in
+exactly the situations surveillance produces constantly: it leaves the unit interval for small
+`n`, and collapses to zero width at `p = 0`, which would report "0.0% (0.0–0.0)" for a lineage seen
+zero times in 20 sequences. Wilson gives 0–17% there, which is the honest answer.
+
+The interval covers **binomial sampling error only**. It does not cover reporting bias, geographic
+clustering, or lineage-assignment error, all of which are typically larger. Two intervals
+overlapping is weak evidence of no difference; two not overlapping is not proof of one.
+
+## Growth estimates
+
+`--growth` fits a weighted least-squares line to the log-odds of the proportion against time,
+weighting each week by `n·p·(1−p)` and applying a Haldane–Anscombe 0.5 correction so 0 and 1 stay
+finite.
+
+**What it is:** a description of how the log-odds of this lineage among sequenced specimens moved
+over this window, in this place.
+
+**What it is not:** a fitness estimate, a transmissibility estimate, or a forecast. A logistic
+model assumes two competing populations under constant conditions. Real windows contain changing
+sequencing programmes, shifting geography, holidays, and multiple co-circulating lineages.
+
+Two guards keep the interval honest.
+
+**Observation thresholds.** With the continuity correction alone, a lineage observed **zero** times
+in every week still produces p = 0.5/(n+1), which drifts purely with the denominator. A shrinking
+denominator then manufactures a tight, confident-looking positive slope for a lineage nobody has
+seen — this was observed in testing, at +0.105/week with a CI excluding zero, for a lineage with
+no observations at all. `logit_slope()` therefore requires at least 5 observations across at least
+3 non-empty weeks and returns nothing otherwise. Do not lower those thresholds to get a number.
+
+**Dispersion clamped at 1.** The standard error uses a quasi-binomial dispersion estimated from the
+residuals, floored at 1. With inverse-variance weights the model's own scale *is* 1, so an estimate
+below it means a short series happened to sit near the line — not that the slope is better
+determined than binomial sampling allows. Letting that through would report an interval narrower
+than the data supports. Above 1 the estimate is kept, so genuine overdispersion widens the interval
+as it should. The reported `dispersion` is worth reading: well above 1 means the weekly points
+scatter far more than binomial sampling explains, which usually means the denominator's composition
+is changing and the slope is describing that rather than the lineage.
+
+When quoting a slope, give the window, the geography, the number of weeks, and the interval, and
+call it descriptive.
+
+## Reproducibility
+
+The database changes daily. A result without `dataVersion`, the instance, the filters, and the
+window cannot be reproduced or audited — the same query will simply return different numbers.
+Every script prints all four. Keep them with the figure.
+
+Open GenBank-derived instances hold a subset of what GISAID holds. Absolute counts here are lower
+than GISAID-derived figures; proportions are usually comparable but not identical. Do not mix the
+two in one table.
+
+## What this data cannot support
+
+- **Case counts, incidence, or severity.** Sequences are not cases; there is no denominator of
+  infections and no outcome data.
+- **Clinical interpretation.** Nothing here speaks to how a patient should be treated.
+- **Outbreak-response or public-health recommendations.** Those require case surveillance,
+  local context, and authority this data does not carry.
+- **Claims about a lineage's biology from its frequency.** A rising proportion is consistent with
+  higher transmissibility, immune escape, a founder effect, a single outbreak in one facility, or
+  a change in who is being sequenced. Frequency alone does not distinguish them.
+- **Absence.** "Zero sequences" means zero *sequenced and submitted* specimens under these
+  filters. With H5N1 at 15% completeness after 30 days, recent absence is close to uninformative.
+  Check whether the name is even valid first — on an unindexed column, a typo returns 0 rather
+  than an error.