tree-annotated-plot 0.2.2__tar.gz → 0.4.0__tar.gz

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/CHANGELOG.md

@@ -5,6 +5,52 @@ 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).
 
+## [Unreleased]
+
+## [0.4.0] - 2026-08-20
+
+### Added
+
+- `spacing` (default `0`): pixels of blank space between the tree panel and
+  the chart panel. `0` keeps the two butted together, as before. Distinct from
+  `shift_tree_loc`, which moves the tree within its own panel by resizing the
+  label strip. CLI form: `--spacing`.
+
+### Changed
+
+- Pin `ruff` to `>=0.16,<0.17` and state the lint rules explicitly with
+  `[tool.ruff.lint] select`. Ruff's *default* rule set widened in 0.16, which
+  turned CI red on unchanged code; the selection is now a project decision
+  rather than whatever the installed ruff defaults to. Development-only, no
+  effect on the package.
+
+### Fixed
+
+- With `connect_leader_to_label` on, strain labels were anchored exactly on the
+  tree panel's chart-facing edge, so the text ran up against the chart's frame
+  and the frame line became hard to read. The pad that the label strip already
+  reserved is now applied between the text and the chart, and the leader lines
+  stop where the text begins rather than continuing to the panel edge. The gap
+  is `max(3, strain_label_font_size * 0.2)` px, and the tree panel grows by that
+  much, so a hand-tuned `shift_tree_loc` may want the same adjustment.
+
+## [0.3.0] - 2026-05-19
+
+### Added
+
+- `prune_chart_to_tree` (default `False`): when on, chart rows whose
+  `chart_strain_field` value isn't a tree tip are filtered out before
+  drawing. CLI form:
+  `--prune-chart-to-tree / --no-prune-chart-to-tree`.
+  ([#6](https://github.com/jbloomlab/tree-annotated-plot/issues/6))
+- `-h` is accepted as a short alias for `--help` on the
+  `tree-annotated-plot` CLI.
+
+### Changed
+
+- Minimum supported Python lowered from 3.13 to 3.11. CI still
+  runs on 3.13.
+
 ## [0.2.2] - 2026-05-09
 
 ### Fixed

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: tree-annotated-plot
-Version: 0.2.2
+Version: 0.4.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
@@ -30,10 +30,12 @@ License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Visualization
-Requires-Python: >=3.13
+Requires-Python: >=3.11
 Requires-Dist: altair<7,>=6.0
 Requires-Dist: click>=8.0
 Requires-Dist: pandas>=2.0
@@ -41,7 +43,7 @@ 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'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-click>=0.8; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
@@ -66,7 +68,7 @@ See [https://jbloomlab.github.io/tree-annotated-plot/](https://jbloomlab.github.
 
 ## Installation
 
-Released on [PyPI](https://pypi.org/project/tree-annotated-plot/). Requires Python 3.13+.
+Released on [PyPI](https://pypi.org/project/tree-annotated-plot/). Requires Python 3.11+.
 
 ```bash
 pip install tree-annotated-plot

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/README.md

@@ -15,7 +15,7 @@ See [https://jbloomlab.github.io/tree-annotated-plot/](https://jbloomlab.github.
 
 ## Installation
 
-Released on [PyPI](https://pypi.org/project/tree-annotated-plot/). Requires Python 3.13+.
+Released on [PyPI](https://pypi.org/project/tree-annotated-plot/). Requires Python 3.11+.
 
 ```bash
 pip install tree-annotated-plot

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/docs/index.md

@@ -27,7 +27,7 @@ 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+.
+Requires Python 3.11+.
 
 ```bash
 pip install tree-annotated-plot
@@ -36,7 +36,7 @@ pip install tree-annotated-plot
 To pin a specific version:
 
 ```bash
-pip install tree-annotated-plot==0.0.1
+pip install tree-annotated-plot==0.3.0
 ```
 
 To install the bleeding edge directly from the

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/pyproject.toml

@@ -4,15 +4,17 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tree-annotated-plot"
-version = "0.2.2"
+version = "0.4.0"
 description = "Annotate the axis of an Altair / Vega-Lite plot with a phylogenetic tree."
 readme = "README.md"
-requires-python = ">=3.13"
+requires-python = ">=3.11"
 license = { file = "LICENSE" }
 authors = [{ name = "Jesse Bloom", email = "jbloom@fredhutch.org" }]
 classifiers = [
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Operating System :: OS Independent",
     "Topic :: Scientific/Engineering :: Bio-Informatics",
@@ -34,7 +36,7 @@ Issues = "https://github.com/jbloomlab/tree-annotated-plot/issues"
 [project.optional-dependencies]
 dev = [
     "pytest>=8",
-    "ruff>=0.6",
+    "ruff>=0.16,<0.17",
     "black>=24",
 ]
 docs = [
@@ -52,7 +54,14 @@ packages = ["src/tree_annotated_plot"]
 dev-mode-dirs = ["src"]
 
 [tool.black]
-target-version = ["py313"]
+target-version = ["py311"]
 
 [tool.ruff]
-target-version = "py313"
+target-version = "py311"
+
+[tool.ruff.lint]
+# Ruff's default rule set is not stable across releases -- 0.16 broadened it,
+# which turned CI red on unchanged code. State the rules we lint against so a
+# ruff upgrade changes them only when we say so. These are ruff's pre-0.16
+# defaults, which is what this project has been checked against all along.
+select = ["E4", "E7", "E9", "F"]

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/src/tree_annotated_plot/_config.py

@@ -68,6 +68,15 @@ class PlotConfig:
         "(x-encoded).",
     ] = None
 
+    spacing: Annotated[
+        int,
+        "Pixels of blank space between the tree panel and the chart panel. "
+        "Default 0, which butts the two together. Distinct from "
+        "`shift_tree_loc`, which moves the tree within its own panel by "
+        "resizing the label strip; `spacing` sets the gap between the panels "
+        "and applies whether or not `connect_leader_to_label` is on.",
+    ] = 0
+
     tree_line_width: Annotated[
         float,
         "Stroke width (px) for the tree's branch lines. Default 2.",
@@ -109,9 +118,14 @@ class PlotConfig:
         "When off (default), tree tips not present in the chart's strain "
         "set are a fatal error. When on, those tips (and any internal "
         "nodes whose subtrees become empty) are dropped before drawing, "
-        "with single-child internals collapsed into their kept child. "
-        "Chart strains not present in the tree are *always* fatal "
-        "regardless of this flag — pruning would silently lose plot data.",
+        "with single-child internals collapsed into their kept child.",
+    ] = False
+
+    prune_chart_to_tree: Annotated[
+        bool,
+        "When off (default), chart strains not present in the tree are a "
+        "fatal error. When on, chart rows whose `chart_strain_field` "
+        "value isn't a tree tip are filtered out before drawing.",
     ] = False
 
     strict_version: Annotated[
@@ -150,8 +164,9 @@ class PlotConfig:
     shift_tree_loc: Annotated[
         int,
         "Pixels by which to shift the tree toward (positive) or away from "
-        "(negative) the chart. Default 0. Has no effect when "
-        "connect_leader_to_label is off.",
+        "(negative) the chart, by resizing the label strip inside the tree "
+        "panel. Default 0. Has no effect when connect_leader_to_label is off; "
+        "to set the gap between the tree and chart panels use `spacing`.",
     ] = 0
 
     color_tree_by: Annotated[

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/src/tree_annotated_plot/_plot.py

@@ -49,12 +49,14 @@ def plot(
     branch_length: Literal["div", "num_date"],
     tree_size: int = 100,
     tree_location: TreeLocation | None = None,
+    spacing: int = 0,
     tree_line_width: float = 2.0,
     tree_node_size: float = 45,
     leader_line_width: float = 1.0,
     scale_bar: bool = False,
     branch_length_units: str | None = None,
     prune_tree_to_chart: bool = False,
+    prune_chart_to_tree: bool = False,
     strict_version: bool = True,
     connect_leader_to_label: bool = False,
     strain_label_font_size: float = 10.0,
@@ -76,12 +78,14 @@ def plot(
             branch_length=branch_length,
             tree_size=tree_size,
             tree_location=tree_location,
+            spacing=spacing,
             tree_line_width=tree_line_width,
             tree_node_size=tree_node_size,
             leader_line_width=leader_line_width,
             scale_bar=scale_bar,
             branch_length_units=branch_length_units,
             prune_tree_to_chart=prune_tree_to_chart,
+            prune_chart_to_tree=prune_chart_to_tree,
             strict_version=strict_version,
             connect_leader_to_label=connect_leader_to_label,
             strain_label_font_size=strain_label_font_size,
@@ -168,12 +172,33 @@ def _build(
 
     chart_strains = _extract_chart_strains(spec, axis_hits, config.chart_strain_field)
 
+    if config.prune_chart_to_tree and (set(chart_strains) - set(tip_names)):
+        _prune_chart_spec_to_strains(
+            spec,
+            chart_strain_field=config.chart_strain_field,
+            keep_strains=set(tip_names),
+        )
+        chart = alt.Chart.from_dict(spec)
+        chart_strains = _extract_chart_strains(
+            spec, axis_hits, config.chart_strain_field
+        )
+        if not chart_strains:
+            raise ValueError(
+                "prune_chart_to_tree=True dropped every chart row: no "
+                "chart strain matched any tree tip under "
+                f"chart_strain_field={config.chart_strain_field!r} / "
+                f"tree_strain_field={config.tree_strain_field!r}. Pruning "
+                "is meant for charts that bundle a superset of strains; "
+                "an empty intersection suggests a wrong field choice."
+            )
+
     _reconcile_tips_and_strains(
         tree_strains=tip_names,
         chart_strains=chart_strains,
         chart_strain_field=config.chart_strain_field,
         tree_strain_field=config.tree_strain_field,
         prune_tree_to_chart=config.prune_tree_to_chart,
+        prune_chart_to_tree=config.prune_chart_to_tree,
         chart_spec=spec,
         tree_source=tree,
     )
@@ -258,7 +283,10 @@ def _build(
     hoisted_config, hoisted_other = _pop_toplevel_only_attrs(new_chart)
 
     combined = _concat_for_location(
-        tree_chart=tree_chart, user_chart=new_chart, location=location
+        tree_chart=tree_chart,
+        user_chart=new_chart,
+        location=location,
+        spacing=config.spacing,
     )
     _apply_combined_config(combined, hoisted_config)
     for k, v in hoisted_other.items():
@@ -297,6 +325,7 @@ def _concat_for_location(
     tree_chart: alt.TopLevelMixin,
     user_chart: alt.TopLevelMixin,
     location: TreeLocation,
+    spacing: int,
 ) -> alt.HConcatChart | alt.VConcatChart:
     """Concat tree and chart in the order implied by the tree's location.
 
@@ -310,19 +339,19 @@ def _concat_for_location(
     user-chart marks whose color values aren't in the tree's domain.
     """
     if location == "left":
-        return alt.hconcat(tree_chart, user_chart, spacing=0).resolve_scale(
+        return alt.hconcat(tree_chart, user_chart, spacing=spacing).resolve_scale(
             y="independent", color="independent"
         )
     if location == "right":
-        return alt.hconcat(user_chart, tree_chart, spacing=0).resolve_scale(
+        return alt.hconcat(user_chart, tree_chart, spacing=spacing).resolve_scale(
             y="independent", color="independent"
         )
     if location == "top":
-        return alt.vconcat(tree_chart, user_chart, spacing=0).resolve_scale(
+        return alt.vconcat(tree_chart, user_chart, spacing=spacing).resolve_scale(
             x="independent", color="independent"
         )
     if location == "bottom":
-        return alt.vconcat(user_chart, tree_chart, spacing=0).resolve_scale(
+        return alt.vconcat(user_chart, tree_chart, spacing=spacing).resolve_scale(
             x="independent", color="independent"
         )
     raise ValueError(f"unreachable: tree_location={location!r}")
@@ -641,6 +670,70 @@ def _extract_chart_strains(
     return _extract_field_values_from_spec_data(spec, chart_strain_field)
 
 
+def _prune_chart_spec_to_strains(
+    spec: dict, *, chart_strain_field: str, keep_strains: set[str]
+) -> None:
+    """Filter a Vega-Lite spec in place to drop rows outside `keep_strains`.
+
+    Mutates three kinds of structure:
+      - top-level `datasets` entries (each a list of row-dicts).
+      - inline `data.values` lists anywhere in the spec tree.
+      - explicit `sort` lists on encoding channels bound to
+        `chart_strain_field` (any other `sort` is left alone).
+
+    Rows that don't carry `chart_strain_field` at all are preserved
+    (we have no signal to drop them). URL-backed data raises — we
+    can't fetch + filter at plot time, mirroring `_extract_chart_strains`.
+    """
+
+    def row_kept(row: Any) -> bool:
+        if not isinstance(row, dict):
+            return True
+        if chart_strain_field not in row:
+            return True
+        return row[chart_strain_field] in keep_strains
+
+    datasets = spec.get("datasets") if isinstance(spec, dict) else None
+    if isinstance(datasets, dict):
+        for name, rows in list(datasets.items()):
+            if isinstance(rows, list):
+                datasets[name] = [row for row in rows if row_kept(row)]
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            data = node.get("data")
+            if isinstance(data, dict):
+                if "url" in data:
+                    raise ValueError(
+                        f"chart references data via URL ({data['url']!r}); "
+                        "URL data is not supported, so prune_chart_to_tree "
+                        "cannot filter it. Materialize the data inline "
+                        "(via alt.Chart(df) with a pandas DataFrame) before "
+                        "saving the chart."
+                    )
+                if "values" in data and isinstance(data["values"], list):
+                    data["values"] = [row for row in data["values"] if row_kept(row)]
+            encoding = node.get("encoding")
+            if isinstance(encoding, dict):
+                for channel in encoding.values():
+                    if not isinstance(channel, dict):
+                        continue
+                    if channel.get("field") != chart_strain_field:
+                        continue
+                    sort = channel.get("sort")
+                    if isinstance(sort, list):
+                        channel["sort"] = [s for s in sort if s in keep_strains]
+            for k, v in node.items():
+                if k in ("data", "datasets"):
+                    continue
+                walk(v)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(spec)
+
+
 def _extract_field_values_from_spec_data(spec: dict, field: str) -> list[str]:
     """Walk spec for inline / named data and return distinct values of `field`.
 
@@ -708,13 +801,16 @@ def _reconcile_tips_and_strains(
     chart_strain_field: str,
     tree_strain_field: str,
     prune_tree_to_chart: bool,
+    prune_chart_to_tree: bool,
     chart_spec: dict,
     tree_source: Any,
 ) -> None:
     """Verify tree strains and chart strains are reconcilable.
 
     Three asymmetries:
-      - chart strains not in tree → always fatal.
+      - chart strains not in tree → fatal unless `prune_chart_to_tree=True`
+        (in which case the chart spec has already been pre-filtered upstream
+        and this set is expected to be empty by the time we get here).
       - tree tips not in chart → fatal unless `prune_tree_to_chart=True`.
       - (duplicate tree_strain_field values across tips → handled by the
         separate `_check_no_duplicate_tip_strains`.)
@@ -728,7 +824,9 @@ def _reconcile_tips_and_strains(
     chart_minus_tree = chart_set - tree_set
     tree_minus_chart = tree_set - chart_set
 
-    if not chart_minus_tree and (not tree_minus_chart or prune_tree_to_chart):
+    chart_ok = not chart_minus_tree
+    tree_ok = not tree_minus_chart or prune_tree_to_chart
+    if chart_ok and tree_ok:
         return
 
     hints = _candidate_field_hints(
@@ -748,6 +846,7 @@ def _reconcile_tips_and_strains(
             chart_minus_tree=chart_minus_tree,
             tree_minus_chart=tree_minus_chart,
             prune_tree_to_chart=prune_tree_to_chart,
+            prune_chart_to_tree=prune_chart_to_tree,
             hints=hints,
         )
     )
@@ -762,14 +861,16 @@ def _format_strain_mismatch(
     chart_minus_tree: set[str],
     tree_minus_chart: set[str],
     prune_tree_to_chart: bool,
+    prune_chart_to_tree: bool,
     hints: list[str],
 ) -> str:
     parts: list[str] = []
-    if chart_minus_tree:
+    if chart_minus_tree and not prune_chart_to_tree:
         parts.append(
             f"{len(chart_minus_tree)} chart strain(s) are not present in the "
-            "tree (these would be silently dropped if we pruned, so this is "
-            "always fatal)."
+            "tree. Pass `prune_chart_to_tree=True` to drop the offending "
+            "chart rows automatically (use with care — this discards plot "
+            "data)."
         )
     if tree_minus_chart and not prune_tree_to_chart:
         parts.append(
@@ -783,7 +884,7 @@ def _format_strain_mismatch(
     )
     parts.append("Sample chart_strain_field values: " f"{sorted(chart_strains)[:5]}")
     parts.append("Sample tree_strain_field values:  " f"{sorted(tree_strains)[:5]}")
-    if chart_minus_tree:
+    if chart_minus_tree and not prune_chart_to_tree:
         parts.append(f"Sample chart-only values: {sorted(chart_minus_tree)[:5]}")
     if tree_minus_chart and not prune_tree_to_chart:
         parts.append(f"Sample tree-only values:  {sorted(tree_minus_chart)[:5]}")
@@ -1380,6 +1481,11 @@ def _build_scale_bar_layer(
 
 _LABEL_PAD_PX_MIN = 4
 _LABEL_PAD_RATIO = 0.4  # `LABEL_PAD_PX = max(MIN, font_size * RATIO)`
+# Gap between the labels and the chart, kept separate from the tree-facing pad
+# above because it clears the chart's frame rather than the deepest tip, and so
+# wants a small fixed clearance rather than the pad's larger, faster-growing one.
+_LABEL_CHART_GAP_PX_MIN = 3
+_LABEL_CHART_GAP_RATIO = 0.2  # `LABEL_CHART_GAP_PX = max(MIN, font_size * RATIO)`
 _LABEL_CHAR_PX_RATIO = 0.6  # rough proportional sans-serif glyph-width estimate
 _LABEL_HALO_RATIO = 0.6  # white-halo strokeWidth as a fraction of font_size
 
@@ -1519,9 +1625,15 @@ def _build_tree_chart(
         max_name_len = max((len(n) for n in names), default=0)
         char_px = strain_label_font_size * _LABEL_CHAR_PX_RATIO
         label_pad_px = max(_LABEL_PAD_PX_MIN, strain_label_font_size * _LABEL_PAD_RATIO)
+        chart_gap_px = max(
+            _LABEL_CHART_GAP_PX_MIN, strain_label_font_size * _LABEL_CHART_GAP_RATIO
+        )
         # Strip needs to fit the longest label plus `halo_px / 2` of halo
-        # extension on the leader-facing side, plus a small fixed pad.
-        label_pixel_width = label_pad_px + max_name_len * char_px + halo_px / 2
+        # extension on the leader-facing side, a pad between the tree and the
+        # text, and a smaller gap between the text and the chart.
+        label_pixel_width = (
+            label_pad_px + chart_gap_px + max_name_len * char_px + halo_px / 2
+        )
         strip_pixel_width = label_pixel_width - shift_tree_loc
         if strip_pixel_width <= 0:
             raise ValueError(
@@ -1534,9 +1646,13 @@ def _build_tree_chart(
         per_pixel = branch_span / tree_size if tree_size else 0.0
         extra_branch_units = strip_pixel_width * per_pixel
         chart_edge_branch = branch_max + extra_branch_units
-        tips_df = tips_df.assign(x_label=chart_edge_branch)
-        leader_df = tips_df[tips_df["x"] < chart_edge_branch].assign(
-            x2=chart_edge_branch
+        # Anchor the labels `chart_gap_px` *inside* the chart-facing edge rather
+        # than on it, so the text does not run up against the chart's frame. The
+        # leaders stop at the same place, where the text begins.
+        label_anchor_branch = chart_edge_branch - chart_gap_px * per_pixel
+        tips_df = tips_df.assign(x_label=label_anchor_branch)
+        leader_df = tips_df[tips_df["x"] < label_anchor_branch].assign(
+            x2=label_anchor_branch
         )
         extended_tree_size = tree_size + strip_pixel_width
     else:
@@ -1585,9 +1701,9 @@ def _build_tree_chart(
         # When connect_leader_to_label is on, the branch domain is extended
         # past `branch_max` to `chart_edge_branch` so the label strip has
         # data-units to occupy; tips at `branch_max` still sit at pixel
-        # `tree_size` on the panel. Each label's chart-facing edge is
-        # anchored at `chart_edge_branch` and aligned outward (right for
-        # tree on the left, left for tree on the right).
+        # `tree_size` on the panel. Each label's chart-facing edge sits
+        # `chart_gap_px` inside `chart_edge_branch`, aligned outward (right
+        # for tree on the left, left for tree on the right).
         if tree_location == "left":
             branch_domain = [branch_min, chart_edge_branch]
             text_align = "right"
@@ -1688,7 +1804,8 @@ def _build_tree_chart(
         # strip at bottom, opposite the chart above).
         # tree_location="bottom" → root at bottom → branch_max at top (label
         # strip at top, opposite the chart below).
-        # Each label's chart-facing edge is anchored at `chart_edge_branch`.
+        # Each label's chart-facing edge sits `chart_gap_px` inside
+        # `chart_edge_branch`.
         # The text mark is rotated 270° (reads bottom-to-top), which maps
         # pre-rotation `align="right"` to a top anchor (text extends down)
         # and `align="left"` to a bottom anchor (text extends up). For tree

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/src/tree_annotated_plot/cli.py

@@ -263,6 +263,7 @@ def _stack_config_options(command: Any) -> Any:
         "Save the result as HTML / JSON / PNG / SVG / PDF "
         "(format is dispatched on --output's extension)."
     ),
+    context_settings={"help_option_names": ["-h", "--help"]},
 )
 @click.option(
     "--tree",

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/tests/test_appearance_tuning.py

@@ -795,3 +795,30 @@ def test_cli_scale_bar_font_size(tmp_path):
     collect_text_marks(tree_panel, text_marks)
     sizes = [m.get("fontSize") for m in text_marks if "fontSize" in m]
     assert 16.0 in sizes or 16 in sizes
+
+
+def test_cli_spacing(tmp_path):
+    """`--spacing` reaches the saved spec's top-level concat gap."""
+    tree_path, chart_path, out_path = _cli_setup(
+        tmp_path, _attr_auspice(), _vertical_chart(["A", "B", "C", "D"])
+    )
+    _run_cli(
+        [
+            "--tree",
+            str(tree_path),
+            "--chart",
+            str(chart_path),
+            "--output",
+            str(out_path),
+            "--chart-strain-field",
+            "strain",
+            "--tree-strain-field",
+            "name",
+            "--branch-length",
+            "div",
+            "--spacing",
+            "9",
+        ]
+    )
+    spec = json.loads(out_path.read_text())
+    assert spec["spacing"] == 9

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/tests/test_cli.py

@@ -27,6 +27,14 @@ def test_help_lists_data_options() -> None:
     assert "--output" in result.output
 
 
+def test_short_help_flag_is_alias_for_long() -> None:
+    """`-h` should produce identical output to `--help`."""
+    long_form = _runner().invoke(main, ["--help"])
+    short_form = _runner().invoke(main, ["-h"])
+    assert short_form.exit_code == 0
+    assert short_form.output == long_form.output
+
+
 def test_help_lists_auto_generated_options() -> None:
     """A handful of PlotConfig-derived options should appear in --help."""
     result = _runner().invoke(main, ["--help"])
@@ -37,6 +45,7 @@ def test_help_lists_auto_generated_options() -> None:
         "--branch-length",
         "--tree-size",
         "--tree-location",
+        "--spacing",
         "--tree-line-width",
         "--scale-bar / --no-scale-bar",
         "--strict-version / --no-strict-version",

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/tests/test_label_connection.py

@@ -285,9 +285,9 @@ def test_default_leader_endpoint_stops_at_branch_max() -> None:
 
 def test_vertical_left_renders_text_with_right_align() -> None:
     """Vertical layout with `connect_leader_to_label=True` and default
-    `tree_location="left"`: tree on left, chart on right; labels flush
-    against the chart on the panel's right (chart-facing) edge. Text
-    mark uses `align="right"` and `x_label > branch_max`."""
+    `tree_location="left"`: tree on left, chart on right; labels sit just
+    inside the panel's right (chart-facing) edge. Text mark uses
+    `align="right"` and `x_label > branch_max`."""
     out = tree_annotated_plot.plot(_auspice(), _vertical_chart(), **_on_kw())
     text = _text_layer(out)
     assert text is not None
@@ -557,3 +557,48 @@ def test_default_off_keeps_user_axis_labels_intact() -> None:
     assert axis.get("labelFontWeight") == "bold"
     assert axis.get("labels") is not False
     assert axis.get("ticks") is not False
+
+
+# ---------- label inset from the chart-facing edge ----------
+
+
+def test_labels_sit_inside_the_chart_facing_edge() -> None:
+    """Labels are anchored one pad *inside* `chart_edge_branch` rather than on
+    it, so the glyphs do not run up against the chart panel's frame. The panel
+    itself still extends to `chart_edge_branch`, which is the chart-facing end
+    of the branch scale's domain."""
+    out = tree_annotated_plot.plot(_auspice(), _vertical_chart(), **_on_kw())
+    text = _text_layer(out)
+    assert text is not None
+    # tree on the left → branch domain is [branch_min, chart_edge_branch]
+    chart_edge_branch = text["encoding"]["x"]["scale"]["domain"][1]
+    rows = _resolve_dataset(out.to_dict(), text)
+    assert rows
+    for row in rows:
+        assert row["x_label"] < chart_edge_branch
+
+
+def test_labels_sit_inside_the_chart_facing_edge_horizontal() -> None:
+    """Same inset in horizontal layout, where the default tree_location is
+    "bottom" and the branch domain runs [branch_min, chart_edge_branch] on y."""
+    out = tree_annotated_plot.plot(_auspice(), _horizontal_chart(), **_on_kw())
+    text = _text_layer(out)
+    assert text is not None
+    chart_edge_branch = text["encoding"]["y"]["scale"]["domain"][1]
+    rows = _resolve_dataset(out.to_dict(), text)
+    assert rows
+    for row in rows:
+        assert row["x_label"] < chart_edge_branch
+
+
+def test_leaders_stop_where_the_labels_begin() -> None:
+    """The leaders run to the label anchor rather than on to the panel edge, so
+    the dashed line meets the text instead of passing under it to the frame."""
+    out = tree_annotated_plot.plot(_auspice(), _vertical_chart(), **_on_kw())
+    text = _text_layer(out)
+    assert text is not None
+    anchors = {row["x_label"] for row in _resolve_dataset(out.to_dict(), text)}
+    assert len(anchors) == 1, f"expected one shared label anchor, got {anchors}"
+    (anchor,) = anchors
+    for row in _resolve_dataset(out.to_dict(), _leader_layer(out)):
+        assert row["x2"] == pytest.approx(anchor)

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/tests/test_reconciliation.py

@@ -73,7 +73,7 @@ def _chart_for_strains(strains: list[str], *, height: int = 200) -> alt.Chart:
     )
 
 
-# ---------- chart-not-in-tree (always fatal) ----------
+# ---------- chart-not-in-tree (fatal unless prune_chart_to_tree) ----------
 
 
 def test_chart_strain_not_in_tree_is_fatal_default() -> None:
@@ -90,9 +90,9 @@ def test_chart_strain_not_in_tree_is_fatal_default() -> None:
         )
 
 
-def test_chart_strain_not_in_tree_is_fatal_even_with_prune() -> None:
+def test_chart_strain_not_in_tree_is_fatal_with_only_tree_prune() -> None:
     """`prune_tree_to_chart=True` only drops *tree* tips. A chart strain
-    not in the tree still raises — pruning would silently lose plot data."""
+    not in the tree still raises — the two flags are orthogonal."""
     chart = _chart_for_strains(["A1", "A2", "X"])
     with pytest.raises(ValueError, match="not present in the tree"):
         tree_annotated_plot.plot(
@@ -105,6 +105,97 @@ def test_chart_strain_not_in_tree_is_fatal_even_with_prune() -> None:
         )
 
 
+def test_chart_strain_not_in_tree_succeeds_with_prune_chart_to_tree() -> None:
+    """`prune_chart_to_tree=True` filters chart rows whose strain isn't a
+    tree tip. The resulting chart's strain-axis sort matches the kept tree
+    tip order, and the dropped strain is gone from the chart's data."""
+    chart = _chart_for_strains(["A1", "A2", "A3", "B1", "B2", "X"])
+    out = tree_annotated_plot.plot(
+        _auspice_two_clades(),
+        chart,
+        chart_strain_field="strain",
+        tree_strain_field="name",
+        branch_length="div",
+        prune_chart_to_tree=True,
+    )
+    assert isinstance(out, alt.HConcatChart)
+    spec = out.to_dict()
+    # The strain-axis sort on the user-chart panel should be exactly the
+    # tree's tip order — no `X`.
+    sorts = []
+    for ch in out.hconcat:
+        ch_spec = ch.to_dict()
+        enc = ch_spec.get("encoding", {})
+        for channel in enc.values():
+            if isinstance(channel, dict) and channel.get("field") == "strain":
+                if isinstance(channel.get("sort"), list):
+                    sorts.append(channel["sort"])
+    assert sorts, "expected at least one strain-axis encoding with a sort"
+    for s in sorts:
+        assert "X" not in s
+        assert set(s) <= {"A1", "A2", "A3", "B1", "B2"}
+    # And the user-chart data (now in `datasets`) should not contain X rows.
+    for rows in (spec.get("datasets") or {}).values():
+        if isinstance(rows, list) and rows and isinstance(rows[0], dict):
+            if "strain" in rows[0]:
+                assert all(r["strain"] != "X" for r in rows)
+
+
+def test_prune_chart_to_tree_zero_overlap_raises() -> None:
+    """If pruning would drop every chart row (no overlap with tree tips),
+    raise a clear error rather than producing an empty plot."""
+    chart = _chart_for_strains(["X", "Y", "Z"])
+    with pytest.raises(ValueError, match="dropped every chart row"):
+        tree_annotated_plot.plot(
+            _auspice_two_clades(),
+            chart,
+            chart_strain_field="strain",
+            tree_strain_field="name",
+            branch_length="div",
+            prune_chart_to_tree=True,
+        )
+
+
+def test_prune_chart_and_tree_combined() -> None:
+    """Both flags may be on at once: the chart has extras (X) and the tree
+    has tips the chart lacks (B1, B2). Pruning is bidirectional."""
+    chart = _chart_for_strains(["A1", "A2", "A3", "X"])
+    out = tree_annotated_plot.plot(
+        _auspice_two_clades(),
+        chart,
+        chart_strain_field="strain",
+        tree_strain_field="name",
+        branch_length="div",
+        prune_tree_to_chart=True,
+        prune_chart_to_tree=True,
+    )
+    assert isinstance(out, alt.HConcatChart)
+    # Final intersection is {A1, A2, A3}: chart loses X, tree loses B1/B2.
+    found_sort = None
+    for ch in out.hconcat:
+        enc = ch.to_dict().get("encoding", {})
+        for channel in enc.values():
+            if isinstance(channel, dict) and channel.get("field") == "strain":
+                if isinstance(channel.get("sort"), list):
+                    found_sort = channel["sort"]
+    assert found_sort is not None
+    assert set(found_sort) == {"A1", "A2", "A3"}
+
+
+def test_prune_chart_to_tree_default_error_mentions_flag() -> None:
+    """When chart has strains not in tree and the user hasn't opted in,
+    the error message should suggest `prune_chart_to_tree=True`."""
+    chart = _chart_for_strains(["A1", "A2", "A3", "B1", "B2", "X"])
+    with pytest.raises(ValueError, match="prune_chart_to_tree=True"):
+        tree_annotated_plot.plot(
+            _auspice_two_clades(),
+            chart,
+            chart_strain_field="strain",
+            tree_strain_field="name",
+            branch_length="div",
+        )
+
+
 # ---------- tree-not-in-chart (fatal unless prune) ----------
 
 

{tree_annotated_plot-0.2.2 → tree_annotated_plot-0.4.0}/tests/test_tree_location.py

@@ -181,3 +181,55 @@ def test_right_with_x_encoded_strain_raises() -> None:
         tree_annotated_plot.plot(
             _auspice_4_tip(), _horizontal_chart(), tree_location="right", **_kw()
         )
+
+
+# ---------- spacing between the tree and chart panels ----------
+
+
+@pytest.mark.parametrize(
+    ("chart_fn", "location"),
+    [
+        (_vertical_chart, "left"),
+        (_vertical_chart, "right"),
+        (_horizontal_chart, "top"),
+        (_horizontal_chart, "bottom"),
+    ],
+)
+def test_spacing_defaults_to_zero(chart_fn, location) -> None:
+    """The default butts the two panels together, as before `spacing` existed."""
+    out = tree_annotated_plot.plot(
+        _auspice_4_tip(), chart_fn(), tree_location=location, **_kw()
+    )
+    assert out.to_dict()["spacing"] == 0
+
+
+@pytest.mark.parametrize(
+    ("chart_fn", "location"),
+    [
+        (_vertical_chart, "left"),
+        (_vertical_chart, "right"),
+        (_horizontal_chart, "top"),
+        (_horizontal_chart, "bottom"),
+    ],
+)
+def test_spacing_propagates_to_the_concat(chart_fn, location) -> None:
+    """An explicit `spacing` reaches the top-level concat spec, for every
+    `tree_location` — the gap is between the two panels, so it applies
+    uniformly to the hconcat and vconcat forms alike."""
+    out = tree_annotated_plot.plot(
+        _auspice_4_tip(), chart_fn(), tree_location=location, spacing=7, **_kw()
+    )
+    assert out.to_dict()["spacing"] == 7
+
+
+def test_spacing_does_not_disturb_panel_sizes() -> None:
+    """Spacing is applied along the branch axis, between panels, so neither
+    panel's own dimensions change and strain-row alignment is untouched."""
+    out_zero = tree_annotated_plot.plot(_auspice_4_tip(), _vertical_chart(), **_kw())
+    out_gap = tree_annotated_plot.plot(
+        _auspice_4_tip(), _vertical_chart(), spacing=12, **_kw()
+    )
+    d_zero, d_gap = out_zero.to_dict(), out_gap.to_dict()
+    for i in (0, 1):
+        assert d_zero["hconcat"][i]["width"] == d_gap["hconcat"][i]["width"]
+        assert d_zero["hconcat"][i].get("height") == d_gap["hconcat"][i].get("height")