tree-annotated-plot 0.0.1__tar.gz → 0.2.0__tar.gz

{tree_annotated_plot-0.0.1 → tree_annotated_plot-0.2.0}/.github/workflows/release.yml

@@ -1,4 +1,6 @@
-# Build wheel + sdist and publish to PyPI when a `v*` tag is pushed.
+# When a `v*` tag is pushed: build wheel + sdist, publish to PyPI,
+# then create a GitHub Release with auto-generated notes and the
+# wheel + sdist attached as downloadable assets.
 #
 # Uses PyPI trusted publishing (OIDC) — no API token / password is
 # stored in the repo. The trusted-publisher relationship must be
@@ -80,3 +82,31 @@ jobs:
           path: dist/
 
       - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    # Runs only after PyPI publish succeeds, so a transient PyPI failure
+    # doesn't leave a GitHub Release pointing at a version that isn't on
+    # PyPI. The Release page links to the tag, the wheel + sdist, and an
+    # auto-generated changelog (PR titles + commit list since the
+    # previous tag).
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      # `softprops/action-gh-release` needs write access to create a
+      # Release on the tag and upload the dist files as assets.
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - uses: softprops/action-gh-release@v3
+        with:
+          # Attach the same wheel + sdist that went to PyPI so the
+          # Release page is a complete record of what was published.
+          files: dist/*
+          # Auto-generate notes from PR titles + commits since the
+          # previous tag. Maintainer can edit them after the fact in
+          # the Releases UI without re-running the workflow.
+          generate_release_notes: true

tree_annotated_plot-0.0.1/.github/workflows/ci.yml → tree_annotated_plot-0.2.0/.github/workflows/tests.yml

@@ -1,10 +1,16 @@
 # Run lint, format-check, and tests on every push to main and on every PR.
 #
+# The workflow `name` is "tests" because that's what the README badge
+# displays — readers (especially the biology audience) parse "tests
+# passing" more readily than "CI passing". Behaviorally, this workflow
+# also runs ruff and black (i.e. it's the project's full CI gate, not
+# only tests); the slight label overload is intentional.
+#
 # Local equivalent: `scripts/check.sh` (which expects a local .venv;
 # this workflow uses the runner's python directly so it doesn't depend
 # on that layout).
 
-name: ci
+name: tests
 
 on:
   push:

tree_annotated_plot-0.2.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-05-06
+
+### Added
+
+- `connect_leader_to_label` (default `False`): extends each strain's
+  dashed leader line all the way to its text label. When on, the
+  chart's strain-axis labels are suppressed and replacement labels
+  are rendered alongside the tree on its chart-facing edge.
+- `strain_label_font_size` (default `10`), `strain_label_font_weight`
+  (default `"normal"`), and `shift_tree_loc` (default `0`) for tuning
+  the size, weight, and placement of the connected labels.
+- `color_tree_by` (default `None`): color the tree's branches and tip
+  circles by an Auspice node attribute (e.g. `"subclade"`) or by the
+  inferred genotype state at one or more sites
+  (e.g. `"genotype:HA1:158"` or `"genotype:HA1:158,189"`). Colors,
+  category ordering, and the bottom-of-plot legend match the
+  Nextstrain view of the same tree.
+- `tree_color_scale` (default `None`): override the default coloring
+  with an explicit `{category: color}` mapping. Keys must match the
+  tree's categories one-to-one and the legend order follows the
+  user's key order. CLI form: `"value1=#hex1,value2=#hex2,..."`.
+- `tree_color_legend_format` (default `None`): pass any subset of
+  Vega-Lite's
+  [Legend properties](https://vega.github.io/vega-lite/docs/legend.html#properties)
+  as a dict to style the tree's color legend (`orient`, `direction`,
+  `columns`, `padding`, `labelFontSize`, `titleFontSize`, …). When
+  `orient` is `"left"` or `"right"` and the user has not set
+  `columns` or `direction`, `columns=1` is forced so entries stack
+  vertically. CLI form: a JSON object string.
+- `tree_color_legend_show` (default `True`): set to `False` to hide
+  the tree's color legend entirely while still coloring the tree.
+- `scale_bar_font_size` (default `10`): font size for the tree's
+  scale bar label.
+
+### Changed
+
+- Default `tree_line_width` bumped from `1.5` to `2`, default
+  `tree_node_size` from `28` to `45`. Tree branch lines and tip
+  circles are now drawn at full opacity. The thicker / fuller
+  defaults read better when the tree is colored (the prior values
+  were tuned for unicolor black trees).
+
+## [0.1.0] - 2026-05-04
+
+Initial release.

{tree_annotated_plot-0.0.1 → tree_annotated_plot-0.2.0}/CLAUDE.md

@@ -3,6 +3,11 @@
 - **Keep CLAUDE.md, README.md, and the docs site updated** when changing the
   code. `CLAUDE.md` describes programming conventions; `README.md` describes
   basic use; `docs/` is the user-facing reference. Don't let them drift.
+- **Record user-facing changes in `CHANGELOG.md`** under the `## [Unreleased]`
+  section as you make them — new parameters, behavior changes, removed
+  features, bug fixes — in [Keep a Changelog](https://keepachangelog.com/)
+  format. At release time, `## [Unreleased]` is renamed to
+  `## [X.Y.Z] - YYYY-MM-DD` and a fresh `## [Unreleased]` is created.
 - **Single source of truth — `pyproject.toml`**: canonical for dependencies,
   supported Python version, build config, tool settings. Don't restate any of
   these in prose; refer to `pyproject.toml`.
@@ -57,7 +62,7 @@
   scripts/check.sh
   ```
   The same three checks run in CI via
-  [`.github/workflows/ci.yml`](.github/workflows/ci.yml) on push to
+  [`.github/workflows/tests.yml`](.github/workflows/tests.yml) on push to
   `main` and on PRs (CI also fetches the upstream Kikawa Auspice JSONs
   so real-data tests run rather than skip). Local green ≈ CI green.
 - **Build docs alongside checks** when changing public API surface:
@@ -95,11 +100,13 @@
 - **Releases are tag-driven**. Push a `vX.Y.Z` tag (after bumping
   `pyproject.toml`'s `version`) and
   [`.github/workflows/release.yml`](.github/workflows/release.yml)
-  builds wheel + sdist and publishes to PyPI via trusted publishing
-  (OIDC — no token in the repo). The build job verifies the tag and
-  `pyproject.toml` version match before publishing. Per-release recipe
-  and one-time PyPI configuration steps are in `README.md` under
-  "Releasing a new version".
+  builds wheel + sdist, publishes to PyPI via trusted publishing
+  (OIDC — no token in the repo), and creates a matching GitHub
+  Release with auto-generated notes + the wheel/sdist attached as
+  assets. The build job verifies the tag and `pyproject.toml` version
+  match before publishing. Per-release recipe and one-time PyPI
+  configuration steps are in `README.md` under "Releasing a new
+  version".
 - **Adding a new example** (full recipe in `README.md`):
   1. Self-contained module under `examples/` with module-level
      helpers (callable from outside).

{tree_annotated_plot-0.0.1 → tree_annotated_plot-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tree-annotated-plot
-Version: 0.0.1
+Version: 0.2.0
 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
@@ -51,6 +51,10 @@ Description-Content-Type: text/markdown
 
 # `tree-annotated-plot`: annotate the axis of an Altair / Vega-Lite plot with a phylogenetic tree
 
+[![PyPI version](https://img.shields.io/pypi/v/tree-annotated-plot.svg)](https://pypi.org/project/tree-annotated-plot/)
+[![Python versions](https://img.shields.io/pypi/pyversions/tree-annotated-plot.svg)](https://pypi.org/project/tree-annotated-plot/)
+[![tests](https://github.com/jbloomlab/tree-annotated-plot/actions/workflows/tests.yml/badge.svg)](https://github.com/jbloomlab/tree-annotated-plot/actions/workflows/tests.yml)
+[![Docs](https://img.shields.io/github/deployments/jbloomlab/tree-annotated-plot/github-pages?label=docs)](https://jbloomlab.github.io/tree-annotated-plot/)
 [![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)
@@ -60,6 +64,26 @@ See [https://jbloomlab.github.io/tree-annotated-plot/](https://jbloomlab.github.
 
 > **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.
 
+## Installation
+
+Released on [PyPI](https://pypi.org/project/tree-annotated-plot/). Requires Python 3.13+.
+
+```bash
+pip install tree-annotated-plot
+```
+
+To install the bleeding edge directly from this repository:
+
+```bash
+pip install git+https://github.com/jbloomlab/tree-annotated-plot.git
+```
+
+For a development checkout, see [Installation (development)](#installation-development) below.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the version history.
+
 ## Notes for developing the package
 
 ### Installation (development)
@@ -110,9 +134,9 @@ Then open `site/examples.html` in a browser and, for each example:
 If something visibly regresses, fix it before pushing — there's no
 CI gate that will catch a visual regression for you.
 
-### Continuous integration
+### Continuous integration tests
 
-[`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs on every
+[`.github/workflows/tests.yml`](.github/workflows/tests.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
@@ -129,8 +153,11 @@ merge), and additionally deploys `site/` to GitHub Pages on push to
 
 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).
+builds the sdist + wheel when a `v*` tag is pushed, publishes them
+to PyPI, and creates a matching
+[GitHub Release](https://github.com/jbloomlab/tree-annotated-plot/releases)
+with auto-generated notes and the wheel/sdist attached (see
+"Releasing a new version" below).
 
 ### Releasing a new version
 

{tree_annotated_plot-0.0.1 → tree_annotated_plot-0.2.0}/README.md

@@ -1,5 +1,9 @@
 # `tree-annotated-plot`: annotate the axis of an Altair / Vega-Lite plot with a phylogenetic tree
 
+[![PyPI version](https://img.shields.io/pypi/v/tree-annotated-plot.svg)](https://pypi.org/project/tree-annotated-plot/)
+[![Python versions](https://img.shields.io/pypi/pyversions/tree-annotated-plot.svg)](https://pypi.org/project/tree-annotated-plot/)
+[![tests](https://github.com/jbloomlab/tree-annotated-plot/actions/workflows/tests.yml/badge.svg)](https://github.com/jbloomlab/tree-annotated-plot/actions/workflows/tests.yml)
+[![Docs](https://img.shields.io/github/deployments/jbloomlab/tree-annotated-plot/github-pages?label=docs)](https://jbloomlab.github.io/tree-annotated-plot/)
 [![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)
@@ -9,6 +13,26 @@ See [https://jbloomlab.github.io/tree-annotated-plot/](https://jbloomlab.github.
 
 > **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.
 
+## Installation
+
+Released on [PyPI](https://pypi.org/project/tree-annotated-plot/). Requires Python 3.13+.
+
+```bash
+pip install tree-annotated-plot
+```
+
+To install the bleeding edge directly from this repository:
+
+```bash
+pip install git+https://github.com/jbloomlab/tree-annotated-plot.git
+```
+
+For a development checkout, see [Installation (development)](#installation-development) below.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for the version history.
+
 ## Notes for developing the package
 
 ### Installation (development)
@@ -59,9 +83,9 @@ Then open `site/examples.html` in a browser and, for each example:
 If something visibly regresses, fix it before pushing — there's no
 CI gate that will catch a visual regression for you.
 
-### Continuous integration
+### Continuous integration tests
 
-[`.github/workflows/ci.yml`](.github/workflows/ci.yml) runs on every
+[`.github/workflows/tests.yml`](.github/workflows/tests.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
@@ -78,8 +102,11 @@ merge), and additionally deploys `site/` to GitHub Pages on push to
 
 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).
+builds the sdist + wheel when a `v*` tag is pushed, publishes them
+to PyPI, and creates a matching
+[GitHub Release](https://github.com/jbloomlab/tree-annotated-plot/releases)
+with auto-generated notes and the wheel/sdist attached (see
+"Releasing a new version" below).
 
 ### Releasing a new version
 

{tree_annotated_plot-0.0.1 → tree_annotated_plot-0.2.0}/docs/examples.md

@@ -97,8 +97,170 @@ With the tree panel added by `tree-annotated-plot`:
 The strain axis is on `y`, so `tree_annotated_plot.plot` auto-picks
 the **vertical layout** (`tree_location` defaults to `"left"` on a
 y-encoded strain): result is an `HConcatChart` with the tree on the
-left, tips flush against the chart's strain labels, and a centered
-scale bar at the bottom of the tree panel.
+left and a centered scale bar at the bottom of the tree panel. The
+chart's natural strain-axis labels are kept exactly as the
+chart-builder wrote them (fonts, ticks, axis title, and all), and the
+tree's dashed leader lines stop at the tree panel's chart-facing
+edge.
+
+The H3N2 example above is rendered with `color_tree_by="subclade"`,
+which colors the tree's branches and tip circles by the
+`node_attrs.subclade` value at each node and adds a categorical legend
+below the plot. See "Color the tree" below for the full set of options.
+
+### Optional: connect leaders all the way to the labels
+
+If you'd prefer the dashed leaders to run flush into the strain
+labels themselves (with no break between tip and label), set
+`connect_leader_to_label=True`. This involves moving the labels off
+the chart's natural axis and into the tree panel, with a few
+trade-offs to be aware of:
+
+- The chart's strain-axis is replaced: any labels, ticks, title,
+  or custom `axis=...` you set on that encoding are dropped, and
+  replacement labels are rendered alongside the tree.
+- Label widths are estimated, not measured exactly, so layout may
+  need tuning. The two main knobs are `strain_label_font_size`
+  (default 10) and `shift_tree_loc` (a manual pixel offset that
+  moves the tree closer to the labels).
+
+The example below turns on label connection, shrinks the labels to
+9 pt, and uses `shift_tree_loc=60` to bring the tree flush against
+them:
+
+![H3N2 with label connection at 9pt font](images/h3n2_combined_label_connect.svg)
+
+[Open the interactive chart in a new tab →](charts/h3n2_combined_label_connect.html){target="_blank"}
+
+CLI flags: `--connect-leader-to-label --strain-label-font-size 9
+--shift-tree-loc 60`. In Python:
+`connect_leader_to_label=True, strain_label_font_size=9, shift_tree_loc=60`.
+
+### Color the tree
+
+Pass `color_tree_by` to color the tree's branches and tip circles by
+any property the Auspice JSON exposes — broadly, anything that
+appears in the "Color By" dropdown on the Nextstrain view of the same
+tree. Two forms are supported:
+
+- A named attribute, e.g. `color_tree_by="subclade"` (used in the
+  example above). Common alternatives include `"clade_membership"`,
+  `"region"`, `"country"` — whichever the tree provides.
+- A genotype at one or more sites in a gene. For a single site,
+  `color_tree_by="genotype:HA1:158"` colors each tip by the amino
+  acid at HA1 site 158. A comma-separated list gives a haplotype:
+  `"genotype:HA1:158,189"`. Sites that don't vary in the tree are
+  dropped from the haplotype label.
+
+Colors match what you'd see on the Nextstrain view of the same tree —
+either from the JSON's palette information when the build provides it,
+or from the same default palette Auspice uses when it doesn't.
+Categories are ordered by descending frequency in both cases. Missing
+values render in gray, and the legend is drawn at the bottom of the
+combined plot.
+
+The example below colors the same H3N2 chart by genotype at HA1
+site 158, which has two mutations in the tree (`N158K`, `N158D`) and
+so renders three states (N, K, D):
+
+![H3N2 combined chart, colored by genotype HA1:158](images/h3n2_combined_genotype_158.svg)
+
+[Open the interactive chart in a new tab →](charts/h3n2_combined_genotype_158.html){target="_blank"}
+
+CLI flag: `--color-tree-by genotype:HA1:158`. In Python:
+`color_tree_by="genotype:HA1:158"`.
+
+### Customizing the colors and legend
+
+Four optional knobs let you override the defaults:
+
+- `tree_color_scale` — supply your own `{category: color}` mapping
+  instead of the Auspice palette. Keys must match the tree's
+  categories one-to-one (extras or misses are an error). The legend
+  order follows the order of keys you pass. `"unknown"` is always
+  gray and must not be specified.
+- `tree_color_legend_format` — pass any subset of Vega-Lite's
+  [Legend properties](https://vega.github.io/vega-lite/docs/legend.html#properties)
+  as a dict to style the legend (`orient`, `direction`, `columns`,
+  `padding`, `offset`, `labelFontSize`, `titleFontSize`, …). Smart
+  default: when `orient` is `"left"` or `"right"` and you have not
+  set `columns` or `direction`, entries stack vertically
+  (`columns=1` is forced).
+- `tree_color_legend_show` — set to `False` to hide the legend
+  entirely while keeping the tree colored.
+- `scale_bar_font_size` — font size for the scale bar's label.
+
+The exact category strings depend on the form of `color_tree_by`:
+
+| `color_tree_by` | Example category strings |
+|---|---|
+| node attribute (e.g. `"subclade"`) | `"K"`, `"J.2"`, `"J.2.4"` |
+| `"genotype:HA1:158"` (single site) | `"K158"`, `"R158"`, `"E158"` |
+| `"genotype:HA1:158,189"` (both sites vary) | `"K158/E189"`, `"R158/E189"` |
+| `"genotype:HA1:158,189"` (189 invariant) | `"K158"`, `"R158"` (invariant site dropped) |
+
+If you pass keys that don't match, the error message lists the
+tree's actual categories so you can copy them.
+
+The H3N2 example below puts all four knobs to work: an explicit
+6-color palette (a colorblind-safe Okabe–Ito-inspired set) ordered
+K → J.2.4 → J.2.3 → J.2.2 → J.2 → G.1.3.1, the legend moved to the
+**left** of the combined plot at 14-pt, and a matching 14-pt
+scale-bar label.
+
+![H3N2 combined chart with custom colors and legend](images/h3n2_combined_custom_colors.svg)
+
+[Open the interactive chart in a new tab →](charts/h3n2_combined_custom_colors.html){target="_blank"}
+
+```python
+out = tree_annotated_plot.plot(
+    "examples/data/flu-seqneut-2025to2026_H3N2.json",
+    chart,
+    chart_strain_field="axis_label",
+    tree_strain_field="derived_haplotype",
+    branch_length="div",
+    tree_size=140,
+    scale_bar=True,
+    branch_length_units="substitutions",
+    color_tree_by="subclade",
+    tree_color_scale={
+        "K": "#0072B2",
+        "J.2.4": "#009E73",
+        "J.2.3": "#D55E00",
+        "J.2.2": "#CC79A7",
+        "J.2": "#56B4E9",
+        "G.1.3.1": "#E69F00",
+    },
+    tree_color_legend_format={
+        "orient": "left",
+        "labelFontSize": 14,
+        "titleFontSize": 14,
+    },
+    scale_bar_font_size=14,
+)
+```
+
+`--tree-color-scale` on the CLI is a comma-separated list of
+`key=color` pairs and `--tree-color-legend-format` is a JSON object
+string (quote the whole argument in both cases so the shell doesn't
+interpret `#`, braces, or quotes):
+
+```bash
+tree-annotated-plot \
+    --tree examples/data/flu-seqneut-2025to2026_H3N2.json \
+    --chart examples/data/flu-seqneut-2025to2026_H3N2_titers.json \
+    --chart-strain-field axis_label \
+    --tree-strain-field derived_haplotype \
+    --branch-length div \
+    --tree-size 140 \
+    --scale-bar \
+    --branch-length-units substitutions \
+    --color-tree-by subclade \
+    --tree-color-scale "K=#0072B2,J.2.4=#009E73,J.2.3=#D55E00,J.2.2=#CC79A7,J.2=#56B4E9,G.1.3.1=#E69F00" \
+    --tree-color-legend-format '{"orient":"left","labelFontSize":14,"titleFontSize":14}' \
+    --scale-bar-font-size 14 \
+    --output examples/data/h3n2_combined_custom_colors.html
+```
 
 ### Reproduce — command line
 
@@ -114,6 +276,7 @@ tree-annotated-plot \
     --tree-size 140 \
     --scale-bar \
     --branch-length-units substitutions \
+    --color-tree-by subclade \
     --output examples/data/h3n2_combined.json
 ```
 
@@ -131,6 +294,7 @@ out = tree_annotated_plot.plot(
     tree_size=140,
     scale_bar=True,
     branch_length_units="substitutions",
+    color_tree_by="subclade",
 )
 ```
 

{tree_annotated_plot-0.0.1 → tree_annotated_plot-0.2.0}/docs/index.md

@@ -24,6 +24,31 @@ with `Chart` / `LayerChart` / `FacetChart` / `HConcatChart` /
 axis. The tree drops to whichever side of the chart the strain labels
 sit on by default (left for y-axis, bottom for x-axis).
 
+## Installation
+
+Released on [PyPI](https://pypi.org/project/tree-annotated-plot/).
+Requires Python 3.13+.
+
+```bash
+pip install tree-annotated-plot
+```
+
+To pin a specific version:
+
+```bash
+pip install tree-annotated-plot==0.0.1
+```
+
+To install the bleeding edge directly from the
+[GitHub source](https://github.com/jbloomlab/tree-annotated-plot):
+
+```bash
+pip install git+https://github.com/jbloomlab/tree-annotated-plot.git
+```
+
+For a development checkout (contributors), see the README's
+[development install](https://github.com/jbloomlab/tree-annotated-plot#installation-development).
+
 ## 30-second example
 
 Given an Auspice tree at `h3n2.auspice.json` and a Vega-Lite chart spec

{tree_annotated_plot-0.0.1 → tree_annotated_plot-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tree-annotated-plot"
-version = "0.0.1"
+version = "0.2.0"
 description = "Annotate the axis of an Altair / Vega-Lite plot with a phylogenetic tree."
 readme = "README.md"
 requires-python = ">=3.13"

{tree_annotated_plot-0.0.1 → tree_annotated_plot-0.2.0}/scripts/generate_docs_assets.py

@@ -110,9 +110,7 @@ def _render_kikawa() -> None:
         # Render the bare chart (no tree) so the docs page can show what
         # the chart looks like before tree-annotated-plot wraps it.
         _save_pair(chart, f"{basename}_chart_only")
-        out = tree_annotated_plot.plot(
-            DATA_DIR / f"flu-seqneut-2025to2026_{subtype}.json",
-            chart,
+        plot_kwargs = dict(
             chart_strain_field="axis_label",
             tree_strain_field="derived_haplotype",
             branch_length="div",
@@ -120,8 +118,110 @@ def _render_kikawa() -> None:
             scale_bar=True,
             branch_length_units="substitutions",
         )
+        if subtype == "H3N2":
+            # Color H3N2 by subclade so the docs SVG matches what users see
+            # on Nextstrain. The Auspice JSON's meta.colorings.subclade has
+            # no `scale` defined, so colors come from the default palette.
+            plot_kwargs["color_tree_by"] = "subclade"
+        out = tree_annotated_plot.plot(
+            DATA_DIR / f"flu-seqneut-2025to2026_{subtype}.json",
+            chart,
+            **plot_kwargs,
+        )
         _save_pair(out, f"{basename}_combined")
 
+    # H3N2 again, with `connect_leader_to_label=True` and a 9-point label
+    # font: opt-in label connection where leaders run flush into the
+    # labels rendered alongside the tree (the default keeps the chart's
+    # natural strain-axis labels untouched).
+    h3n2_chart = builder.make_chart(
+        subtype="H3N2",
+        chart_type="iqr",
+        titers=titers,
+        viruses=viruses,
+        metadata=metadata,
+        all_cohorts=all_cohorts,
+    )
+    out = tree_annotated_plot.plot(
+        DATA_DIR / "flu-seqneut-2025to2026_H3N2.json",
+        h3n2_chart,
+        chart_strain_field="axis_label",
+        tree_strain_field="derived_haplotype",
+        branch_length="div",
+        tree_size=140,
+        scale_bar=True,
+        branch_length_units="substitutions",
+        connect_leader_to_label=True,
+        strain_label_font_size=9,
+        shift_tree_loc=60,
+        color_tree_by="subclade",
+    )
+    _save_pair(out, "h3n2_combined_label_connect")
+
+    # H3N2 once more, colored by genotype at HA1 site 158: same chart and
+    # default layout as `h3n2_combined`, with `color_tree_by` switched to
+    # the genotype form. Site 158 has two mutations (N158K, N158D) in the
+    # tree, so this renders three states (N, K, D).
+    h3n2_chart_genotype = builder.make_chart(
+        subtype="H3N2",
+        chart_type="iqr",
+        titers=titers,
+        viruses=viruses,
+        metadata=metadata,
+        all_cohorts=all_cohorts,
+    )
+    out = tree_annotated_plot.plot(
+        DATA_DIR / "flu-seqneut-2025to2026_H3N2.json",
+        h3n2_chart_genotype,
+        chart_strain_field="axis_label",
+        tree_strain_field="derived_haplotype",
+        branch_length="div",
+        tree_size=140,
+        scale_bar=True,
+        branch_length_units="substitutions",
+        color_tree_by="genotype:HA1:158",
+    )
+    _save_pair(out, "h3n2_combined_genotype_158")
+
+    # H3N2 once more, demonstrating all four appearance-tuning knobs:
+    # an explicit `tree_color_scale` (Okabe-Ito-inspired colorblind-safe
+    # palette, ordered K, J.2.4, J.2.3, J.2.2, J.2, G.1.3.1), a 14-pt
+    # legend on the left, and a 14-pt scale-bar label.
+    h3n2_chart_custom = builder.make_chart(
+        subtype="H3N2",
+        chart_type="iqr",
+        titers=titers,
+        viruses=viruses,
+        metadata=metadata,
+        all_cohorts=all_cohorts,
+    )
+    out = tree_annotated_plot.plot(
+        DATA_DIR / "flu-seqneut-2025to2026_H3N2.json",
+        h3n2_chart_custom,
+        chart_strain_field="axis_label",
+        tree_strain_field="derived_haplotype",
+        branch_length="div",
+        tree_size=140,
+        scale_bar=True,
+        branch_length_units="substitutions",
+        color_tree_by="subclade",
+        tree_color_scale={
+            "K": "#0072B2",
+            "J.2.4": "#009E73",
+            "J.2.3": "#D55E00",
+            "J.2.2": "#CC79A7",
+            "J.2": "#56B4E9",
+            "G.1.3.1": "#E69F00",
+        },
+        tree_color_legend_format={
+            "orient": "left",
+            "labelFontSize": 14,
+            "titleFontSize": 14,
+        },
+        scale_bar_font_size=14,
+    )
+    _save_pair(out, "h3n2_combined_custom_colors")
+
 
 def main() -> None:
     """Render every example to SVG + interactive HTML under `docs/`."""