Add GenBank assembly taxonomy tab and refreshable SQLite snapshot

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+data/taxonomy.sqlite filter=lfs diff=lfs merge=lfs -text

FEATURE_BACKLOG.md

@@ -9,7 +9,7 @@ Last updated: 2026-09-30.
 | ID | Feature | Status |
 | --- | --- | --- |
 | F001 | GenBank inference coverage map | Planned; not implemented |
-| F002 | Taxonomy map and navigation | Planned; not implemented |
+| F002 | Taxonomy map and navigation | GenBank assembly taxonomy implemented; annotation links and coverage pending |
 | F003 | Comparison with RefSeq annotations | Planned; not implemented |
 | F004 | Download annotations by accession, individually or in bulk | Partial; individual indexed segment downloads exist |
 | F005 | Fast accession lookup and retrieval across the full dataset | Prototype implemented for three remote objects; full coverage pending |
@@ -36,6 +36,8 @@ Decisions and dependencies for implementation:
 
 ## F002 — Taxonomy map and navigation
 
+Current implementation: the first tab shows an NCBI taxonomy sunburst sized by current GenBank assembly counts. It supports branch expansion, child/parent navigation, and scientific-name/taxon-ID search. A separate SQLite snapshot stores aggregated counts and provenance; `python refresh_taxonomy.py --download` refreshes it. See [refresh instructions](README.md#refresh-the-taxonomy-snapshot). The chart includes all assembly groups; it does not show inference coverage. Linking taxa to annotation accessions and coverage coloring remain future work. F001 is deferred for now.
+
 **Goal:** Provide a taxonomy-based view of the available genomes and annotations.
 
 Desired behavior:
@@ -47,9 +49,8 @@ Desired behavior:
 
 Decisions and dependencies for implementation:
 
-- Choose a visualization, such as an expandable tree, treemap, or sunburst; no format is selected yet.
-- Choose and version a taxonomy source, and resolve assembly taxon IDs to lineages.
-- Define how to represent missing, unresolved, or changed taxon IDs.
+- Implemented: sunburst with bounded subtrees and exact “Other taxa” counts; NCBI taxonomy with source checksums and dates; merged IDs resolved and unresolved IDs explicitly counted.
+- Remaining: connect the taxonomy inventory to inference coverage and accession-level annotation results.
 
 ## F003 — Comparison with RefSeq annotations
 

README.md

@@ -15,6 +15,24 @@ Search an indexed subset of [HuggingFaceBio/genbank-annotations](https://hugging
 
 Future features and open design decisions are tracked in the [feature backlog](FEATURE_BACKLOG.md).
 
+## GenBank taxonomy
+
+The first tab shows an interactive sunburst of **GenBank genome assemblies**, using NCBI's current GenBank assembly summary and taxonomy. Sector area represents assembly count. The second tab provides annotation lookup over the existing small index.
+
+The taxonomy includes all taxonomic groups and assembly levels in the current summary, accepting `GCA_` accessions with `version_status=latest`. Each assembly contributes once to its taxon and each ancestor. Merged taxon IDs are resolved; unresolved IDs are counted in a separate root branch. These counts describe genome assemblies, not all GenBank nucleotide records or annotation coverage.
+
+Click sectors to expand the loaded chart. Use the child-group menu or scientific-name/taxon-ID search to load another subtree, and the parent/home buttons to return. Each chart loads three descendant levels and the eight largest children per node; smaller children are combined into an accurately counted “Other taxa” sector. Search can reach those taxa individually. Hover percentages refer to the selected group; the group heading also shows its share of the full snapshot.
+
+### Refresh the taxonomy snapshot
+
+```bash
+python refresh_taxonomy.py --download
+```
+
+This downloads roughly 2 GB of **metadata only** to `.cache/coverage/`, then atomically rebuilds `data/taxonomy.sqlite`. To rebuild from already downloaded metadata, omit `--download`. No sequence or probability data is downloaded. The builder uses the Python standard library. The SQLite file contains taxon relationships, names, counts, and source URLs/checksums/dates; it is independent of `data/catalog.sqlite`.
+
+Upload the new `data/taxonomy.sqlite` to the Space and restart/redeploy to activate it. The app reads the bundled snapshot and does not download NCBI metadata at startup. Refreshes are manual; the displayed date is the snapshot build date. Annotation coverage coloring and accession navigation from taxonomy remain in the backlog.
+
 ## Run locally
 
 ```bash
@@ -30,7 +48,7 @@ Open http://localhost:7860. Remote reads require a Hugging Face login (`hf auth
 
 The preview Space is [HuggingFaceBio/genbank-annotation-explorer](https://huggingface.co/spaces/HuggingFaceBio/genbank-annotation-explorer), with private visibility.
 
-To deploy or update it, upload this directory, including `data/catalog.sqlite`. Set `HF_TOKEN` as a Space secret with read access to the bucket. Include `data/sample.parquet` and `data/manifest.json` if offline sample mode is desired. Credentials stay on the server and must never be committed. The README metadata configures the runtime, following the [Gradio Spaces documentation](https://huggingface.co/docs/hub/spaces-sdks-gradio). Keep the Space private for the initial preview.
+To deploy or update it, upload the app code and documentation, including `data/catalog.sqlite` and `data/taxonomy.sqlite`; exclude `.cache/` and local environments. Set `HF_TOKEN` as a Space secret with read access to the bucket. Include `data/sample.parquet` and `data/manifest.json` if offline sample mode is desired. Credentials stay on the server and must never be committed. The README metadata configures the runtime, following the [Gradio Spaces documentation](https://huggingface.co/docs/hub/spaces-sdks-gradio). Keep the Space private for the initial preview.
 
 ## Remote prototype scope
 

app.py

@@ -13,6 +13,7 @@ import gradio as gr
 import pyarrow.parquet as pq
 import plotly.graph_objects as go
 
+from taxonomy import build_taxonomy_tab
 from catalog import Catalog
 from remote_catalog import RemoteCatalog, RemoteReadError
 
@@ -119,43 +120,47 @@ def build_app(catalog=None):
 
     with gr.Blocks(title="GenBank Annotation Explorer", delete_cache=(3600, 3600)) as demo:
         gr.Markdown("# GenBank Annotation Explorer\nExplore predicted coding regions by **assembly or contig accession**.")
-        gr.Markdown(f"**Prototype {scope} · {len(catalog.records):,} segments · "
-                    f"{len(catalog.manifest['assemblies']):,} assemblies · {catalog.manifest['bases']:,} bases**\n\n"
-                    "Source: [HuggingFaceBio/genbank-annotations](https://huggingface.co/buckets/HuggingFaceBio/genbank-annotations). "
-                    f"These are model-predicted CDS probabilities, not curated gene features. Search covers the {scope} only. "
-                    + (f"Annotations load on demand from **{len(catalog.manifest['sources'])} bucket files**. "
-                       f"Index updated {catalog.manifest['created_at'][:10]}." if remote_mode else ""))
-        with gr.Row():
-            accession = gr.Textbox(label="Accession ID", placeholder="Assembly (GCA_…) or contig accession", scale=5)
-            search_button = gr.Button("Find annotations", variant="primary", scale=1)
-        examples = [first["assembly_accession"], first["record_name"]]
-        if remote_mode:
-            with closing(catalog.connect()) as conn:
-                examples += [r[0] for r in conn.execute("SELECT record_name FROM segments WHERE id IN (SELECT min(id) FROM segments GROUP BY object_path)")]
-            examples += ["JBPJTW010000350.1"]
-        gr.Examples(examples=[[e] for e in dict.fromkeys(examples)], inputs=accession)
-        status = gr.Markdown("Enter an accession or select an example. IDs are case-insensitive; version suffixes are optional.")
-        results = gr.Dataframe(value=catalog.table([]), interactive=False, label="Matching segments")
-        segment = gr.Dropdown(choices=[], label="Segment to explore", interactive=True)
-        with gr.Row():
-            start = gr.Number(label="Start (0-based, inclusive)", precision=0)
-            end = gr.Number(label="End (exclusive)", precision=0)
-            view = gr.Button("Update region")
-        with gr.Row():
-            mode = gr.Radio(["Probabilities", "Binary labels"], value="Probabilities", label="Viewer mode")
-            threshold = gr.Slider(0, 1, value=0.5, step=0.01, label="CDS threshold (max strand P > threshold)")
-        plot = gr.Plot(label="CDS tracks")
-        note = gr.Markdown("Choose a segment to see its probability tracks.")
-        with gr.Accordion("Segment metadata and provenance", open=False):
-            metadata = gr.JSON(label="Source metadata")
-        with gr.Row():
-            download = gr.Button("Prepare segment download")
-            file = gr.File(label="Original segment annotations (Parquet)", interactive=False)
-        with gr.Accordion("Browse indexed accessions and coverage", open=False):
-            gr.Markdown(f"Showing the first {len(all_ids):,} indexed segments. Search an accession to find other indexed records. "
-                        "An indexed file does not imply complete coverage of its assembly.")
-            gr.Dataframe(value=catalog.table(all_ids), interactive=False)
-            gr.JSON(value=catalog.manifest, label="Index provenance" if remote_mode else "Sample provenance")
+        with gr.Tabs():
+            with gr.Tab("GenBank taxonomy"):
+                build_taxonomy_tab()
+            with gr.Tab("Annotation lookup"):
+                gr.Markdown(f"**Prototype {scope} · {len(catalog.records):,} segments · "
+                            f"{len(catalog.manifest['assemblies']):,} assemblies · {catalog.manifest['bases']:,} bases**\n\n"
+                            "Source: [HuggingFaceBio/genbank-annotations](https://huggingface.co/buckets/HuggingFaceBio/genbank-annotations). "
+                            f"These are model-predicted CDS probabilities, not curated gene features. Search covers the {scope} only. "
+                            + (f"Annotations load on demand from **{len(catalog.manifest['sources'])} bucket files**. "
+                               f"Index updated {catalog.manifest['created_at'][:10]}." if remote_mode else ""))
+                with gr.Row():
+                    accession = gr.Textbox(label="Accession ID", placeholder="Assembly (GCA_…) or contig accession", scale=5)
+                    search_button = gr.Button("Find annotations", variant="primary", scale=1)
+                examples = [first["assembly_accession"], first["record_name"]]
+                if remote_mode:
+                    with closing(catalog.connect()) as conn:
+                        examples += [r[0] for r in conn.execute("SELECT record_name FROM segments WHERE id IN (SELECT min(id) FROM segments GROUP BY object_path)")]
+                    examples += ["JBPJTW010000350.1"]
+                gr.Examples(examples=[[e] for e in dict.fromkeys(examples)], inputs=accession)
+                status = gr.Markdown("Enter an accession or select an example. IDs are case-insensitive; version suffixes are optional.")
+                results = gr.Dataframe(value=catalog.table([]), interactive=False, label="Matching segments")
+                segment = gr.Dropdown(choices=[], label="Segment to explore", interactive=True)
+                with gr.Row():
+                    start = gr.Number(label="Start (0-based, inclusive)", precision=0)
+                    end = gr.Number(label="End (exclusive)", precision=0)
+                    view = gr.Button("Update region")
+                with gr.Row():
+                    mode = gr.Radio(["Probabilities", "Binary labels"], value="Probabilities", label="Viewer mode")
+                    threshold = gr.Slider(0, 1, value=0.5, step=0.01, label="CDS threshold (max strand P > threshold)")
+                plot = gr.Plot(label="CDS tracks")
+                note = gr.Markdown("Choose a segment to see its probability tracks.")
+                with gr.Accordion("Segment metadata and provenance", open=False):
+                    metadata = gr.JSON(label="Source metadata")
+                with gr.Row():
+                    download = gr.Button("Prepare segment download")
+                    file = gr.File(label="Original segment annotations (Parquet)", interactive=False)
+                with gr.Accordion("Browse indexed accessions and coverage", open=False):
+                    gr.Markdown(f"Showing the first {len(all_ids):,} indexed segments. Search an accession to find other indexed records. "
+                                "An indexed file does not imply complete coverage of its assembly.")
+                    gr.Dataframe(value=catalog.table(all_ids), interactive=False)
+                    gr.JSON(value=catalog.manifest, label="Index provenance" if remote_mode else "Sample provenance")
         outputs = [status, results, segment, file]
         for event in (search_button.click, accession.submit):
             event(search, accession, outputs).then(select_segment, [segment, mode, threshold], [metadata, start, end, plot, note, file])

data/taxonomy.sqlite

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:69388d96ee05e254b8eb8530a62a71d3d9e4f89e397427c1b7f99c140d488b55
+size 24084480

refresh_taxonomy.py

@@ -0,0 +1,129 @@
+"""Build a small, atomic SQLite taxonomy snapshot from NCBI metadata."""
+import argparse
+from collections import Counter
+from datetime import datetime, timezone
+import hashlib
+import json
+from pathlib import Path
+import sqlite3
+import tarfile
+import urllib.request
+
+ROOT = Path(__file__).resolve().parent
+SOURCES = {
+    "assembly_summary_genbank.txt": "https://ftp.ncbi.nlm.nih.gov/genomes/ASSEMBLY_REPORTS/assembly_summary_genbank.txt",
+    "taxdump.tar.gz": "https://ftp.ncbi.nlm.nih.gov/pub/taxonomy/taxdump.tar.gz",
+}
+
+
+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(summary, taxdump, output):
+    counts = Counter()
+    skipped = 0
+    with open(summary) as stream:
+        for line in stream:
+            if line.startswith("##"):
+                continue
+            if line.startswith("#"):
+                header = line.lstrip("# ").rstrip("\n").split("\t")
+                columns = {name: header.index(name) for name in ("assembly_accession", "taxid", "version_status")}
+                continue
+            row = line.rstrip("\n").split("\t")
+            if not row[columns["assembly_accession"]].startswith("GCA_") or row[columns["version_status"]] != "latest":
+                skipped += 1
+                continue
+            try:
+                taxid = int(row[columns["taxid"]])
+            except ValueError:
+                taxid = -1
+            counts[taxid] += 1
+    print(f"Read {sum(counts.values()):,} current assemblies", flush=True)
+    parents, ranks, merged = {}, {}, {}
+    with tarfile.open(taxdump, "r:gz") as archive:
+        for row in dump_rows(archive, "nodes.dmp"):
+            taxid = int(row[0])
+            parents[taxid], ranks[taxid] = int(row[1]), row[2]
+        for row in dump_rows(archive, "merged.dmp"):
+            merged[int(row[0])] = int(row[1])
+        direct = Counter()
+        for taxid, count in counts.items():
+            seen = set()
+            while taxid in merged and taxid not in seen:
+                seen.add(taxid)
+                taxid = merged[taxid]
+            direct[taxid if taxid in parents else -1] += count
+        parents[-1], ranks[-1] = 1, "unresolved"
+        totals = Counter()
+        for taxid, count in direct.items():
+            seen = set()
+            while True:
+                if taxid in seen:
+                    raise ValueError("Taxonomy cycle detected")
+                seen.add(taxid)
+                totals[taxid] += count
+                if taxid == 1:
+                    break
+                taxid = parents[taxid]
+        names = {-1: "Unresolved taxonomy", 1: "GenBank genome assemblies"}
+        for row in dump_rows(archive, "names.dmp"):
+            taxid = int(row[0])
+            if taxid in totals and taxid != 1 and row[3] == "scientific name":
+                names[taxid] = row[1]
+    if not totals[1] or totals[1] != sum(counts.values()):
+        raise ValueError("Invalid root assembly count")
+    provenance = {}
+    for path in (summary, taxdump):
+        digest = hashlib.sha256()
+        with open(path, "rb") as stream:
+            for chunk in iter(lambda: stream.read(8 * 1024 * 1024), b""):
+                digest.update(chunk)
+        source = {"url": SOURCES[path.name], "sha256": digest.hexdigest(), "bytes": path.stat().st_size}
+        sidecar = path.with_suffix(path.suffix + ".source.json")
+        if sidecar.exists():
+            source.update(json.loads(sidecar.read_text()))
+        provenance[path.name] = source
+    metadata = {"created_at": datetime.now(timezone.utc).isoformat(), "sources": provenance,
+                "assembly_count": totals[1], "unresolved_assemblies": direct[-1],
+                "taxa_with_assemblies": len(totals), "skipped_rows": skipped,
+                "scope": "Current GCA assemblies in NCBI assembly_summary_genbank.txt; version_status=latest. Counts include all assembly levels and taxonomic groups. Not all GenBank nucleotide records."}
+    output.parent.mkdir(parents=True, exist_ok=True)
+    temporary = output.with_suffix(".sqlite.tmp")
+    temporary.unlink(missing_ok=True)
+    try:
+        with sqlite3.connect(temporary) as conn:
+            conn.executescript("CREATE TABLE taxa (taxid INTEGER PRIMARY KEY, parent_id INTEGER, name TEXT, rank TEXT, direct_count INTEGER, total_count INTEGER); CREATE INDEX parents ON taxa(parent_id, total_count DESC); CREATE TABLE metadata (value TEXT);")
+            conn.executemany("INSERT INTO taxa VALUES (?,?,?,?,?,?)", ((t, parents[t], names.get(t, str(t)), ranks[t], direct[t], n) for t, n in totals.items()))
+            conn.execute("INSERT INTO metadata VALUES (?)", (json.dumps(metadata),))
+        temporary.replace(output)
+    finally:
+        temporary.unlink(missing_ok=True)
+    print(json.dumps(metadata, indent=2), flush=True)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--cache-dir", type=Path, default=ROOT / ".cache/coverage")
+    parser.add_argument("--output", type=Path, default=ROOT / "data/taxonomy.sqlite")
+    parser.add_argument("--download", action="store_true", help="Download fresh NCBI metadata before rebuilding (about 2 GB).")
+    args = parser.parse_args()
+    args.cache_dir.mkdir(parents=True, exist_ok=True)
+    if args.download:
+        for filename, url in SOURCES.items():
+            target = args.cache_dir / filename
+            temporary = target.with_suffix(target.suffix + ".part")
+            with urllib.request.urlopen(url, timeout=120) as response, open(temporary, "wb") as out:
+                source = {"downloaded_at": datetime.now(timezone.utc).isoformat(), "last_modified": response.headers.get("Last-Modified")}
+                while chunk := response.read(8 * 1024 * 1024):
+                    out.write(chunk)
+            temporary.replace(target)
+            target.with_suffix(target.suffix + ".source.json").write_text(json.dumps(source))
+    build(args.cache_dir / "assembly_summary_genbank.txt", args.cache_dir / "taxdump.tar.gz", args.output)
+
+
+if __name__ == "__main__":
+    main()

taxonomy.py

@@ -0,0 +1,126 @@
+"""Read-only taxonomy navigation, independent of the annotation lookup index."""
+from contextlib import closing
+import json
+from pathlib import Path
+import sqlite3
+
+import gradio as gr
+import plotly.graph_objects as go
+
+DATABASE = Path(__file__).resolve().parent / "data/taxonomy.sqlite"
+
+
+class Taxonomy:
+    def __init__(self, path=DATABASE):
+        self.path = Path(path)
+        with closing(self.connect()) as conn:
+            self.metadata = json.loads(conn.execute("SELECT value FROM metadata").fetchone()[0])
+
+    def connect(self):
+        conn = sqlite3.connect(f"{self.path.resolve().as_uri()}?mode=ro", uri=True)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def search(self, query):
+        query = str(query or "").strip()
+        with closing(self.connect()) as conn:
+            if query.lstrip("-").isdigit():
+                rows = conn.execute("SELECT * FROM taxa WHERE taxid=?", (int(query),)).fetchall()
+            else:
+                pattern = "%" + query.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_") + "%"
+                rows = conn.execute("SELECT * FROM taxa WHERE name LIKE ? ESCAPE '\\' ORDER BY total_count DESC LIMIT 100", (pattern,)).fetchall()
+        return [(f"{r['name']} · {r['total_count']:,} assemblies · taxid {r['taxid']}", str(r['taxid'])) for r in rows]
+
+    def view(self, taxid):
+        with closing(self.connect()) as conn:
+            root = conn.execute("SELECT * FROM taxa WHERE taxid=?", (int(taxid),)).fetchone()
+            if root is None:
+                raise ValueError("Taxon is absent from this assembly snapshot")
+            ids, labels, parents, values, details = [], [], [], [], []
+
+            def add(key, label, parent, count, rank):
+                ids.append(str(key)); labels.append(label); parents.append(str(parent))
+                values.append(count)
+                details.append([rank, count / root['total_count'] * 100])
+
+            def visit(row, parent="", depth=0):
+                key = row['taxid']
+                add(key, row['name'], parent, row['total_count'], row['rank'])
+                if depth >= 3:
+                    return
+                children = conn.execute("SELECT * FROM taxa WHERE parent_id=? AND taxid!=? ORDER BY total_count DESC", (key, key)).fetchall()
+                # At most 8 children per node; exact residual counts stay visible.
+                for child in children[:8]:
+                    visit(child, key, depth + 1)
+                other = sum(c['total_count'] for c in children[8:])
+                if other:
+                    add(f"other-{key}", f"Other taxa ({len(children) - 8:,})", key, other, "Grouped for display; search to explore")
+                if row['direct_count'] and children:
+                    add(f"direct-{key}", "Assigned directly to this taxon", key, row['direct_count'], "direct assignments")
+
+            visit(root)
+            children = conn.execute("SELECT * FROM taxa WHERE parent_id=? AND taxid!=? ORDER BY total_count DESC LIMIT 200", (root['taxid'], root['taxid'])).fetchall()
+            lineage, current = [], root
+            while True:
+                lineage.append(current['name'])
+                if current['taxid'] == 1:
+                    break
+                current = conn.execute("SELECT * FROM taxa WHERE taxid=?", (current['parent_id'],)).fetchone()
+        figure = go.Figure(go.Sunburst(ids=ids, labels=labels, parents=parents, values=values,
+                                      branchvalues="total", customdata=details, sort=False,
+                                      hovertemplate="<b>%{label}</b><br>%{customdata[0]}<br>%{value:,} assemblies<br>%{customdata[1]:.2f}% of selected group<extra></extra>"))
+        figure.update_layout(height=620, margin=dict(t=10, b=10, l=10, r=10), template="plotly_white")
+        count = root['total_count']
+        note = f"### {root['name']}\n**{count:,} assemblies** · {count / self.metadata['assembly_count']:.2%} of this GenBank assembly snapshot\n\n" + " → ".join(reversed(lineage))
+        choices = [(f"{r['name']} · {r['total_count']:,}", str(r['taxid'])) for r in children]
+        return figure, note, choices, str(root['parent_id'])
+
+
+def build_taxonomy_tab():
+    if not DATABASE.exists():
+        gr.Markdown("Taxonomy snapshot unavailable. Run `python refresh_taxonomy.py --download` to create it.")
+        return
+    taxonomy = Taxonomy()
+    meta = taxonomy.metadata
+    gr.Markdown(f"## GenBank genome assemblies\n**{meta['assembly_count']:,} assemblies** · Snapshot built **{meta['created_at'][:10]}**\n\n"
+                "Explore the NCBI taxonomy by assembly count. This inventory covers current GenBank genome assemblies; "
+                "it does not count every nucleotide submission or indicate which genomes we have annotated.")
+    initial, initial_note, initial_choices, _ = taxonomy.view("1")
+    selected = gr.State("1")
+    parent = gr.State("1")
+    with gr.Row():
+        home = gr.Button("All GenBank assemblies")
+        up = gr.Button("Parent group")
+        child = gr.Dropdown(choices=initial_choices, label="Explore a child group (largest 200)", interactive=True)
+    with gr.Row():
+        query = gr.Textbox(label="Find a taxon", placeholder="Scientific name or NCBI taxon ID")
+        find = gr.Button("Search taxonomy")
+    matches = gr.Dropdown(choices=[], label="Taxon search results (up to 100, largest first)", interactive=True)
+    search_status = gr.Markdown()
+    note = gr.Markdown(initial_note)
+    chart = gr.Plot(value=initial, label="GenBank taxonomy")
+    gr.Markdown("Click chart sectors to expand the displayed branches; click the center to zoom out. "
+                "Use **Explore a child group** or **Find a taxon** to load deeper branches. "
+                "Each view includes three descendant levels and the eight largest children per node. "
+                "**Other taxa** preserves the remaining assembly counts. Colors distinguish branches; they do not show annotation coverage.")
+    with gr.Accordion("Snapshot sources and scope", open=False):
+        gr.Markdown("Source: [NCBI GenBank assembly summary](https://ftp.ncbi.nlm.nih.gov/genomes/ASSEMBLY_REPORTS/assembly_summary_genbank.txt) "
+                    "and [NCBI Taxonomy](https://ftp.ncbi.nlm.nih.gov/pub/taxonomy/taxdump.tar.gz). "
+                    "Counts roll up each assembly's taxon through its ancestors. Merged taxon IDs are resolved; unresolved IDs remain in an explicit group.")
+        gr.JSON(meta)
+
+    def taxonomy_view(taxid):
+        figure, text, choices, parent_id = taxonomy.view(taxid or "1")
+        return figure, text, gr.Dropdown(choices=choices, value=None), str(taxid or "1"), parent_id
+
+    def taxonomy_search(text):
+        choices = taxonomy.search(text) if str(text or "").strip() else []
+        return gr.Dropdown(choices=choices, value=None), f"{len(choices)} matching taxa shown." if choices else "No matching taxa. Try a scientific name or taxon ID."
+
+    outputs = [chart, note, child, selected, parent]
+    child.input(taxonomy_view, child, outputs)
+    matches.input(taxonomy_view, matches, outputs)
+    home.click(lambda: taxonomy_view("1"), outputs=outputs)
+    up.click(taxonomy_view, parent, outputs)
+    find.click(taxonomy_search, query, [matches, search_status])
+    query.submit(taxonomy_search, query, [matches, search_status])