pango-designation: the data files behind SARS-CoV-2 lineage naming

Three data files that most Pango tooling ends up reading

The pango-designation repository is the upstream data source for SARS-CoV-2 lineage naming. Its stated purpose is the latest maintained Pango-lineage designations, and the description says it is the repository for suggesting new lineages that should be added to the current scheme.

The resources section names what is hosted here, following the former pango.network website. The lineage description list is lineage_notes.txt. The sequence designation list is lineages.csv. The alias record is alias_key.json, which lives under the pango_designation package directory.

These are different things and the distinction matters if you are joining against them. The sequence designation list is the tabular one, a CSV of designations, and it is the file you would load into a dataframe. The lineage description list is prose, the notes that accompany a lineage and carry the reasoning behind it. The alias record is a JSON map of alternative names, which is what you use to reconcile the several spellings a lineage can appear under.

The primary language listed for the repository is Jupyter Notebook, and the top level listing shows why. Alongside the data files there is automated-issue-ref.ipynb, anaconda_projects/, autoref/, curation_notes/, scripts/, utils/, tests/, a pango_designation/ package directory, and a set of maintenance scripts: analyze_lineage_notes.py, deduplicate_keeping_first.py, deduplicate_keeping_last.py, drop_duplicate_rows.py, checkDups.sh and findDups.sh.

The naming of the deduplication scripts is telling. There are two, one keeping the first occurrence and one keeping the last, which tells you the duplicate question has more than one defensible answer and the project would rather ship both than pick for you.

This is a data repository with a small amount of tooling around it, not an application. The distinction matters for how you depend on it.

Cloning the repository without pulling 15GB of CSV history

The developer docs contain the single most practically important instruction in the README, and it is a warning about the size of the data.

It is recommended to clone the repo using --filter=blob:none for a blobless clone unless you want to download and put 15GB on your hard drive. The reason given is that the lineages.csv file is quite large, and since git stores the state of each file at each commit, that creates a large repo. The README notes that git is good at downloading past blobs when necessary, so you should not be impacted in your day to day work by doing this partial clone.

The recommended commands are:

git clone --filter=blob:none https://github.com/cov-lineages/pango-designation.git
gh repo clone cov-lineages/pango-designation -- --filter=blob:none

Both commands request a blobless clone; the second uses the GitHub CLI.

This is worth understanding rather than just copying. The full history of a CSV that changes on every lineage addition is expensive to store, and the fix is partial clone, where the file contents are fetched on demand rather than all at once. The README links to a GitHub blog post on partial and shallow clone for the background.

If you only want the current state of the data, the release tags are a much cheaper route than any clone. The three most recent are v1.41 on 2026-09-24, v1.40 on 2026-08-13 and v1.39 on 2026-06-09, and the tag naming follows the release version, so v1.41 tells you exactly which designation snapshot you have. The repository is not archived and the last push was on 2026-10-13, so master moves ahead of the newest tag.

The mutation constellations, and why they are reference only

The lineage_constellations directory holds the mutations associated with each of the AY lineages. The README is precise about what these are and, more importantly, about what they are not.

They are the mutations that were acquired along the phylogenetic path leading to the common ancestor of the lineage and that remain conserved in the lineage, defined as being in more than 70 percent of sequences designated to the lineage. The path is identified using the UShER phylogenetic tree.

The threshold does the work here. A constellation is a path, not a definition, so at each position the mutations on the path can be conserved, absent, or somewhere in between, and the 70 percent cut is where a position counts as a lineage-wide property.

Two limitations follow, and the README states both. These constellations differ from those in the separate constellations repository, because they attempt to capture all of the associated mutations rather than only the defining mutations for a lineage. And they are provided for reference and are not used by scorpio currently, though the README says they should be compatible with scorpio if researchers are interested in exploring them.

The scorpio point is a useful signal about the ecosystem. Because scorpio does not consume these richer constellations, they sit outside the current designation pipeline. If you are building a tool that needs path mutations rather than defining ones, this is where they are, and the note that they should be compatible with scorpio is the hint about how to consume them.

