tree-annotated-plot 0.1.0__tar.gz → 0.2.1__tar.gz

tree_annotated_plot-0.2.1/CHANGELOG.md

@@ -0,0 +1,65 @@
+# 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.1] - 2026-05-06
+
+### Fixed
+
+- Apply tree-tip ordering to chart axes that use untyped Altair
+  shorthand (`alt.Y("strain")` without a `:N` / `:O` type suffix).
+  Previously the sort override was silently skipped, so the chart
+  rendered in data order instead of tree order.
+- An internal consistency check now raises if the spec-level walk
+  and the live-object walk over the user's chart ever disagree on
+  the number of strain-axis encodings, so silent skips like the
+  one above can't recur in another shape.
+
+## [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.1.0 → tree_annotated_plot-0.2.1}/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`.

{tree_annotated_plot-0.1.0 → tree_annotated_plot-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tree-annotated-plot
-Version: 0.1.0
+Version: 0.2.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
@@ -80,6 +80,10 @@ 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)

{tree_annotated_plot-0.1.0 → tree_annotated_plot-0.2.1}/README.md

@@ -29,6 +29,10 @@ 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)

{tree_annotated_plot-0.1.0 → tree_annotated_plot-0.2.1}/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.1.0 → tree_annotated_plot-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tree-annotated-plot"
-version = "0.1.0"
+version = "0.2.1"
 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.1.0 → tree_annotated_plot-0.2.1}/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/`."""