/pathogen-variant-surveillance

name: pathogen-variant-surveillance
description: Query live pathogen genomic surveillance data through the GenSpectrum LAPIS API to find which viral lineages are circulating now, how fast they are growing, and what mutations they carry. Use whenever a question depends on the current state of a pathogen population rather than on remembered facts - which SARS-CoV-2 variant is dominant, whether a Pango lineage is still designated or has been withdrawn, what clade or genotype of H5N1 is in a host or region, whether a PCR primer or assay target still matches circulating sequence, or how a lineage's prevalence has moved week to week. Triggers include "variant surveillance", "genomic surveillance", "what variant is circulating", "dominant variant", "Pango lineage", "lineage prevalence", "growth advantage", "SARS-CoV-2 variant", "XFG", "clade 2.3.4.4b", "H5N1 genotype", "influenza clade", "RSV/mpox/measles/dengue lineage", "CoV-Spectrum", "LAPIS", "Nextclade", "pango-designation", and any request to report what a pathogen population looks like today.
license: MIT
compatibility: Requires Python 3.11+. Scripts use only the standard library - no third-party packages. Needs network access to the public GenSpectrum LAPIS instances (lapis.cov-spectrum.org, lapis.genspectrum.org, lapis.pathoplexus.org) and to raw.githubusercontent.com for pango-designation. No API key.
allowed-tools: Read Write Edit Bash
metadata:
  version: "1.1"
  skill-author: K-Dense Inc.
  last-reviewed: "2026-07-27"

Pathogen Variant Surveillance

When to use

Any time an answer depends on what a pathogen population looks like **now**: which lineages are circulating, whether one is growing, what a lineage name currently means, or whether an assay target still matches.

The rule

**Never state what is circulating, and never write a lineage name, from memory.**

Three things go wrong at once, and only the first is an ordinary knowledge-cutoff problem:

1. **Names post-date training.** The Pango designation list carries over 6,200 names and grows continuously. 2. **The nomenclature is a live data structure, not a convention.** `XFG` is a recombinant that only resolves through `alias_key.json`; `PQ.17` unaliases to `XDV.1.5.1.1.8.1.17`. Neither expansion is derivable by reasoning — the mapping is a file that changes. 3. **Prior knowledge gets retracted, not just outdated.** 294 names in the current `lineage_notes.txt` are withdrawn or redesignated. `PC.2` is now `LF.7.9`; `XFG.20` was withdrawn outright. A remembered lineage fact is not merely stale, it can be actively wrong.

Every number this skill reports is a count returned by a live instance, stamped with the data version it came from.

Scope

Surveillance data analysis for research. This skill describes sequences that were collected and submitted; it does not produce clinical interpretations, outbreak-response recommendations, or public-health guidance, and sequence counts are not case counts.

Instances

One API shape covers every pathogen. `--instance` names a verified deployment; `--base-url` reaches any other LAPIS instance.

| Instance | Host | Lineage column | Indexed | | --- | --- | --- | --- | | `sars-cov-2` | lapis.cov-spectrum.org (open GenBank data) | `pangoLineage` | yes | | `h5n1`, `h3n2`, `h1n1pdm`, `influenza-a` | lapis.genspectrum.org | `clade` | no | | `rsv-a`, `rsv-b`, `mpox`, `measles`, `dengue`, `west-nile`, `hmpv`, `ebola-zaire`, `ebola-sudan`, `cchf` | lapis.pathoplexus.org | varies | varies |

**Field names differ per instance and are never assumed.** Every script reads `/sample/databaseConfig` at run time and picks the collection-date, submission-date and lineage columns from what the instance actually declares. `dateFrom=` is correct on SARS-CoV-2 and a hard 400 on H5N1, whose collection date is `sampleCollectionDateRangeLower`.

Scripts

cd skills/pathogen-variant-surveillance/scripts

| Script | Question answered | | --- | --- | | `resolve_lineage.py` | Does this name still exist, what does it expand to, what is it descended from? | | `lineage_prevalence.py` | What share of sequences is this lineage, week by week, and is it growing? | | `mutation_profile.py` | What mutations does it carry, and how does it differ from another lineage? | | `reporting_lag.py` | How far back does the data have to go before it can be trusted? |

All four take `--format table|tsv|json` and print provenance (instance, data version, resolved field names, filters) to stderr, so `> out.tsv` keeps the data clean and the provenance visible.

Start from the data, not from a remembered list

# no names: discover what is actually circulating in the window
python3 lineage_prevalence.py --top 5 --where country=USA --weeks 12

> note: discovered the 5 most common pangoLineage values in the window: > XFG.1.1, XFG.23.1.3, PY.1.1.1, XFJ.3.1.2, PQ.17

This is the right first command for "what is circulating". Naming lineages up front presumes you already know which ones matter, which is the assumption this skill exists to remove.

Check a name before using it

python3 resolve_lineage.py XFG.23.1.3 PQ.17 PC.2 NOTALINEAGE

query        status     unaliased                        parent    recombinant_of  descendants  sequences  detail
XFG.23.1.3   current    XFG.23.1.3                       XFG.23.1  LF.7+LP.8.1.2   6            317        S:A1174V, on C29137T branch
PQ.17        current    XDV.1.5.1.1.8.1.17               NB.1.8.1                  23           931        Alias of XDV.1.5.1.1.8.1.17
PC.2         withdrawn  B.1.1.529.2.86.1.1.16.1.7.2.1.2  LF.7.2.1                  4            25         now LF.7.9; Redesignated as LF.7.9
NOTALINEAGE  unknown    NOTALINEAGE                                                0            n/a        no such name in the live nomenclature

(`detail` abridged; each real row also cites the lineage proposal it came from.)

Exit code is 1 if any name is withdrawn