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

{tree_annotated_plot-0.2.1 → tree_annotated_plot-0.3.0}/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.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
+
+- `mark_line`, `mark_trail`, and `mark_area` now connect points in tree
+  tip order regardless of other encodings on the chart. Previously, a
+  user chart with an explicit categorical color-scale `domain` rendered
+  with crisscrossing line segments because Vega-Lite's default
+  connection-order heuristic ignored the strain-axis sort. The package
+  now attaches a `calculate` transform that derives a per-row tip rank
+  and points the `order` channel at that field on these marks. Any
+  user-supplied `order` is left in place.
+- When `color_tree_by` is used together with a user chart that has its
+  own `color` encoding (e.g. a titer plot colored by `cell_line`), the
+  user chart's marks no longer disappear. The concat container now
+  resolves the `color` scale as `independent` so the tree's
+  `color_value:N` scale (with its tree-specific domain) is not merged
+  with the user chart's color scale.
+
 ## [0.2.1] - 2026-05-06
 
 ### Fixed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tree-annotated-plot
-Version: 0.2.1
+Version: 0.3.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
@@ -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.1 → tree_annotated_plot-0.3.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.1 → tree_annotated_plot-0.3.0}/docs/examples.md

@@ -105,8 +105,12 @@ 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.
+`node_attrs.subclade` value at each node. The package's default places
+the categorical legend at the bottom of the combined plot; here we pass
+`tree_color_legend_format={"orient": "left"}` to push it to the left
+side instead, so it doesn't compete with the cohort-selection legend
+already sitting below the chart. See "Color the tree" below for the
+full set of options.
 
 ### Optional: connect leaders all the way to the labels
 
@@ -156,8 +160,11 @@ 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.
+values render in gray. By default the legend is drawn at the bottom of
+the combined plot; the H3N2 examples in this section pass
+`tree_color_legend_format={"orient": "left"}` to move it to the left
+instead, since the bottom edge already carries the cohort-selection
+legend.
 
 The example below colors the same H3N2 chart by genotype at HA1
 site 158, which has two mutations in the tree (`N158K`, `N158D`) and
@@ -277,6 +284,7 @@ tree-annotated-plot \
     --scale-bar \
     --branch-length-units substitutions \
     --color-tree-by subclade \
+    --tree-color-legend-format '{"orient":"left"}' \
     --output examples/data/h3n2_combined.json
 ```
 
@@ -295,6 +303,7 @@ out = tree_annotated_plot.plot(
     scale_bar=True,
     branch_length_units="substitutions",
     color_tree_by="subclade",
+    tree_color_legend_format={"orient": "left"},
 )
 ```
 

{tree_annotated_plot-0.2.1 → tree_annotated_plot-0.3.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.1 → tree_annotated_plot-0.3.0}/pyproject.toml

@@ -4,15 +4,17 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tree-annotated-plot"
-version = "0.2.1"
+version = "0.3.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",
@@ -52,7 +54,7 @@ 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"

{tree_annotated_plot-0.2.1 → tree_annotated_plot-0.3.0}/scripts/generate_docs_assets.py

@@ -122,7 +122,11 @@ def _render_kikawa() -> None:
             # 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.
+            # Place the subclade legend on the left so it doesn't compete
+            # with the cohort-selection legend that already sits at the
+            # bottom of the chart.
             plot_kwargs["color_tree_by"] = "subclade"
+            plot_kwargs["tree_color_legend_format"] = {"orient": "left"}
         out = tree_annotated_plot.plot(
             DATA_DIR / f"flu-seqneut-2025to2026_{subtype}.json",
             chart,
@@ -155,6 +159,7 @@ def _render_kikawa() -> None:
         strain_label_font_size=9,
         shift_tree_loc=60,
         color_tree_by="subclade",
+        tree_color_legend_format={"orient": "left"},
     )
     _save_pair(out, "h3n2_combined_label_connect")
 
@@ -180,6 +185,7 @@ def _render_kikawa() -> None:
         scale_bar=True,
         branch_length_units="substitutions",
         color_tree_by="genotype:HA1:158",
+        tree_color_legend_format={"orient": "left"},
     )
     _save_pair(out, "h3n2_combined_genotype_158")
 

{tree_annotated_plot-0.2.1 → tree_annotated_plot-0.3.0}/src/tree_annotated_plot/_config.py

