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:

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:

{"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

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

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.