#!/usr/bin/env python3
"""
plot_taxonomy_html.py
─────────────────────
Interactive, self-contained HTML sunburst of a maniFasta lineage manifest.
Companion to plot_taxonomy.py — it imports that module's tree builder and
colour logic, so the HTML and the static SVG always show the same numbers.
python3 plot_taxonomy_html.py \
--metadata AllOralsDB.v2026.214_S.manifest.lineage.tsv \
--out AllOralsDB.v2026.214_S.taxonomy_sunburst.html \
--title "AllOralsDB v2026.214_S"
Output is ONE .html file with no external dependencies.
Interactions
hover tooltip: name, rank, sequence count, % of database, lineage
click wedge zoom into that clade (angles rescale to fill the circle)
click centre zoom out one level
breadcrumb click any ancestor to jump back
search box dims everything whose lineage doesn't match
stdlib only.
"""
import sys
import json
import argparse
import importlib.util
from pathlib import Path
def info(m): print(f"[INFO] {m}", file=sys.stderr)
def die(m):
print(f"ERROR: {m}", file=sys.stderr)
raise SystemExit(1)
def load_plot_taxonomy(path: Path):
"""Import plot_taxonomy.py from an explicit path (it isn't a package)."""
if not path.is_file():
die(f"plot_taxonomy.py not found at {path} — pass --plot-taxonomy")
spec = importlib.util.spec_from_file_location("plot_taxonomy", path)
mod = importlib.util.module_from_spec(spec)
spec.loader.exec_module(mod)
for need in ("read_tsv", "build_tree", "make_color_map",
"top_group", "shade_hex", "measured_depth", "UNCLASS_COLOR"):
if not hasattr(mod, need):
die(f"{path} has no '{need}' — version mismatch?")
return mod
def tree_to_json(pt, root, *, color_by, cmap, ring_count):
"""Serialise the Node tree to plain dicts, precomputing each wedge's fill."""
def walk(node, path, depth):
d = {
"n": node.name,
"r": node.rank or "",
"v": node.value,
}
if depth > 0:
grp = pt.top_group(path, color_by)
d["c"] = pt.shade_hex(cmap.get(grp, pt.UNCLASS_COLOR),
node.depth, ring_count)
if depth < ring_count and node.children:
kids = sorted(node.children.values(), key=lambda c: -c.value)
d["ch"] = [walk(k, path + [k], depth + 1) for k in kids]
return d
return walk(root, [], 0)
HTML = r"""
__TITLE__ — taxonomic composition
__TITLE__
__SUBTITLE__
Click a wedge to zoom · click the centre to go back · hover for full label
"""
def main():
ap = argparse.ArgumentParser(description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--metadata", required=True, type=Path,
help="*.manifest.lineage.tsv from the build")
ap.add_argument("--out", required=True, type=Path, help="output .html")
ap.add_argument("--plot-taxonomy", type=Path, default=None,
help="path to plot_taxonomy.py (default: alongside this script)")
ap.add_argument("--prefix", default="tax_")
ap.add_argument("--color-by", default="phylum",
choices=["phylum", "domain_or_realm"], dest="color_by")
ap.add_argument("--max-depth", type=int, default=0, dest="max_depth")
ap.add_argument("--max-rings", type=int, default=8, dest="max_rings")
ap.add_argument("--unclassified-label", default="Unclassified",
dest="unclassified_label")
ap.add_argument("--title", default="Taxonomic composition")
ap.add_argument("--subtitle", default="")
ap.add_argument("--unit", default="sequences")
args = ap.parse_args()
pt_path = args.plot_taxonomy or (Path(__file__).resolve().parent / "plot_taxonomy.py")
pt = load_plot_taxonomy(pt_path)
if not args.metadata.is_file():
die(f"not found: {args.metadata}")
header, rows = pt.read_tsv(args.metadata)
info(f"rows: {len(rows):,}")
max_depth = args.max_depth if args.max_depth and args.max_depth > 0 else 0
root, n_rows = pt.build_tree(rows, header, args.prefix,
args.unclassified_label, max_depth)
cmap = pt.make_color_map(root, args.color_by, args.unclassified_label)
ring_count = pt.measured_depth(root)
if args.max_rings:
ring_count = min(ring_count, args.max_rings)
ring_count = max(ring_count, 1)
info(f"tree total: {root.value:,.0f} | rings: {ring_count}")
tree = tree_to_json(pt, root, color_by=args.color_by,
cmap=cmap, ring_count=ring_count)
# legend: aggregate node values at the colour-by rank
legend = {}
def collect(node, path):
for ch in node.children.values():
p = path + [ch]
if ch.rank == args.color_by:
grp = pt.top_group(p, args.color_by)
e = legend.setdefault(grp, [cmap.get(grp, pt.UNCLASS_COLOR), 0.0])
e[1] += ch.value
collect(ch, p)
collect(root, [])
leg = sorted(([k, v[0], v[1]] for k, v in legend.items()),
key=lambda x: -x[2])[:24]
html = (HTML
.replace("__TITLE__", args.title)
.replace("__SUBTITLE__", args.subtitle or f"{int(root.value):,} sequences")
.replace("__UNIT__", args.unit)
.replace("__RINGS__", str(ring_count))
.replace("__LEGEND__", json.dumps(leg))
.replace("__DATA__", json.dumps(tree, separators=(",", ":"))))
args.out.write_text(html, encoding="utf-8")
info(f"wrote {args.out} ({args.out.stat().st_size/1024:.0f} KB)")
if __name__ == "__main__":
main()