@@ -109,9 +109,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[

{tree_annotated_plot-0.2.1 → tree_annotated_plot-0.3.0}/src/tree_annotated_plot/_plot.py

@@ -55,6 +55,7 @@ def plot(
     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,
@@ -82,6 +83,7 @@ def plot(
             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 +170,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,
     )
@@ -233,6 +256,28 @@ def _build(
             ch.axis = alt.Axis(labels=False, ticks=False, domain=False, title=None)
         n_hits += 1
     _check_walker_hits("strain-axis update", n_hits, len(axis_hits), axis)
+
+    # Pin line/trail/area connection order to tip order via Vega-Lite's
+    # `order` channel. Without this, an explicit categorical `color` scale
+    # `domain` (or other encoding choices) can shift Vega-Lite's
+    # connection-order heuristic away from the strain-axis sort, causing
+    # lines to crisscross. The order channel's `sort` only accepts
+    # ascending/descending, so we attach a `calculate` transform that
+    # computes a per-row tip rank and point `order` at that derived
+    # quantitative field. User-supplied `order` always wins.
+    rank_expr = (
+        f"indexof({json.dumps(list(tip_names))}, "
+        f"datum[{json.dumps(config.chart_strain_field)}])"
+    )
+    for node in _iter_connection_order_nodes(new_chart, config.chart_strain_field):
+        enc = _live_attr(node, "encoding")
+        if _live_attr(enc, "order") is not None:
+            continue
+        existing = _live_attr(node, "transform") or []
+        node.transform = list(existing) + [
+            {"calculate": rank_expr, "as": _TIP_ORDER_RANK_FIELD}
+        ]
+        enc.order = alt.Order(f"{_TIP_ORDER_RANK_FIELD}:Q")
     hoisted_config, hoisted_other = _pop_toplevel_only_attrs(new_chart)
 
     combined = _concat_for_location(
@@ -276,22 +321,32 @@ def _concat_for_location(
     user_chart: alt.TopLevelMixin,
     location: TreeLocation,
 ) -> alt.HConcatChart | alt.VConcatChart:
-    """Concat tree and chart in the order implied by the tree's location."""
+    """Concat tree and chart in the order implied by the tree's location.
+
+    The strain axis is resolved independent so the tree and chart can use
+    different scales on that axis (the tree's branch length vs. the chart's
+    measurement value), while still sharing the orthogonal strain axis. The
+    `color` scale is also resolved independent: when ``color_tree_by`` is set
+    the tree panel emits a `color_value:N` color scale with a tree-specific
+    domain, and Vega-Lite's default of sharing color across concat views
+    would merge it with any color encoding on the user's chart, hiding
+    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(
-            y="independent"
+            y="independent", color="independent"
         )
     if location == "right":
         return alt.hconcat(user_chart, tree_chart, spacing=0).resolve_scale(
-            y="independent"
+            y="independent", color="independent"
         )
     if location == "top":
         return alt.vconcat(tree_chart, user_chart, spacing=0).resolve_scale(
-            x="independent"
+            x="independent", color="independent"
         )
     if location == "bottom":
         return alt.vconcat(user_chart, tree_chart, spacing=0).resolve_scale(
-            x="independent"
+            x="independent", color="independent"
         )
     raise ValueError(f"unreachable: tree_location={location!r}")
 
@@ -609,6 +664,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`.
 
@@ -676,13 +795,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`.)
@@ -696,7 +818,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(
@@ -716,6 +840,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,
         )
     )
@@ -730,14 +855,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(
@@ -751,7 +878,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]}")
@@ -999,6 +1126,65 @@ def _live_attr(obj: Any, name: str) -> Any:
     return v
 
 
+# Vega-Lite marks whose drawing order along the discrete axis is determined
+# by the order channel (rule 1 of the connection-order fallback chain). For
+# these marks pinning the order channel to a per-row tip-order rank ensures
+# the line / trail / area connects strains in tip order regardless of how
+# Vega-Lite would otherwise resolve the fallback (e.g. when an explicit
+# color-scale `domain` shifts it away from the y-axis sort).
+_CONNECTION_ORDER_MARKS = frozenset({"line", "trail", "area"})
+
+# Derived field name appended to each connection-order mark's transform
+# pipeline. Chosen to be unlikely to collide with user data; private prefix
+# makes the intent clear if anyone inspects the rendered spec.
+_TIP_ORDER_RANK_FIELD = "_tap_strain_order_idx"
+
+
+def _mark_type(node: Any) -> str | None:
+    """Return the mark type string for a chart node, or None.
+
+    Handles altair's two mark forms: the plain string (e.g. ``"line"`` from
+    ``chart.mark_line()``) and the ``MarkDef`` object (e.g. from
+    ``chart.mark_line(point=True)``). Container nodes (LayerChart,
+    HConcatChart, etc.) have no mark and return None.
+    """
+    mark = _live_attr(node, "mark")
+    if mark is None:
+        return None
+    if isinstance(mark, str):
+        return mark
+    type_ = _live_attr(mark, "type")
+    return type_ if isinstance(type_, str) else None
+
+
+def _iter_connection_order_nodes(node: Any, chart_strain_field: str) -> Iterator[Any]:
+    """Yield the live chart node for every node whose mark is in
+    ``_CONNECTION_ORDER_MARKS`` and whose ``x``/``y`` strain encoding
+    matches ``chart_strain_field``.
+
+    Mirrors `_iter_strain_axis_channels`'s traversal (hconcat / vconcat /
+    concat / layer / spec descent). Yields the node itself (not just the
+    encoding) so the caller can attach both a ``calculate`` transform and
+    the ``order`` channel.
+    """
+    if _mark_type(node) in _CONNECTION_ORDER_MARKS:
+        enc = _live_attr(node, "encoding")
+        if enc is not None:
+            for channel in ("x", "y"):
+                ch = _live_attr(enc, channel)
+                if ch is not None and _channel_field(ch) == chart_strain_field:
+                    yield node
+                    break
+    for attr in ("hconcat", "vconcat", "concat", "layer"):
+        sub = _live_attr(node, attr)
+        if isinstance(sub, list):
+            for s in sub:
+                yield from _iter_connection_order_nodes(s, chart_strain_field)
+    spec = _live_attr(node, "spec")
+    if spec is not None:
+        yield from _iter_connection_order_nodes(spec, chart_strain_field)
+
+
 def _pop_toplevel_only_attrs(
     chart: alt.TopLevelMixin,
 ) -> tuple[Any, dict]:

{tree_annotated_plot-0.2.1 → tree_annotated_plot-0.3.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.1 → tree_annotated_plot-0.3.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"])

{tree_annotated_plot-0.2.1 → tree_annotated_plot-0.3.0}/tests/test_color_tree.py

@@ -663,6 +663,40 @@ def test_color_tree_by_legend_hides_internal_only_unknown():
         assert "unknown" in enc["scale"]["domain"]
 
 
+def test_color_tree_by_color_scale_independent_from_user_chart():
+    """When the tree is colored, the concat container must resolve the color
+    scale as `independent` so the tree's `color_value:N` scale doesn't merge
+    with a user-chart color encoding (which would hide user marks whose
+    color values aren't in the tree's domain)."""
+    df = pd.DataFrame(
+        {
+            "strain": ["A", "B", "C", "D"] * 2,
+            "titer": [1.0, 2.0, 4.0, 8.0, 1.5, 2.5, 4.5, 8.5],
+            "cell_line": ["X", "X", "X", "X", "Y", "Y", "Y", "Y"],
+        }
+    )
+    user_chart = (
+        alt.Chart(df)
+        .mark_line(point=True)
+        .encode(
+            x="titer:Q",
+            y=alt.Y("strain:N"),
+            color=alt.Color("cell_line:N"),
+        )
+        .properties(width=200, height=200)
+    )
+    out = tree_annotated_plot.plot(
+        _attr_auspice(),
+        user_chart,
+        **_kw(),
+        color_tree_by="subclade",
+    )
+    spec = out.to_dict()
+    resolve = spec.get("resolve") or {}
+    scale = resolve.get("scale") or {}
+    assert scale.get("color") == "independent"
+
+
 # -----------------------------------------------------------------------------
 # CLI
 # -----------------------------------------------------------------------------

tree_annotated_plot-0.3.0/tests/test_line_order.py

@@ -0,0 +1,258 @@
+"""Connection order on `mark_line` / `mark_trail` / `mark_area` follows tip order.
+
+Regression: when the user chart had `mark_line` with strain on a discrete
+axis, lines connected points in tip order most of the time — but adding an
+explicit categorical color-scale `domain` shifted Vega-Lite's default
+connection-order heuristic away from the strain-axis `sort`, causing lines
+to crisscross. The package now sets the `order` channel to a per-row
+tip-rank field on these marks (unless the user has set their own `order`),
+pinning rule 1 of the Vega-Lite fallback chain.
+
+The tip-rank is computed via a `calculate` transform that runs `indexof`
+against the tip-names list — Vega-Lite's `order` channel `sort` only
+accepts ascending/descending, so a derived quantitative field is the
+direct way to express custom ordering.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import altair as alt
+import pandas as pd
+import pytest
+
+import tree_annotated_plot
+from tree_annotated_plot._plot import _TIP_ORDER_RANK_FIELD
+
+
+def _synthetic_auspice() -> dict:
+    """4-tip Auspice tree; tip layout order is [A, B, C, D]."""
+    return {
+        "version": "v2",
+        "meta": {},
+        "tree": {
+            "name": "ROOT",
+            "node_attrs": {"div": 0.0},
+            "children": [
+                {
+                    "name": "int1",
+                    "node_attrs": {"div": 0.01},
+                    "children": [
+                        {"name": "A", "node_attrs": {"div": 0.04}},
+                        {"name": "B", "node_attrs": {"div": 0.05}},
+                    ],
+                },
+                {
+                    "name": "int2",
+                    "node_attrs": {"div": 0.02},
+                    "children": [
+                        {"name": "C", "node_attrs": {"div": 0.03}},
+                        {"name": "D", "node_attrs": {"div": 0.06}},
+                    ],
+                },
+            ],
+        },
+    }
+
+
+TIP_ORDER = ["A", "B", "C", "D"]
+
+
+def _df() -> pd.DataFrame:
+    return pd.DataFrame(
+        [
+            {"strain": s, "serum": serum, "titer": v}
+            for s, serum, v in [
+                ("A", "s1", 100),
+                ("B", "s1", 200),
+                ("C", "s1", 400),
+                ("D", "s1", 800),
+                ("A", "s2", 150),
+                ("B", "s2", 250),
+                ("C", "s2", 350),
+                ("D", "s2", 700),
+            ]
+        ]
+    )
+
+
+def _plot_user_panel(chart: alt.TopLevelMixin) -> dict:
+    """Run plot() with default settings and return the user-panel spec dict."""
+    out = tree_annotated_plot.plot(
+        _synthetic_auspice(),
+        chart,
+        chart_strain_field="strain",
+        tree_strain_field="name",
+        branch_length="div",
+    )
+    # Default tree_location for y-axis strain is "left" — user panel is hconcat[1].
+    return out.to_dict()["hconcat"][1]
+
+
+def _find_order_encodings(spec: Any) -> list[dict]:
+    """Walk a spec dict and return every `encoding.order` dict found."""
+    found: list[dict] = []
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            enc = node.get("encoding")
+            if isinstance(enc, dict) and "order" in enc:
+                found.append(enc["order"])
+            for k, v in node.items():
+                if k != "encoding":
+                    walk(v)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(spec)
+    return found
+
+
+def _find_tip_rank_transforms(spec: Any) -> list[dict]:
+    """Walk a spec dict and return every calculate transform that computes
+    the package's tip-rank derived field."""
+    found: list[dict] = []
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            transforms = node.get("transform")
+            if isinstance(transforms, list):
+                for t in transforms:
+                    if isinstance(t, dict) and t.get("as") == _TIP_ORDER_RANK_FIELD:
+                        found.append(t)
+            for v in node.values():
+                walk(v)
+        elif isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(spec)
+    return found
+
+
+def _assert_tip_rank_wired(spec: dict) -> None:
+    """Spec contains both an order-channel pointing at the tip-rank field
+    and a calculate transform that derives that field from the tip names."""
+    orders = _find_order_encodings(spec)
+    assert len(orders) == 1, f"expected one order encoding, got {orders}"
+    assert orders[0]["field"] == _TIP_ORDER_RANK_FIELD
+    assert orders[0]["type"] == "quantitative"
+    transforms = _find_tip_rank_transforms(spec)
+    assert len(transforms) == 1, f"expected one tip-rank transform, got {transforms}"
+    expr = transforms[0]["calculate"]
+    assert "indexof" in expr
+    # The expression embeds the tip names list verbatim.
+    for tip in TIP_ORDER:
+        assert f'"{tip}"' in expr, f"tip {tip!r} not in calculate expression {expr!r}"
+
+
+def test_mark_line_with_color_domain_gets_order_in_tip_order():
+    """The original bug: explicit color-scale `domain` no longer crisscrosses lines."""
+    chart = (
+        alt.Chart(_df())
+        .mark_line(point=True)
+        .encode(
+            x=alt.X("titer:Q", scale=alt.Scale(type="log")),
+            y=alt.Y("strain:N"),
+            color=alt.Color(
+                "serum:N",
+                scale=alt.Scale(domain=["s1", "s2"], range=["red", "blue"]),
+            ),
+        )
+        .properties(width=300, height=200)
+    )
+    _assert_tip_rank_wired(_plot_user_panel(chart))
+
+
+def test_user_supplied_order_is_preserved():
+    """User-supplied `order` always wins; the package never overwrites it."""
+    chart = (
+        alt.Chart(_df())
+        .mark_line()
+        .encode(
+            x=alt.X("titer:Q"),
+            y=alt.Y("strain:N"),
+            color="serum:N",
+            order=alt.Order("titer:Q", sort="ascending"),
+        )
+        .properties(width=300, height=200)
+    )
+    spec = _plot_user_panel(chart)
+    orders = _find_order_encodings(spec)
+    assert len(orders) == 1
+    assert orders[0]["field"] == "titer"
+    # The package did not attach its tip-rank transform either.
+    assert _find_tip_rank_transforms(spec) == []
+
+
+@pytest.mark.parametrize("mark_method", ["mark_line", "mark_area", "mark_trail"])
+def test_connection_order_marks_get_order_in_tip_order(mark_method: str):
+    """All three connection-order marks (line / area / trail) get `order` injected."""
+    base = alt.Chart(_df()).encode(
+        x=alt.X("titer:Q"),
+        y=alt.Y("strain:N"),
+        color="serum:N",
+    )
+    chart = getattr(base, mark_method)().properties(width=300, height=200)
+    _assert_tip_rank_wired(_plot_user_panel(chart))
+
+
+def test_layered_chart_only_line_layer_gets_order():
+    """Mixed-mark layers: line layer gets `order`, circle layer is untouched."""
+    base = alt.Chart(_df()).encode(
+        x=alt.X("titer:Q"),
+        y=alt.Y("strain:N"),
+        color="serum:N",
+    )
+    layered = (base.mark_line() + base.mark_circle()).properties(width=300, height=200)
+    _assert_tip_rank_wired(_plot_user_panel(layered))
+
+
+def test_no_connection_order_marks_means_no_order_injected():
+    """A chart with only point/circle/etc. marks is a no-op for the walker."""
+    chart = (
+        alt.Chart(_df())
+        .mark_circle()
+        .encode(
+            x=alt.X("titer:Q"),
+            y=alt.Y("strain:N"),
+            color="serum:N",
+        )
+        .properties(width=300, height=200)
+    )
+    spec = _plot_user_panel(chart)
+    assert _find_order_encodings(spec) == []
+    assert _find_tip_rank_transforms(spec) == []
+
+
+def test_faceted_chart_gets_order_injection():
+    """The walker descends into the inner spec of a faceted chart."""
+    df_facet = pd.DataFrame(
+        [
+            {"strain": s, "serum": serum, "panel": p, "titer": v}
+            for s, serum, p, v in [
+                ("A", "s1", "P1", 100),
+                ("B", "s1", "P1", 200),
+                ("C", "s1", "P1", 400),
+                ("D", "s1", "P1", 800),
+                ("A", "s1", "P2", 150),
+                ("B", "s1", "P2", 250),
+                ("C", "s1", "P2", 350),
+                ("D", "s1", "P2", 700),
+            ]
+        ]
+    )
+    base = (
+        alt.Chart(df_facet)
+        .mark_line()
+        .encode(
+            x=alt.X("titer:Q"),
+            y=alt.Y("strain:N"),
+            color="serum:N",
+        )
+        .properties(width=300, height=200)
+    )
+    faceted = base.facet(facet="panel:N", columns=2)
+    _assert_tip_rank_wired(_plot_user_panel(faceted))

{tree_annotated_plot-0.2.1 → tree_annotated_plot-0.3.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) ----------