tree-annotated-plot 0.0.1__py3-none-any.whl

tree_annotated_plot/_tree.py

@@ -0,0 +1,307 @@
+"""Parse Auspice JSON phylogenetic trees and compute a 2-D layout for drawing."""
+
+from __future__ import annotations
+
+import json
+import warnings
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterator
+
+import pandas as pd
+
+
+@dataclass
+class TreeNode:
+    """A node in a phylogenetic tree.
+
+    `name` carries the resolved strain identifier for tips (the value at
+    `tree_strain_field`). For internal nodes, `name` is the Auspice top-level
+    `name` field — internal-node identity isn't used for chart-strain matching.
+
+    `x` is divergence from the root (read from `node_attrs.div`).
+    `y` is set by :func:`layout` and is the integer index of the node's tip
+    (for tips) or the midpoint of its descendants' tip indices (for internal
+    nodes).
+    """
+
+    name: str
+    x: float
+    children: list["TreeNode"] = field(default_factory=list)
+    y: float | None = None
+
+    @property
+    def is_tip(self) -> bool:
+        return not self.children
+
+
+def load_auspice(
+    source: str | Path | dict,
+    *,
+    tree_strain_field: str,
+    branch_length: str = "div",
+    strict_version: bool = True,
+) -> TreeNode:
+    """Load an Auspice JSON tree from a path or dict.
+
+    Parameters
+    ----------
+    source
+        Path to an Auspice JSON file, or an already-parsed dict.
+    tree_strain_field
+        Where on each tip to find the strain identifier. The literal string
+        ``"name"`` selects the tip's top-level ``name`` field; any other value
+        ``X`` selects ``node_attrs[X]`` (auto-unwrapping the Auspice
+        ``{"value": ...}`` convention). Dotted paths are not accepted.
+    branch_length
+        Which Auspice node attribute supplies branch lengths. ``"div"``
+        (default) reads ``node_attrs.div`` (a scalar absolute divergence
+        from the root). ``"num_date"`` reads ``node_attrs.num_date.value``
+        (an absolute calendar position in years). In both cases the value
+        is stored on each ``TreeNode.x`` and is used as-is by layout,
+        segments, and pruning — they're branch-source-agnostic.
+    strict_version
+        When True (default), raise ``ValueError`` if the Auspice JSON's
+        top-level ``version`` field does not start with ``"v2"``. With
+        ``False`` the same case becomes a ``warnings.warn``. A missing
+        ``version`` field always warns and proceeds.
+    """
+    _validate_tree_strain_field(tree_strain_field)
+    if branch_length not in ("div", "num_date"):
+        raise ValueError(
+            f"branch_length={branch_length!r} not supported; expected 'div' "
+            "or 'num_date'."
+        )
+
+    if isinstance(source, (str, Path)):
+        with open(source) as f:
+            data = json.load(f)
+    elif isinstance(source, dict):
+        data = source
+    else:
+        raise ValueError(f"unsupported tree source type: {type(source).__name__}")
+
+    _check_auspice_version(data, strict_version=strict_version)
+
+    if "tree" not in data:
+        raise ValueError("Auspice JSON must have a top-level 'tree' field")
+    return _parse_node(data["tree"], tree_strain_field, branch_length)
+
+
+def _check_auspice_version(data: dict, *, strict_version: bool) -> None:
+    """Inspect the Auspice top-level `version`; raise / warn on non-v2."""
+    version = data.get("version")
+    if version is None:
+        warnings.warn(
+            "Auspice JSON has no top-level 'version' field; proceeding, but "
+            "the structure is assumed to be Auspice v2.",
+            stacklevel=3,
+        )
+        return
+    if not isinstance(version, str) or not version.startswith("v2"):
+        msg = (
+            f"Auspice JSON has version={version!r}; this package only "
+            "supports v2. Regenerate the tree with a current Augur version."
+        )
+        if strict_version:
+            raise ValueError(msg)
+        warnings.warn(msg, stacklevel=3)
+
+
+def _validate_tree_strain_field(tree_strain_field: str) -> None:
+    if not isinstance(tree_strain_field, str) or not tree_strain_field:
+        raise ValueError(
+            f"tree_strain_field must be a non-empty string, got "
+            f"{tree_strain_field!r}"
+        )
+    if "." in tree_strain_field:
+        raise ValueError(
+            f"tree_strain_field={tree_strain_field!r} contains a dot. Dotted "
+            "paths are not supported. Use 'name' for the top-level Auspice "
+            "node `name` field, or a single attribute name (e.g. "
+            "'derived_haplotype') to look up under node_attrs (the "
+            "{'value': ...} Auspice convention is auto-unwrapped)."
+        )
+
+
+def _resolve_tip_strain(node_dict: dict, tree_strain_field: str) -> str:
+    """Look up tree_strain_field on a tip and return its string value."""
+    if tree_strain_field == "name":
+        v = node_dict.get("name")
+    else:
+        attrs = node_dict.get("node_attrs", {})
+        if tree_strain_field not in attrs:
+            raise ValueError(
+                f"tree tip {node_dict.get('name', '?')!r} has no "
+                f"node_attrs[{tree_strain_field!r}]"
+            )
+        v = attrs[tree_strain_field]
+        if isinstance(v, dict) and "value" in v:
+            v = v["value"]
+
+    if not isinstance(v, str) or not v:
+        raise ValueError(
+            f"tree_strain_field={tree_strain_field!r} on tip "
+            f"{node_dict.get('name', '?')!r} resolved to {v!r}; expected a "
+            "non-empty string"
+        )
+    return v
+
+
+def _parse_node(d: dict, tree_strain_field: str, branch_length: str) -> TreeNode:
+    children_dicts = d.get("children", [])
+    branch_value = _resolve_branch_length(d, branch_length)
+    if children_dicts:
+        # Internal node: use the Auspice top-level name (always present).
+        name = d.get("name") or "<internal>"
+    else:
+        # Tip: resolve via tree_strain_field.
+        name = _resolve_tip_strain(d, tree_strain_field)
+    children = [
+        _parse_node(c, tree_strain_field, branch_length) for c in children_dicts
+    ]
+    return TreeNode(name=name, x=float(branch_value), children=children)
+
+
+def _resolve_branch_length(node_dict: dict, branch_length: str) -> float:
+    """Pull the branch-length value out of a node's node_attrs."""
+    attrs = node_dict.get("node_attrs", {})
+    if branch_length == "div":
+        v = attrs.get("div")
+        if v is None:
+            raise ValueError(
+                f"tree node {node_dict.get('name', '?')!r} has no "
+                "node_attrs.div (required by branch_length='div')."
+            )
+        return v
+    # branch_length == "num_date"
+    nd = attrs.get("num_date")
+    if not isinstance(nd, dict) or "value" not in nd:
+        raise ValueError(
+            f"tree node {node_dict.get('name', '?')!r} has no "
+            "node_attrs.num_date.value (required by branch_length='num_date')."
+        )
+    return nd["value"]
+
+
+def _prune_tree_to(root: TreeNode, keep_strains: set[str]) -> TreeNode:
+    """Return a new tree pruned to subtrees whose tips are in `keep_strains`.
+
+    Strict-flavor pruning per the Phase 2 plan:
+      - Drop every tip whose `name` is not in `keep_strains`.
+      - Drop every internal node whose entire subtree was dropped.
+      - Collapse single-child internals: when an internal node has only
+        one surviving child after pruning, the kept child replaces it.
+        Because each `TreeNode.x` is the *absolute* divergence from the
+        original root (not a delta from its parent), no branch-length
+        summation is needed — the kept node's `x` already reflects the
+        correct distance from any further-up ancestor. (For `num_date`
+        once Phase 2h adds it, the same holds: dates are absolute
+        positions.)
+      - Re-root to the LCA of the kept tips: if the original root has
+        only one kept-child path, the recursive case collapses upward
+        until a node with ≥2 surviving subtrees is reached, which becomes
+        the new root.
+
+    Raises ValueError if the resulting tree has no tips (i.e. `keep_strains`
+    didn't overlap any tip's name).
+    """
+    pruned = _prune_recursive(root, keep_strains)
+    if pruned is None:
+        raise ValueError(
+            "after pruning, no tips remain; keep_strains has no overlap "
+            "with the tree's tip names"
+        )
+    return pruned
+
+
+def _prune_recursive(node: TreeNode, keep_strains: set[str]) -> TreeNode | None:
+    """Return a copy of `node` pruned to kept descendants, or None if no
+    descendants are kept.
+
+    Single-child internals are collapsed by returning the surviving child
+    directly — its absolute `x` is preserved, so root-to-tip distances
+    survive unchanged.
+    """
+    if node.is_tip:
+        if node.name in keep_strains:
+            return TreeNode(name=node.name, x=node.x, children=[])
+        return None
+
+    new_children: list[TreeNode] = []
+    for c in node.children:
+        kept = _prune_recursive(c, keep_strains)
+        if kept is not None:
+            new_children.append(kept)
+
+    if not new_children:
+        return None
+    if len(new_children) == 1:
+        # Collapse this single-child internal into its child.
+        return new_children[0]
+    return TreeNode(name=node.name, x=node.x, children=new_children)
+
+
+def tips(root: TreeNode) -> Iterator[TreeNode]:
+    """Yield tips of the tree in left-to-right (pre-order) traversal."""
+    if root.is_tip:
+        yield root
+    else:
+        for c in root.children:
+            yield from tips(c)
+
+
+def layout(root: TreeNode) -> list[TreeNode]:
+    """Assign `y` to every node in the tree and return tips in order.
+
+    Tips get integer y indices 0..N-1 in left-to-right order. Internal nodes
+    get the midpoint of their immediate children's y values.
+    """
+    tip_list = list(tips(root))
+    if not tip_list:
+        raise ValueError("tree has no tips")
+    for i, tip in enumerate(tip_list):
+        tip.y = float(i)
+    _assign_internal_y(root)
+    return tip_list
+
+
+def _assign_internal_y(node: TreeNode) -> float:
+    if node.is_tip:
+        assert node.y is not None
+        return node.y
+    ys = [_assign_internal_y(c) for c in node.children]
+    node.y = (min(ys) + max(ys)) / 2.0
+    return node.y
+
+
+def segments(root: TreeNode) -> pd.DataFrame:
+    """Build a DataFrame of line segments for drawing the tree.
+
+    Returns columns `x`, `x2`, `y`, `y2`. Each row is one segment:
+
+    - For each internal node, one vertical connector from the topmost to the
+      bottommost child (x == x2 == node.x).
+    - For each non-root node, one horizontal branch from its parent's x to its
+      own x at its own y (y == y2).
+
+    Assumes :func:`layout` has already been called on `root`.
+    """
+    if root.y is None:
+        raise ValueError("call layout(root) before segments(root)")
+
+    rows: list[dict] = []
+
+    def walk(node: TreeNode) -> None:
+        if node.is_tip:
+            return
+        child_ys = [c.y for c in node.children]
+        rows.append(
+            {"x": node.x, "x2": node.x, "y": min(child_ys), "y2": max(child_ys)}
+        )
+        for c in node.children:
+            rows.append({"x": node.x, "x2": c.x, "y": c.y, "y2": c.y})
+            walk(c)
+
+    walk(root)
+    return pd.DataFrame(rows, columns=["x", "x2", "y", "y2"])

