Label every group with an English name and fix the hover treatment (#2)

- Label every group with an English name and fix the hover treatment (dd2b8fbb121d49f4398aabd348d13281a9bb8b78)

FEATURE_BACKLOG.md

@@ -54,7 +54,9 @@ Desired behavior:
 Decisions and dependencies for implementation:
 
 - Implemented: eukaryotic tree with bounded subtrees and exact, expandable “Other lineages” aggregates; NCBI taxonomy with source checksums and dates; merged IDs resolved. Unresolved taxonomy is excluded from the eukaryotic view.
+- Implemented: English names beside every scientific name, from NCBI Taxonomy common names plus a curated gloss table (`refresh_common_names.py`).
 - Remaining: connect the taxonomy inventory to accession-level annotation results and distinguish partial/complete base coverage.
+- Remaining: clade icons. [PhyloPic](https://www.phylopic.org) is the usable source and resolves NCBI taxids directly, walking up the tree when a clade has no silhouette of its own: `GET https://api.phylopic.org/resolve/ncbi.nlm.nih.gov/taxid/{taxid}?embed_primaryImage=true` with `Accept: application/vnd.phylopic.v2+json`, which returns an SVG under `_embedded.primaryImage._links.vectorFile.href`. Two things to settle before using it: licences differ per image (CC0, CC BY 4.0, CC BY-SA 3.0 and at least one CC BY-NC-SA 3.0 among the groups the atlas shows first), so each icon needs its own credit line and the non-commercial ones need replacing or omitting; and the SVGs should be fetched once into the repo rather than hot-linked, to keep the Space free of external requests.
 
 ## F003 — Comparison with RefSeq annotations
 

README.md

@@ -17,7 +17,7 @@ Future features and open design decisions are tracked in the [feature backlog](F
 
 ## GenBank taxonomy
 
-The landing page opens with an interactive **tree of eukaryotic life**, using NCBI's current GenBank assembly summary and taxonomy. It is drawn as a Sankey diagram: each group is a bar split into annotated (green) and not-annotated (gray) assemblies, and flows carry both parts from a group into its lineages. Counts and percentages appear beside the groups, with details on hover. The default **Genome Atlas** tab contains the tree and its lineage controls. A separate **Database** tab holds accession search, segment visualization, and downloads, using the full published-file snapshot. RefSeq exploration can be added beneath the tree. The two equal-width navigation options span the top of the page.
+The landing page opens with an interactive **tree of eukaryotic life**, using NCBI's current GenBank assembly summary and taxonomy. It is drawn as a Sankey diagram: each group is a bar split into annotated (green) and not-annotated (gray) assemblies, and flows carry both parts from a group into its lineages. Counts and percentages appear beside the groups, with details on hover. Each group is labelled with its scientific name and, where one exists, a plain-English name underneath, so the Latin backbone of the tree (Opisthokonta, Eumetazoa, Ecdysozoa) stays readable without prior knowledge. The default **Genome Atlas** tab contains the tree and its lineage controls. A separate **Database** tab holds accession search, segment visualization, and downloads, using the full published-file snapshot. RefSeq exploration can be added beneath the tree. The two equal-width navigation options span the top of the page.
 
 The viewer is restricted to **Eukaryota (NCBI taxid 2759) and its descendants**, including search, breadcrumbs, and parent navigation. The model predicts eukaryotic annotations; bacteria, archaea, and viruses are outside this display. The current eukaryotic snapshot contains **70,395 assemblies**, of which **17,561 (24.9%)** have published annotations. The underlying SQLite snapshot retains the full NCBI inventory for refresh/provenance, while the interface uses only the eukaryotic subtree and its denominators. Assemblies with unresolved taxonomy cannot be assigned to that subtree and are excluded.
 
@@ -25,6 +25,8 @@ The inventory accepts `GCA_` accessions with `version_status=latest`. Each assem
 
 Click a group to expand its direct lineages into a new column on the right; every ancestor column stays visible, so the full path from Eukaryota is always on screen. Clicking a group in an earlier column replaces the columns after it. Use breadcrumbs, “Collapse last group”, or shortcuts to go back. Nodes support Enter/Space keyboard navigation. The opening view expands the actual animal/fungal ancestor, Opisthokonta. Each column shows six direct lineages, an expandable remainder, and the selected lineage if it falls outside the top six. Bar and flow heights follow assembly counts within a column; every column is rescaled to the full height. “Other lineages” is an explicitly labeled display aggregate, not an invented clade; its counts sum the remaining siblings. Repeated expansion reaches all siblings without truncating them. Scientific-name/taxon-ID search also reaches individual taxa. Column spacing does not encode time. The view scrolls horizontally, and jumps to the newest column after each expansion.
 
+English names come from `data/common_names.json`, built by `refresh_common_names.py` from NCBI Taxonomy's `genbank common name` and `common name` entries (about 9,200 taxa) plus a curated table of roughly 190 short glosses for the large unranked clades NCBI leaves unnamed. Glosses are plain-language summaries of the living members of a clade, not formal synonyms; the scientific name stays the primary label and a gloss that merely repeats it is dropped at build time. Rebuild it with `python refresh_common_names.py` once `.cache/coverage/taxdump.tar.gz` is present; the build fails if a curated taxid no longer matches its scientific name in the snapshot.
+
 The graphic uses server-rendered SVG/HTML with scoped styles in `atlas.css` and delegated click/keyboard handlers in `atlas.js`; no external graphics library or image assets are required. Include these files when deploying.
 
 The annotation workspace shares the atlas palette and typography through `style.py` and `app.css`: warm panels, serif section headings, green controls, and matching tables, downloads, and disclosures. CDS plots use a solid green positive strand and a dashed warm-brown negative strand; binary labels use green. The fixed light palette stays consistent with the landing graphic under either OS color preference. Include both style files when deploying; Gradio 6 receives the theme and stylesheet in `launch()`.

atlas.css

@@ -31,17 +31,19 @@
 .bar-outline { fill:none; stroke:#f7f8f0; stroke-width:1; }
 .tree-node { cursor:pointer; }
 .tree-node.is-direct { cursor:default; }
-.tree-hit { fill:transparent; transition:fill .15s; }
-.tree-node:hover .tree-hit,.tree-node:focus .tree-hit { fill:#e5ecdd99; }
+.tree-hit { fill:transparent; }
 .tree-node:focus { outline:none; }
 .tree-node:focus .bar-outline { stroke:#173c30; stroke-width:2; }
 .tree-node.is-selected .bar-outline { stroke:#173c30; stroke-width:1.5; }
 .tree-node.is-sibling { opacity:.62; transition:opacity .15s; }
 .tree-node.is-sibling:hover,.tree-node.is-sibling:focus { opacity:1; }
-.tree-label,.tree-count { paint-order:stroke; stroke:#f7f8f0; stroke-width:4px; stroke-linejoin:round; }
-.tree-label { font:600 13px Arial,Helvetica,sans-serif; fill:#254735; }
+.tree-label,.tree-english,.tree-count { paint-order:stroke; stroke:#f7f8f0; stroke-width:4px; stroke-linejoin:round; }
+.tree-label { font:600 13px Arial,Helvetica,sans-serif; fill:#254735; transition:fill .15s; }
 .tree-node.is-selected .tree-label { font-weight:700; fill:#173c30; }
+.tree-english { font:italic 11.5px Georgia,'Times New Roman',serif; fill:#5d7a66; }
 .tree-count { font:11px Arial,Helvetica,sans-serif; fill:#697966; }
+.tree-node:not(.is-direct):hover .tree-label,.tree-node:focus .tree-label { fill:#0f2e22; text-decoration:underline; }
+.tree-node:not(.is-direct):hover .bar-outline { stroke:#287557; stroke-width:2; }
 .atlas-footer { display:flex; align-items:center; flex-wrap:wrap; gap:15px; justify-content:space-between; border-top:1px solid #dde4d5; padding-top:14px; color:#6c7a66; font-size:11px; line-height:1.6; }
 .atlas-legend { display:flex; gap:7px; align-items:center; }
 .atlas-swatch { width:10px; height:10px; border-radius:2px; }

refresh_common_names.py

@@ -0,0 +1,273 @@
+"""Build the English name lookup used by the Genome Atlas labels.
+
+Two sources are merged, curated names winning over NCBI:
+
+* NCBI Taxonomy ``names.dmp`` supplies ``genbank common name`` and ``common name``
+  for roughly 9,000 taxa, almost all of them species, genera and familiar classes.
+* A curated table below covers the large unranked clades that NCBI leaves
+  unnamed. These are exactly the groups the atlas shows first — Opisthokonta,
+  Eumetazoa, Ecdysozoa and their kin — so without them the top of the tree reads
+  as untranslated Latin.
+
+Curated glosses are short, lower-case noun phrases describing the living members
+of the clade. They are plain-language summaries, not formal synonyms; the
+scientific name stays the primary label everywhere in the interface.
+"""
+import argparse
+from collections import Counter
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import sqlite3
+import tarfile
+
+ROOT = Path(__file__).resolve().parent
+NAME_CLASSES = ("genbank common name", "common name")
+
+# taxid: (scientific name, English gloss). The scientific name is verified
+# against the snapshot so a wrong taxid fails the build instead of mislabelling
+# a clade.
+CURATED = {
+    2698737: ("Sar", "marine algae and protists"),
+    554915: ("Amoebozoa", "amoebas"),
+    2611352: ("Discoba", "flagellate protists"),
+    33682: ("Euglenozoa", "euglenids and trypanosomes"),
+    2704647: ("Metakinetoplastina", "trypanosomes and kin"),
+    2696291: ("Ochrophyta", "brown algae and diatoms"),
+    431838: ("Intramacronucleata", "ciliates"),
+    422676: ("Aconoidasida", "malaria parasites and kin"),
+    1280412: ("Conoidasida", "gut parasites"),
+    2692248: ("core chlorophytes", "green algae"),
+    3166: ("Chlorophyceae", "green algae"),
+    75966: ("Trebouxiophyceae", "green algae"),
+    1035538: ("Mamiellophyceae", "tiny marine green algae"),
+    13792: ("Mamiellales", "tiny marine green algae"),
+    127916: ("Ichthyosporea", "parasites of fish and kin"),
+    2687318: ("Filasterea", "single-celled animal relatives"),
+    2686024: ("Rotosphaerida", "amoeboid protists"),
+    6042: ("Demospongiae", "common sponges"),
+    1913637: ("Mucoromycota", "bread moulds and kin"),
+    451507: ("Mucoromycotina", "bread moulds"),
+    3704128: ("Kickxellomycota", "thread-like fungi"),
+    112252: ("Fungi incertae sedis", "fungi of uncertain position"),
+    33154: ("Opisthokonta", "animals and fungi"),
+    6072: ("Eumetazoa", "animals with true tissues"),
+    33213: ("Bilateria", "two-sided animals"),
+    33317: ("Protostomia", "mouth-first animals"),
+    1206794: ("Ecdysozoa", "moulting animals"),
+    2697495: ("Spiralia", "spiral-cleaving animals"),
+    1206795: ("Lophotrochozoa", "molluscs, worms and kin"),
+    88770: ("Panarthropoda", "arthropods and kin"),
+    3701028: ("Altocrustacea", "crustaceans and insects"),
+    3701030: ("Allotriocarida", "insects and some crustaceans"),
+    85512: ("Dicondylia", "most insects"),
+    33340: ("Neoptera", "wing-folding insects"),
+    33342: ("Paraneoptera", "bugs, lice and thrips"),
+    3701061: ("Eumetabola", "advanced insects"),
+    33392: ("Endopterygota", "insects with metamorphosis"),
+    3701062: ("Aparaglossata", "most metamorphic insects"),
+    3701063: ("Panorpida", "flies, moths and kin"),
+    3701064: ("Neuropteroidea", "beetles and lacewings"),
+    41084: ("Polyphaga", "most beetles"),
+    41088: ("Cucujiformia", "plant-eating beetles"),
+    7434: ("Aculeata", "bees, wasps and ants"),
+    85604: ("Amphiesmenoptera", "moths and caddisflies"),
+    41191: ("Glossata", "moths and butterflies"),
+    41196: ("Neolepidoptera", "moths and butterflies"),
+    41197: ("Heteroneura", "moths and butterflies"),
+    37567: ("Ditrysia", "most moths and butterflies"),
+    104430: ("Apoditrysia", "moths and butterflies"),
+    104431: ("Obtectomera", "macro-moths and butterflies"),
+    37570: ("Noctuoidea", "owlet moths"),
+    40092: ("Hesperioidea", "skipper butterflies"),
+    37568: ("Tortricoidea", "leafroller moths"),
+    7139: ("Tortricidae", "leafroller moths"),
+    7203: ("Brachycera", "short-horned flies"),
+    480118: ("Eremoneura", "advanced flies"),
+    480117: ("Cyclorrhapha", "advanced flies"),
+    43733: ("Muscomorpha", "house flies and kin"),
+    43738: ("Schizophora", "advanced flies"),
+    43741: ("Acalyptratae", "small flies"),
+    43746: ("Ephydroidea", "fruit flies and kin"),
+    43845: ("Drosophilinae", "fruit flies"),
+    46877: ("Drosophilini", "fruit flies"),
+    119089: ("Chromadorea", "roundworms"),
+    6236: ("Rhabditida", "roundworms"),
+    89593: ("Craniata", "animals with a skull"),
+    117570: ("Teleostomi", "jawed vertebrates with bone"),
+    8287: ("Sarcopterygii", "lobe-finned fish and kin"),
+    1338369: ("Dipnotetrapodomorpha", "lungfish and land vertebrates"),
+    186623: ("Actinopteri", "ray-finned fish"),
+    41665: ("Neopterygii", "modern ray-finned fish"),
+    1489341: ("Osteoglossocephalai", "bony-tongued fish and kin"),
+    186625: ("Clupeocephala", "most teleost fish"),
+    1489388: ("Euteleosteomorpha", "advanced teleost fish"),
+    123365: ("Neoteleostei", "advanced bony fish"),
+    123366: ("Eurypterygia", "advanced bony fish"),
+    123367: ("Ctenosquamata", "advanced bony fish"),
+    123368: ("Acanthomorphata", "spiny-rayed fish"),
+    123369: ("Euacanthomorphacea", "spiny-rayed fish"),
+    1489872: ("Percomorphaceae", "perch-like fish"),
+    1489922: ("Eupercaria", "perch-like fish"),
+    1489908: ("Ovalentaria", "cichlids and relatives"),
+    1489910: ("Cichlomorphae", "cichlids and kin"),
+    318546: ("Pseudocrenilabrinae", "African cichlids"),
+    186634: ("Otomorpha", "carps, catfish and herrings"),
+    32519: ("Ostariophysi", "carps and catfish"),
+    186626: ("Otophysi", "carps and catfish"),
+    186627: ("Cypriniphysae", "carps and loaches"),
+    1329799: ("Archelosauria", "turtles, birds and crocodiles"),
+    8492: ("Archosauria", "birds and crocodiles"),
+    436489: ("Saurischia", "dinosaurs, birds today"),
+    436491: ("Theropoda", "dinosaurs, birds today"),
+    436492: ("Coelurosauria", "dinosaurs, birds today"),
+    8825: ("Neognathae", "most modern birds"),
+    3078114: ("Neoaves", "most modern birds"),
+    3073809: ("Australaves", "parrots and songbirds"),
+    1329950: ("Unidentata", "lizards and snakes"),
+    1329912: ("Episquamata", "lizards and snakes"),
+    32525: ("Theria", "live-bearing mammals"),
+    1437010: ("Boreoeutheria", "most placental mammals"),
+    314146: ("Euarchontoglires", "primates and rodents"),
+    314145: ("Laurasiatheria", "carnivores, bats and ungulates"),
+    376913: ("Haplorrhini", "monkeys, apes and tarsiers"),
+    314293: ("Simiiformes", "monkeys and apes"),
+    9526: ("Catarrhini", "Old World monkeys and apes"),
+    207598: ("Homininae", "great apes and humans"),
+    9845: ("Ruminantia", "ruminants"),
+    35500: ("Pecora", "deer, cattle and kin"),
+    9895: ("Bovidae", "cattle, sheep and antelope"),
+    451864: ("Dikarya", "higher fungi"),
+    716545: ("saccharomyceta", "yeasts and sac fungi"),
+    716546: ("leotiomyceta", "filamentous sac fungi"),
+    715989: ("sordariomyceta", "flask fungi and kin"),
+    1520881: ("OSLEUM clade", "filamentous sac fungi"),
+    147550: ("Sordariomycetes", "flask fungi"),
+    222544: ("Sordariomycetidae", "flask fungi"),
+    5139: ("Sordariales", "flask fungi"),
+    222543: ("Hypocreomycetidae", "mould-forming sac fungi"),
+    5125: ("Hypocreales", "moulds and insect fungi"),
+    110618: ("Nectriaceae", "Fusarium and relatives"),
+    474943: ("Cordycipitaceae", "insect-killing fungi"),
+    1028384: ("Glomerellales", "anthracnose fungi"),
+    681950: ("Glomerellaceae", "anthracnose fungi"),
+    5455: ("Colletotrichum", "anthracnose fungi"),
+    639021: ("Magnaporthales", "rice blast fungi"),
+    2528436: ("Pyriculariaceae", "rice blast fungi"),
+    48558: ("Pyricularia", "rice blast fungi"),
+    715962: ("dothideomyceta", "sooty moulds and kin"),
+    147541: ("Dothideomycetes", "sooty moulds and leaf fungi"),
+    451867: ("Dothideomycetidae", "sooty moulds"),
+    451868: ("Pleosporomycetidae", "leaf-spot fungi"),
+    92860: ("Pleosporales", "leaf-spot fungi"),
+    715340: ("Pleosporineae", "leaf-spot fungi"),
+    28556: ("Pleosporaceae", "leaf-spot fungi"),
+    451869: ("Botryosphaeriales", "canker fungi"),
+    45131: ("Botryosphaeriaceae", "canker fungi"),
+    35724: ("Macrophomina", "charcoal rot fungi"),
+    147545: ("Eurotiomycetes", "moulds and relatives"),
+    451871: ("Eurotiomycetidae", "moulds and relatives"),
+    1131492: ("Aspergillaceae", "Aspergillus and Penicillium"),
+    33183: ("Onygenales", "skin and hair fungi"),
+    147548: ("Leotiomycetes", "cup fungi and moulds"),
+    4891: ("Saccharomycetes", "budding yeasts"),
+    4892: ("Saccharomycetales", "budding yeasts"),
+    4893: ("Saccharomycetaceae", "baker's yeast family"),
+    4930: ("Saccharomyces", "baker's yeasts"),
+    3239874: ("Pichiomycetes", "budding yeasts"),
+    3243775: ("Pichiales", "budding yeasts"),
+    1156497: ("Pichiaceae", "budding yeasts"),
+    3239873: ("Dipodascomycetes", "budding yeasts"),
+    3243772: ("Dipodascales", "budding yeasts"),
+    766764: ("Debaryomycetaceae", "yeasts"),
+    27319: ("Metschnikowiaceae", "yeasts"),
+    5302: ("Agaricomycotina", "mushroom-forming fungi"),
+    155619: ("Agaricomycetes", "mushrooms and bracket fungi"),
+    452333: ("Agaricomycetidae", "mushroom-forming fungi"),
+    68889: ("Boletales", "boletes"),
+    155616: ("Tremellomycetes", "jelly fungi"),
+    4762: ("Oomycota", "water moulds"),
+    3418804: ("Peronosporomycetes", "water moulds"),
+    35493: ("Streptophyta", "land plants and their algae"),
+    131221: ("Streptophytina", "land plants and stoneworts"),
+    78536: ("Euphyllophyta", "ferns and seed plants"),
+    1437183: ("Mesangiospermae", "core flowering plants"),
+    1437197: ("Petrosaviidae", "most monocot plants"),
+    4734: ("commelinids", "grasses, palms and kin"),
+    38820: ("Poales", "grasses and sedges"),
+    147368: ("Pooideae", "temperate grasses"),
+    359160: ("BOP clade", "bamboo, rice and wheat grasses"),
+    1648038: ("Triticodae", "wheat and barley grasses"),
+    91827: ("Gunneridae", "core eudicot plants"),
+    1437201: ("Pentapetalae", "core eudicot plants"),
+    71275: ("rosids", "rose-related plants"),
+    91835: ("fabids", "legume-related plants"),
+    91836: ("malvids", "mallow-related plants"),
+    71274: ("asterids", "daisy-related plants"),
+    91888: ("lamiids", "mint-related plants"),
+    72025: ("Fabales", "legumes and kin"),
+    3814: ("Papilionoideae", "pea-flowered legumes"),
+    2231393: ("50 kb inversion clade", "legumes"),
+    3699: ("Brassicales", "cabbages and mustards"),
+    980083: ("Camelineae", "thale cress and kin"),
+    3701: ("Arabidopsis", "thale cresses"),
+    3744: ("Rosales", "roses, figs and kin"),
+    3524: ("Caryophyllales", "cacti, beets and kin"),
+    3646: ("Malpighiales", "willows and spurges"),
+    4069: ("Solanales", "nightshades and kin"),
+    4143: ("Lamiales", "mints and kin"),
+}
+
+
+def dump_rows(archive, name):
+    with archive.extractfile(name) as stream:
+        for line in stream:
+            yield [part.strip() for part in line.decode("utf-8").split("|")]
+
+
+def build(taxdump, database, output):
+    with sqlite3.connect(f"{Path(database).resolve().as_uri()}?mode=ro", uri=True) as conn:
+        known = dict(conn.execute("SELECT taxid, name FROM taxa"))
+    wrong = {t: (want, known.get(t)) for t, (want, _) in CURATED.items() if known.get(t) != want}
+    if wrong:
+        raise ValueError(f"Curated taxids do not match the snapshot: {wrong}")
+
+    names, ranked = {}, {}
+    with tarfile.open(taxdump, "r:gz") as archive:
+        for row in dump_rows(archive, "names.dmp"):
+            taxid = int(row[0])
+            if taxid not in known or row[3] not in NAME_CLASSES:
+                continue
+            rank = NAME_CLASSES.index(row[3])
+            if taxid not in ranked or rank < ranked[taxid]:
+                names[taxid], ranked[taxid] = row[1], rank
+    sources = Counter(ncbi=len(names))
+    for taxid, (_, english) in CURATED.items():
+        sources["curated_override" if taxid in names else "curated"] += 1
+        names[taxid] = english
+    # A gloss that only repeats the scientific name teaches nothing (Fungi ->
+    # "fungi"), and the interface prints the scientific name anyway.
+    redundant = [t for t, english in names.items() if english.casefold() == known[t].casefold()]
+    for taxid in redundant:
+        del names[taxid]
+    payload = {"created_at": datetime.now(timezone.utc).isoformat(),
+               "sources": {"ncbi_taxonomy": "https://ftp.ncbi.nlm.nih.gov/pub/taxonomy/taxdump.tar.gz",
+                           "name_classes": list(NAME_CLASSES),
+                           "curated": "refresh_common_names.py, plain-language glosses for unnamed clades"},
+               "counts": dict(sources, redundant_dropped=len(redundant), total=len(names)),
+               "names": {str(t): names[t] for t in sorted(names)}}
+    Path(output).write_text(json.dumps(payload, indent=1, sort_keys=False))
+    print(json.dumps(payload["counts"], indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--taxdump", type=Path, default=ROOT / ".cache/coverage/taxdump.tar.gz")
+    parser.add_argument("--database", type=Path, default=ROOT / "data/taxonomy.sqlite")
+    parser.add_argument("--output", type=Path, default=ROOT / "data/common_names.json")
+    args = parser.parse_args()
+    build(args.taxdump, args.database, args.output)
+
+
+if __name__ == "__main__":
+    main()

taxonomy.py

@@ -9,15 +9,17 @@ import gradio as gr
 
 ROOT = Path(__file__).resolve().parent
 DATABASE = ROOT / "data/taxonomy.sqlite"
+COMMON_NAMES = ROOT / "data/common_names.json"
 EUKARYOTA = 2759
 EUK_TREE = """WITH RECURSIVE euk(taxid) AS (
     SELECT 2759 UNION ALL
     SELECT t.taxid FROM taxa t JOIN euk e ON t.parent_id=e.taxid
     WHERE t.taxid != t.parent_id
 ) """
-DISPLAY_NAMES = {2759: "Eukaryotes", 33208: "Animals", 33090: "Green plants",
-                 4751: "Fungi", 33154: "Animals + fungi", 2698737: "SAR lineages",
-                 2763: "Red algae", 3041: "Green algae"}
+# Scientific names stay the primary label; English glosses are a secondary line.
+# See refresh_common_names.py for how the lookup is built.
+MAX_ENGLISH = 30
+MAX_LABEL = 24
 
 
 COLUMN_LIMIT = 6
@@ -31,8 +33,13 @@ def encode_path(steps):
 
 
 class Taxonomy:
-    def __init__(self, path=DATABASE):
+    def __init__(self, path=DATABASE, common_names=COMMON_NAMES):
         self.path = Path(path)
+        self.english, self.english_sources = {}, {}
+        if Path(common_names).exists():
+            payload = json.loads(Path(common_names).read_text())
+            self.english = {int(t): name for t, name in payload["names"].items()}
+            self.english_sources = payload.get("sources", {})
         with closing(self.connect()) as conn:
             self.metadata = json.loads(conn.execute("SELECT value FROM metadata").fetchone()[0])
             self.eukaryote_ids = frozenset(r[0] for r in conn.execute(EUK_TREE + "SELECT taxid FROM euk"))
@@ -87,13 +94,13 @@ class Taxonomy:
                 return dict(conn.execute("SELECT * FROM taxa WHERE taxid=?", (t,)).fetchone())
 
             def node(row, offset=0, **extra):
-                return dict(taxid=row['taxid'], offset=offset, name=row['name'],
-                            label=DISPLAY_NAMES.get(row['taxid'], row['name']),
+                return dict(taxid=row['taxid'], offset=offset, name=row['name'], label=row['name'],
+                            english=self.english.get(row['taxid'], ""),
                             total=row['total_count'], covered=row.get('covered_total', 0), **extra)
 
             def remainder(rows, parent, start):
                 return dict(taxid=parent, offset=start, name=f"Other lineages · {len(rows):,} groups (display aggregate)",
-                            label=f"Other lineages ({len(rows):,})", total=sum(r['total_count'] for r in rows),
+                            label=f"Other lineages ({len(rows):,})", english="", total=sum(r['total_count'] for r in rows),
                             covered=sum(r.get('covered_total', 0) for r in rows), aggregate=True)
 
             def column(step, selected):
@@ -111,7 +118,7 @@ class Taxonomy:
                 row = taxon(parent)
                 if not offset and row['direct_count'] and rows:
                     nodes.append(dict(taxid=parent, offset=0, name="Assemblies assigned directly to this taxon",
-                                      label="Direct assignments", total=row['direct_count'],
+                                      label="Direct assignments", english="", total=row['direct_count'],
                                       covered=row.get('covered_direct', 0), direct=True))
                 return nodes
 
@@ -142,7 +149,7 @@ class Taxonomy:
 
         def stack(nodes):
             """Sankey layout: bar heights follow assembly counts, with room for every label."""
-            gap, slot = (12 if len(nodes) > 1 else 0), 36
+            gap, slot = (12 if len(nodes) > 1 else 0), 46
             fixed, scale = set(), 0
             for _ in range(len(nodes) + 1):
                 free = chart - gap * (len(nodes) - 1) - slot * len(fixed)
@@ -159,6 +166,9 @@ class Taxonomy:
                 n['y'] = y + (room - n['h']) / 2
                 y += room + gap
 
+        def clip(text, limit):
+            return text if len(text) <= limit else text[:limit - 2] + "…"
+
         def share(n):
             return n['covered'] / n['total'] if self.coverage and n['total'] else 0
 
@@ -198,8 +208,9 @@ class Taxonomy:
                 x, y, h = n['x'], n['y'], n['h']
                 f = share(n)
                 percent = 100 * f
-                detail = (f"{n['name']} · {n['covered']:,} of {n['total']:,} assemblies have published annotations ({percent:.2f}%). Includes partial assemblies."
-                          if self.coverage else f"{n['name']} · {n['total']:,} assemblies. Coverage inventory unavailable.")
+                title = f"{n['name']} ({n['english']})" if n['english'] else n['name']
+                detail = (f"{title} · {n['covered']:,} of {n['total']:,} assemblies have published annotations ({percent:.2f}%). Includes partial assemblies."
+                          if self.coverage else f"{title} · {n['total']:,} assemblies. Coverage inventory unavailable.")
                 if n.get('aggregate'):
                     detail += " Display aggregate, not a taxonomic clade. Activate to see its lineages."
                 elif not n.get('direct') and not n['selected']:
@@ -207,19 +218,24 @@ class Taxonomy:
                 action = "" if n.get('direct') else f'data-path="{n["path"]}" role="button" tabindex="0"'
                 classes = "tree-node" + (" is-selected" if n['selected'] else " is-sibling" if on_path else "") + \
                     (" is-direct" if n.get('direct') else "")
-                nodes.append(f'<g class="{classes}" {action} aria-label="{escape(detail, quote=True)}" data-detail="{escape(detail, quote=True)}"><title>{escape(detail)}</title>')
+                nodes.append(f'<g class="{classes}" {action} aria-label="{escape(detail, quote=True)}" data-detail="{escape(detail, quote=True)}">')
                 cy = y + h / 2
-                nodes.append(f'<rect x="{x - 6}" y="{min(y, cy - 18):.1f}" width="{spacing - 40}" height="{max(h, 36):.1f}" rx="10" class="tree-hit"/>')
+                nodes.append(f'<rect x="{x - 6}" y="{min(y, cy - 23):.1f}" width="{spacing - 40}" height="{max(h, 46):.1f}" rx="10" class="tree-hit"/>')
                 green = h * f
                 if green > 0:
                     nodes.append(f'<rect x="{x}" y="{y:.1f}" width="{bar}" height="{green:.1f}" class="bar bar-annotated"/>')
                 if green < h:
                     nodes.append(f'<rect x="{x}" y="{y + green:.1f}" width="{bar}" height="{h - green:.1f}" class="bar bar-missing"/>')
                 nodes.append(f'<rect x="{x}" y="{y:.1f}" width="{bar}" height="{h:.1f}" class="bar-outline"/>')
-                label = n['label'] if len(n['label']) <= 24 else n['label'][:22] + "…"
+                label, english = clip(n['label'], MAX_LABEL), clip(n['english'], MAX_ENGLISH)
                 stats = f"{percent:.1f}% · {n['covered']:,} / {n['total']:,}" if self.coverage else f"{n['total']:,} assemblies"
-                nodes.append(f'<text x="{x + bar + 8}" y="{cy - 3:.1f}" class="tree-label">{escape(label)}</text>'
-                             f'<text x="{x + bar + 8}" y="{cy + 13:.1f}" class="tree-count">{stats}</text></g>')
+                text_x = x + bar + 8
+                # Three lines when there is an English gloss, two without, both centred on the bar.
+                head, stat_line = (cy - 10, cy + 16) if english else (cy - 3, cy + 13)
+                nodes.append(f'<text x="{text_x}" y="{head:.1f}" class="tree-label">{escape(label)}</text>')
+                if english:
+                    nodes.append(f'<text x="{text_x}" y="{cy + 3:.1f}" class="tree-english">{escape(english)}</text>')
+                nodes.append(f'<text x="{text_x}" y="{stat_line:.1f}" class="tree-count">{stats}</text></g>')
         svg = (f'<svg viewBox="0 0 {width} {height}" class="life-tree" data-route="{encode_path(steps)}" style="min-width:{width if width > 1040 else 760}px" '
                f'aria-label="Eukaryotic taxonomy and annotation coverage">' + ''.join(flows) + ''.join(nodes) + '</svg>')
 
@@ -227,9 +243,11 @@ class Taxonomy:
         total, covered = focus['total'], focus['covered']
         percent = 100 * covered / total if self.coverage and total else 0
         selected_name = f"Other lineages of {lineage[-1]['name']}" if focus.get('aggregate') else focus['label']
+        if focus.get('english'):
+            selected_name += f" · {focus['english']}"
         crumbs = []
         for depth, (row, (_, offset)) in enumerate(zip(lineage, steps)):
-            name = "Other lineages" if offset else DISPLAY_NAMES.get(row['taxid'], row['name'])
+            name = "Other lineages" if offset else row['name']
             crumbs.append(f'<button data-path="{encode_path(steps[:depth + 1])}">{escape(name)}</button>')
         breadcrumbs = ' <span class="crumb-divider">/</span> '.join(crumbs)
         parent = encode_path(steps[:-1] or steps)
@@ -307,11 +325,15 @@ def build_taxonomy_tab():
                     "Each expanded group adds a column on the right with up to six direct lineages plus any remainder, so every ancestor stays visible. "
                     "The opening view also expands the animal/fungal branch. Bars and flows are drawn like a Sankey diagram: "
                     "heights follow **actual assembly counts** within each column, split into annotated and not-annotated assemblies.\n\n"
+                    "Each group shows its scientific name with a plain-English name underneath where one is available. These come from "
+                    "NCBI Taxonomy's common names plus a curated set of short glosses for the large unranked clades NCBI leaves unnamed, "
+                    "such as Opisthokonta (animals and fungi) or Ecdysozoa (moulting animals). The glosses describe the living members of a "
+                    "clade in everyday words; they are not formal taxonomic synonyms, so the scientific name stays the primary label.\n\n"
                     "Coverage means the fraction of current GenBank assembly versions with published annotations, including partial assemblies. "
                     "It does not measure the fraction of bases annotated. Parent counts include descendants once each. "
                     "Exact accession versions are matched. The Database tab searches a dated snapshot of all published annotation files.\n\n"
                     "Sources: [NCBI assembly summary](https://ftp.ncbi.nlm.nih.gov/genomes/ASSEMBLY_REPORTS/assembly_summary_genbank.txt), "
-                    "[NCBI Taxonomy](https://ftp.ncbi.nlm.nih.gov/pub/taxonomy/taxdump.tar.gz), "
+                    "[NCBI Taxonomy](https://ftp.ncbi.nlm.nih.gov/pub/taxonomy/taxdump.tar.gz) for both the tree and its common names, "
                     "and [published annotations](https://huggingface.co/buckets/HuggingFaceBio/genbank-annotations).")
         coverage = taxonomy.coverage or {}
         gr.JSON({"taxonomy_updated": taxonomy.metadata['created_at'], "coverage_updated": coverage.get('created_at'),

tests/test_taxonomy.py

@@ -1,7 +1,10 @@
+import json
 import re
+import sqlite3
 import unittest
 
-from taxonomy import DATABASE, DEFAULT_PATH, Taxonomy
+from refresh_common_names import CURATED
+from taxonomy import COMMON_NAMES, DATABASE, DEFAULT_PATH, MAX_ENGLISH, Taxonomy
 
 
 @unittest.skipUnless(DATABASE.exists(), "taxonomy snapshot unavailable")
@@ -30,6 +33,37 @@ class TaxonomyTests(unittest.TestCase):
         html = self.taxonomy.view("2759/2759~6")
         self.assertIn('data-path="2759/2759~6/2759~12"', html)
 
+    def test_english_names_label_latin_clades(self):
+        html = self.taxonomy.view("2759/33154/33208")
+        for scientific, english in (("Opisthokonta", "animals and fungi"), ("Metazoa", "animals"),
+                                    ("Eumetazoa", "animals with true tissues"), ("Porifera", "sponges")):
+            self.assertIn(f'class="tree-label">{scientific}</text>', html)
+            self.assertIn(f'class="tree-english">{english}</text>', html)
+        # A gloss that only repeats the scientific name is dropped by the build.
+        self.assertIn('class="tree-label">Fungi</text>', html)
+        self.assertNotIn('class="tree-english">fungi</text>', html)
+
+    def test_one_tooltip_per_node(self):
+        html = self.taxonomy.view(DEFAULT_PATH)
+        # <title> would render the browser's own tooltip on top of the styled one.
+        self.assertNotIn("<title>", html)
+        self.assertIn('data-detail="Viridiplantae (green plants) ·', html)
+        self.assertEqual(html.count("data-detail="), html.count('class="tree-hit"'))
+
+    def test_curated_glosses_match_the_snapshot(self):
+        with sqlite3.connect(f"{DATABASE.resolve().as_uri()}?mode=ro", uri=True) as conn:
+            for taxid, (scientific, english) in CURATED.items():
+                row = conn.execute("SELECT name FROM taxa WHERE taxid=?", (taxid,)).fetchone()
+                self.assertIsNotNone(row, f"taxid {taxid} is not in the snapshot")
+                self.assertEqual(row[0], scientific, f"taxid {taxid}")
+                self.assertLessEqual(len(english), MAX_ENGLISH, f"taxid {taxid} gloss is clipped in the chart")
+
+    def test_published_names_cover_the_curated_table(self):
+        names = json.loads(COMMON_NAMES.read_text())["names"]
+        redundant = {t for t, (scientific, english) in CURATED.items() if scientific.casefold() == english.casefold()}
+        self.assertEqual({int(t) for t in names} & set(CURATED), set(CURATED) - redundant)
+        self.assertEqual(names["6040"], "sponges")  # straight from NCBI Taxonomy
+
     def test_rejects_paths_outside_the_tree(self):
         for path in ("1", "33208", "2759/33208", "2759/2759~3", "2759/9606", "abc"):
             with self.assertRaises(ValueError, msg=path):