The README also calls out the intermediate category explicitly. Sites in that category drop in and out in the Delta clade, so they may be associated with the lineage but may be prone to artefacts. That is a warning for anyone treating a constellation as a checklist, and it is a good example of the project documenting its own uncertainty rather than presenting a clean set of rules.

How a new lineage gets proposed, and where the rules actually live

The contribution path is an issue, and it is a specific one. Novel lineages or lineage refinements can be suggested by filing an issue with the respective sequence names as found on GISAID, and any supporting information such as a phylogenetic tree for the putative lineage.

Two details are load bearing. The sequence names must be as found on GISAID, so the evidence is anchored in the sequence database rather than in the submitter's own labelling. And the supporting information is a phylogenetic tree, which is the same UShER tree the constellations section refers to.

The rules themselves are not in this repository. Full details on how to suggest a new lineage are in the Pango lineage designation guide, and the nomenclature rules are in the Pango statement of nomenclature rules. Both links point at web.archive.org copies of pango.network pages, with the archive dates of 2024-01-16.

That detail is significant and easy to skim past. The repository links to archived versions of the Pango guidance rather than live pages, and the README says the resources previously lived on the former pango.network website. So the authoritative documentation for the naming scheme is a frozen snapshot from January 2024, and the current data in the repository has been updated since then by v1.39, v1.40 and v1.41 at minimum.

The consequence is that a researcher using this repository has the current designations but not necessarily the current rules, and the rules are what determine whether a proposed lineage name will be accepted. The name proposal guide, the nomenclature statement, the UShER tree and the GISAID sequence names are the four pieces you need to file a valid suggestion, and only the last two are referenced from inside the data.

The repository itself is where suggestions land and where the designation lists are maintained, so the split is deliberate: the scheme is documented publicly, the data and the proposals are versioned here.

The Python package, the licence and what the tooling is for

There is a Python package in the repository, pango_designation/, and the setup.py installs it with a console script entry point. The entry point is generated from a _program variable that the setup.py comment says is set in __init__.py, and that variable determines the name of the package and of the final command line tool. The entry point maps {program} to pango_designation.command:main, so the tool is a thin wrapper around a main function in the command module.

The package metadata describes it as PANGO lineage designations for SARS-CoV-2, authored by the cov-lineages group. The alias_key.json file is declared as package data, include_package_data is on, and zip_safe is set to False, which is a sensible choice for a package that ships a data file.

The rest of the top level listing describes a repository that automates curation. There is a .pre-commit-config.yaml, so formatting and checks run on commit, a checkDups.sh and findDups.sh pair for duplicate detection, curation_notes/ for the record of manual curation decisions, autoref/ for reference maintenance, misc/, scripts/, utils/, tests/ and docs/. There is also an analyze_lineage_notes.py, which suggests the notes file is machine checked as well as written by hand.

The licence is the point to check before you build on this. It is listed as Other, a custom licence that GitHub cannot classify, with a LICENSE.md file at the root. That is the only authoritative statement of the terms, and the README does not summarise them. For a dataset that many analyses and dashboards build on, the licence question is worth resolving early rather than after publication, and a custom licence may well include attribution or use conditions that a permissive licence would not impose.

The maintenance picture is a date rather than an adjective. The repository is not archived, the last push was on 2026-10-13, and the release tags v1.41, v1.40 and v1.39 carry dates of 2026-09-24, 2026-08-13 and 2026-06-09.

Editorial conclusion

pango-designation fits a researcher, pipeline or dashboard that needs the current Pango lineage designations as a data source, whether as the CSV to join against, the notes for context, or the alias key to reconcile naming. It is the wrong tool if you need the nomenclature rules, the guidance on proposing a lineage, or the definition of what a lineage means, because those live on the pango network site rather than here, and this repository links to archived copies of them. Before using the data, read the LICENSE.md file yourself, since GitHub could not classify the licence, and decide whether to take the release tags or the master branch, because the tag names follow the release version.

Frequently asked questions

Official sources

1. cov-lineages/pango-designation on GitHub
2. Issues
3. README
4. Releases