tree_annotated_plot/cli.py

@@ -0,0 +1,165 @@
+"""`tree-annotated-plot` command-line entry point.
+
+The CLI's --tree, --chart, --output options are hand-written (they are
+CLI-specific data inputs without a config-object equivalent: their
+*types* differ between Python and CLI surfaces, even though their
+*descriptions* are single-sourced as `_config.{TREE,CHART,OUTPUT}_DESCRIPTION`).
+Every other option is **auto-generated** from `PlotConfig` so its
+`--help` text comes from the same `Annotated[T, "<description>"]`
+metadata that documents the Python `tree_annotated_plot.plot` function. Adding a new
+parameter takes one edit to `_config.py`; both surfaces pick it up.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import types
+import typing
+from pathlib import Path
+from typing import Any, Literal, get_args, get_origin, get_type_hints
+
+import click
+
+from ._config import (
+    CHART_DESCRIPTION,
+    OUTPUT_DESCRIPTION,
+    TREE_DESCRIPTION,
+    PlotConfig,
+)
+from ._plot import _build
+
+_SCALAR_CLICK_TYPE = {int: click.INT, float: click.FLOAT, str: click.STRING}
+
+
+def _option_for_field(field: dataclasses.Field, hints: dict) -> Any:
+    """Build a `click.option(...)` decorator from a PlotConfig field.
+
+    Handles every field shape we use:
+      - bool (with default) → `--flag/--no-flag` dual form.
+      - Literal[...] → `click.Choice([...])`, required if no default.
+      - X | None → unwraps to X with default None. Literal | None becomes
+        a Choice with default None.
+      - int / float / str → click.INT / click.FLOAT / click.STRING.
+
+    Required fields (no default) become `required=True`.
+    """
+    annotated = hints[field.name]
+    real_type = get_args(annotated)[0]
+    description = annotated.__metadata__[0]
+
+    cli_name = "--" + field.name.replace("_", "-")
+    has_default = field.default is not dataclasses.MISSING
+
+    # Bool → dual flag.
+    if real_type is bool:
+        return click.option(
+            f"{cli_name}/--no-{field.name.replace('_', '-')}",
+            default=field.default,
+            help=description,
+            show_default=True,
+        )
+
+    # Literal → Choice.
+    if get_origin(real_type) is Literal:
+        choices = [str(c) for c in get_args(real_type)]
+        kwargs: dict[str, Any] = {
+            "type": click.Choice(choices),
+            "help": description,
+            "show_default": has_default,
+        }
+        if has_default:
+            kwargs["default"] = field.default
+        else:
+            kwargs["required"] = True
+        return click.option(cli_name, **kwargs)
+
+    # Optional / Union — unwrap to the non-None branch.
+    origin = get_origin(real_type)
+    if origin in (typing.Union, types.UnionType):
+        non_none = [a for a in get_args(real_type) if a is not type(None)]
+        if len(non_none) == 1:
+            inner = non_none[0]
+            if get_origin(inner) is Literal:
+                choices = [str(c) for c in get_args(inner)]
+                return click.option(
+                    cli_name,
+                    type=click.Choice(choices),
+                    default=field.default if has_default else None,
+                    help=description,
+                    show_default=True,
+                )
+            return click.option(
+                cli_name,
+                type=_SCALAR_CLICK_TYPE.get(inner, click.STRING),
+                default=field.default if has_default else None,
+                help=description,
+                show_default=True,
+            )
+
+    # Plain scalar.
+    kwargs = {
+        "type": _SCALAR_CLICK_TYPE.get(real_type, click.STRING),
+        "help": description,
+        "show_default": has_default,
+    }
+    if has_default:
+        kwargs["default"] = field.default
+    else:
+        kwargs["required"] = True
+    return click.option(cli_name, **kwargs)
+
+
+def _stack_config_options(command: Any) -> Any:
+    """Apply one `click.option(...)` per PlotConfig field to `command`.
+
+    `click.option(...)` invoked on an already-built `Command` *appends*
+    to `command.params`, so iterating fields in declaration order gives
+    --help in declaration order (required fields first, since
+    `chart_strain_field` and `tree_strain_field` lead PlotConfig).
+    """
+    hints = get_type_hints(PlotConfig, include_extras=True)
+    for field in dataclasses.fields(PlotConfig):
+        command = _option_for_field(field, hints)(command)
+    return command
+
+
+@_stack_config_options
+@click.command(
+    name="tree-annotated-plot",
+    help=(
+        "Plot a phylogenetic tree alongside a Vega-Lite chart whose "
+        "categorical axis is reordered to match the tree's tip order. "
+        "Save the result as HTML / JSON / PNG / SVG / PDF "
+        "(format is dispatched on --output's extension)."
+    ),
+)
+@click.option(
+    "--tree",
+    "tree_path",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help=TREE_DESCRIPTION,
+)
+@click.option(
+    "--chart",
+    "chart_path",
+    required=True,
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help=CHART_DESCRIPTION,
+)
+@click.option(
+    "--output",
+    "output_path",
+    required=True,
+    type=click.Path(dir_okay=False, path_type=Path),
+    help=OUTPUT_DESCRIPTION,
+)
+def main(tree_path: Path, chart_path: Path, output_path: Path, **kwargs: Any) -> None:
+    """Top-level CLI entry point."""
+    config = PlotConfig(**kwargs)
+    out = _build(tree_path, chart_path, config)
+    out.save(str(output_path))
+
+
+if __name__ == "__main__":
+    main()

tree_annotated_plot-0.0.1.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: tree-annotated-plot
+Version: 0.0.1
+Summary: Annotate the axis of an Altair / Vega-Lite plot with a phylogenetic tree.
+Project-URL: Documentation, https://jbloomlab.github.io/tree-annotated-plot/
+Project-URL: Homepage, https://github.com/jbloomlab/tree-annotated-plot
+Project-URL: Repository, https://github.com/jbloomlab/tree-annotated-plot
+Project-URL: Issues, https://github.com/jbloomlab/tree-annotated-plot/issues
+Author-email: Jesse Bloom <jbloom@fredhutch.org>
+License: MIT License
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.13
+Requires-Dist: altair<7,>=6.0
+Requires-Dist: click>=8.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: vl-convert-python>=1.9
+Provides-Extra: dev
+Requires-Dist: black>=24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-click>=0.8; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# `tree-annotated-plot`: annotate the axis of an Altair / Vega-Lite plot with a phylogenetic tree
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+This is a Python package from the [Bloom lab](https://jbloomlab.org/) that allows you to combine an Altair / Vega-Lite plot with a Nextstrain JSON of a phylogenetic tree so that the tree is aligned to annotate strains on the axis of the plot.
+See [https://jbloomlab.github.io/tree-annotated-plot/](https://jbloomlab.github.io/tree-annotated-plot/) for detailed documentation.
+
+> **Note:** charts must be saved from altair 6+ (Vega-Lite v6). Older specs raise by default; pass `--no-strict-version` (CLI) or `strict_version=False` (Python) to override at your own risk. See the [docs](https://jbloomlab.github.io/tree-annotated-plot/) for details.
+
+## Notes for developing the package
+
+### Installation (development)
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,docs]"
+```
+
+[pyproject.toml](pyproject.toml) is the canonical source for the supported Python
+version and runtime dependencies.
+
+### Visual verification after code changes
+
+This package has automated tests for chart **structure** (encodings,
+sort order, tip reconciliation, scale-bar arithmetic, etc.), but
+**not** for chart **appearance** — there are no image-snapshot
+regression tests, because rendering is sensitive to fonts,
+`vl-convert-python` versions, and platform differences in ways that
+make pixel-level comparison flaky in practice.
+
+So the discipline is manual: any time you change code that affects
+rendering (`src/tree_annotated_plot/_plot.py`,
+`src/tree_annotated_plot/_tree.py`, the example scripts under
+`examples/`, or anything they touch), run the full check below and
+**eyeball every example** before considering the change done.
+
+```bash
+bash scripts/check.sh        # lint + format + pytest (all 100+ tests)
+bash scripts/build_docs.sh   # regenerates docs/images + docs/charts and runs mkdocs --strict
+```
+
+Then open `site/examples.html` in a browser and, for each example:
+
+1. Look at the embedded SVG screenshot. Does it match what the
+   feature you changed should produce? Are tip rows still aligned with
+   the chart rows? Is the tree's tip-end facing the chart? Is the
+   scale bar (if enabled) centered and labeled correctly?
+2. Click "Open the interactive chart →". Hover tips to confirm
+   tooltips fire; if there's a cohort selector (Kikawa examples),
+   toggle it; pan/zoom if relevant.
+3. Compare against the
+   [deployed site](https://jbloomlab.github.io/tree-annotated-plot/)
+   (which still reflects `main` before your change) for what "good"
+   looks like.
+
+If something visibly regresses, fix it before pushing — there's no
+CI gate that will catch a visual regression for you.
+
+### Continuous integration
+
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs on every
+push to `main` and every pull request: it installs the package, fetches
+the upstream Kikawa Auspice JSONs (so the real-data tests actually
+exercise rather than skip), builds the Kikawa titer chart specs, and
+runs `ruff check`, `black --check`, and `pytest tests/`. This mirrors
+[`scripts/check.sh`](scripts/check.sh) — green locally should mean
+green in CI.
+
+A separate workflow,
+[`.github/workflows/docs.yml`](.github/workflows/docs.yml), builds the
+docs site on every push to `main` and every PR (catching broken
+mkdocstrings refs / missing images / unresolved cross-links before
+merge), and additionally deploys `site/` to GitHub Pages on push to
+`main`.
+
+A third workflow,
+[`.github/workflows/release.yml`](.github/workflows/release.yml),
+builds the sdist + wheel and publishes them to PyPI when a `v*` tag
+is pushed (see "Releasing a new version" below).
+
+### Releasing a new version
+
+Releases are fully automated by tag push. Trusted publishing (OIDC)
+means **no API token or password is stored in the repo** — PyPI
+authenticates the workflow via its repo + workflow filename +
+environment.
+
+One-time setup (only needed before the first release):
+
+1. Reserve `tree-annotated-plot` on [PyPI](https://pypi.org/) (first
+   successful publish creates it; or claim it manually via
+   `pip install build && python -m build && twine upload dist/*` from a
+   maintainer machine).
+2. On PyPI, go to the project → "Publishing" tab → "Add a new pending
+   publisher". Fill in: owner `jbloomlab`, repository
+   `tree-annotated-plot`, workflow filename `release.yml`, environment
+   `pypi`.
+3. (Optional but recommended) On GitHub, repo Settings → Environments
+   → New environment → name `pypi`. Add yourself as a required
+   reviewer if you want a manual approval gate before each release
+   lands on PyPI.
+
+Per-release recipe (every time):
+
+```bash
+# 1. Edit pyproject.toml and bump `version = "X.Y.Z"`.
+# 2. Commit and tag (the workflow verifies they match before publishing).
+git commit -am "release vX.Y.Z"
+git tag vX.Y.Z
+git push && git push --tags
+```
+
+The `release` workflow then builds, verifies tag ⇋ version match, and
+publishes to PyPI.
+
+### Documentation
+The docs are at
+[https://jbloomlab.github.io/tree-annotated-plot/](https://jbloomlab.github.io/tree-annotated-plot/).
+They are auto-deployed by GitHub Actions on every push to `main` —
+[`.github/workflows/docs.yml`](.github/workflows/docs.yml) installs
+the package + docs extras, runs
+[`scripts/generate_docs_assets.py`](scripts/generate_docs_assets.py)
+to render images and standalone interactive HTML for each
+example, then `mkdocs build --strict`, and uploads `site/` as a
+GitHub Pages artifact.
+
+### Building documentation locally
+
+For day-to-day editing of the docs, use MkDocs's live-reload server
+(saves go straight to your browser):
+
+```bash
+mkdocs serve              # http://localhost:8000
+```
+
+To do this on the Fred Hutch remote server, do:
+```bash
+mkdocs serve -a $(hostname -i | awk '{print $1}'):$(fhfreeport)
+```
+
+For the strict build that matches CI (catches broken
+[`mkdocstrings`](https://mkdocstrings.github.io/) refs, missing
+images, unresolved cross-links):
+
+```bash
+bash scripts/build_docs.sh
+```
+
+This first runs `scripts/generate_docs_assets.py` (so the example
+SVGs and interactive HTMLs exist before MkDocs reads `docs/`), then
+`mkdocs build --strict`. Output lands in `site/`.
+
+### Adding a new example
+
+The docs follow a single template per example: a short motivation,
+an embedded SVG screenshot, a link to the fully-interactive
+standalone HTML, and the commands to reproduce (CLI form first,
+Python API form second). [`docs/examples.md`](docs/examples.md)
+shows the existing shape. To add another:
+
+1. Drop a runnable script into `examples/`. Keep helpers at module
+   level (callable from outside) so the asset script can import them.
+2. Add a clause to `scripts/generate_docs_assets.py` that imports
+   the script and calls `tree_annotated_plot.plot(...)` followed by saving both
+   `<name>.svg` (into `docs/images/`) and `<name>.html` (into
+   `docs/charts/`). Both directories are gitignored — only the
+   asset script writes there.
+3. Add a section to `docs/examples.md` matching the template.
+4. Run `bash scripts/build_docs.sh` and open `site/examples.html`
+   to verify. Push when happy; the deployed site updates on the
+   next CI run.