tree-annotated-plot 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

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.",
@@ -152,11 +161,34 @@ class PlotConfig:
         "when `connect_leader_to_label` is on.",
     ] = "normal"
 
+    strain_label_styles: Annotated[
+        list[dict[str, Any]] | None,
+        "Style a subset of the strain labels rendered in the tree panel; "
+        "requires `connect_leader_to_label`. A list of rules, each a dict "
+        'with keys "strains" (a list of tip identifiers, i.e. '
+        '`tree_strain_field` values), "style" and, optionally, "when". '
+        '"style" holds Vega-Lite text-mark properties: "fill" (a color), '
+        '"opacity" (0 to 1), "fontWeight" ("normal", "bold", or 100-900) '
+        'and "fontStyle" ("normal" or "italic"). "when" is a Vega '
+        "expression that turns the rule on while it is truthy, usually just "
+        "the name of a parameter declared in the chart (e.g. one bound to a "
+        "checkbox), but any expression works (e.g. \"emphasis == 'cell'\" "
+        'for a radio button). Without "when" the style always applies. '
+        "Where rules overlap, later rules win property by property; "
+        "properties no rule sets keep `strain_label_font_weight` and the "
+        "default black, upright text. A strain that isn't a tree tip is an "
+        "error; strains dropped by `prune_tree_to_chart` are skipped. CLI "
+        "form: a JSON array (quote the whole argument), e.g. "
+        '\'[{"strains": ["K"], "style": {"fill": "#d62728", '
+        '"fontWeight": "bold"}, "when": "vaccine_strains"}]\'.',
+    ] = None
+
     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[
@@ -215,10 +247,25 @@ class PlotConfig:
 
 
 # Sidecar for Python-docstring-only prose, keyed by PlotConfig field name.
-# Empty by default — add an entry when a field's docstring entry needs more
-# than the CLI `--help` text covers. The extras are appended to the field's
-# description in `tree_annotated_plot.plot.__doc__`, never in CLI --help.
-PARAM_DOC_EXTRAS: dict[str, str] = {}
+# Add an entry when a field's docstring entry needs more than the CLI
+# `--help` text covers. The extras are appended to the field's description in
+# `tree_annotated_plot.plot.__doc__`, never in CLI --help.
+PARAM_DOC_EXTRAS: dict[str, str] = {
+    "strain_label_styles": (
+        'In Python, "when" may also be an `altair.Parameter`, e.g. '
+        '`alt.param(name="vaccine_strains", value=True, '
+        "bind=alt.binding_checkbox())`, which is declared on the returned "
+        "chart if your chart doesn't already declare it; or an altair "
+        'parameter expression such as `emphasis == "cell"`. Only a bare '
+        "`altair.Parameter` is declared for you: parameters that an "
+        "expression refers to must be declared on the chart, and an "
+        "expression other than a bare name isn't checked until the chart "
+        "renders. A bare name or parameter must be a variable parameter: "
+        "selection parameters are rejected, since the label data doesn't "
+        "carry the fields a selection tests. Any iterable of strings (e.g. "
+        'a pandas Series) works for "strains".'
+    ),
+}
 
 
 # Descriptions for the three data-input parameters. These can't live on

tree_annotated_plot/_label_style.py

@@ -0,0 +1,349 @@
+"""Per-strain styling of the tree-panel strain labels (`strain_label_styles`).
+
+Public entry points: :func:`resolve_rules` validates and normalizes the
+user's rules, and :func:`mark_props` turns them into label mark properties.
+
+Each rule names some strains, a style (a subset of Vega-Lite text-mark
+properties) and, optionally, a `when` condition. Every property a rule sets
+becomes one `alt.ExprRef` on the existing label mark(s), evaluated per label:
+Vega-Lite compiles a mark-level ``{"expr": ...}`` into the Vega encode block,
+where ``datum`` is the label's row. That is why a property with no encoding
+channel (``fontWeight``, ``fontStyle``) can still vary by strain without
+duplicating the label layers. Which rules a label belongs to is carried in
+one boolean column per rule (:func:`membership_column`) on the label data.
+
+``fontSize`` is deliberately not a style key: the label strip's width is
+estimated from `strain_label_font_size`, so a per-strain size would need a
+different layout calculation.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+import altair as alt
+from altair.expr.core import Expression
+
+# Allowed `style` keys, in the order their expressions are emitted.
+STYLE_KEYS = ("fill", "opacity", "fontWeight", "fontStyle")
+
+# Style keys that change the glyph outline. The white halo layer drawn under
+# each label has to follow these so it keeps masking the leader exactly where
+# the text is; `fill` and `opacity` apply to the visible text only.
+_GLYPH_KEYS = frozenset({"fontWeight", "fontStyle"})
+
+_RULE_KEYS = frozenset({"strains", "style", "when"})
+
+_FONT_WEIGHTS = ("normal", "bold")
+_NUMERIC_FONT_WEIGHTS = tuple(range(100, 1000, 100))
+_FONT_STYLES = ("normal", "italic")
+
+# Hints for style keys a user is likely to reach for that we don't accept.
+_STYLE_KEY_HINTS = {
+    "color": 'use "fill" to set the label color',
+    "fontSize": (
+        "per-strain font sizes are not supported because they change the "
+        "label-strip layout; use `strain_label_font_size` for all labels"
+    ),
+}
+
+# A bare Vega expression identifier, i.e. what a param name looks like.
+_IDENTIFIER = re.compile(r"[A-Za-z_$][A-Za-z0-9_$]*")
+
+
+@dataclass(frozen=True)
+class LabelStyleRule:
+    """One validated `strain_label_styles` rule.
+
+    `strains` holds only the strains drawn in the tree (pruned ones are
+    dropped); `when` is a Vega expression string, or None for always-on.
+    """
+
+    strains: frozenset[str]
+    style: dict[str, Any]
+    when: str | None
+
+
+def membership_column(index: int) -> str:
+    """Name of the boolean label-data column marking rule `index`'s strains."""
+    return f"_tap_label_style_{index}"
+
+
+def resolve_rules(
+    raw: Any,
+    *,
+    input_tip_names: Iterable[str],
+    drawn_tip_names: Iterable[str],
+    chart_spec: dict,
+    tree_strain_field: str,
+) -> tuple[list[LabelStyleRule], list[alt.Parameter]]:
+    """Validate `strain_label_styles` and return ``(rules, params_to_declare)``.
+
+    `input_tip_names` are the tree's tips before `prune_tree_to_chart`; a
+    strain outside them is an error. `drawn_tip_names` are the tips left
+    after pruning; strains pruned away are silently dropped from their rule.
+    `params_to_declare` lists the `alt.Parameter` objects passed as `when`
+    that the chart doesn't already declare, deduplicated by name.
+    """
+    if raw is None:
+        return [], []
+    if isinstance(raw, (str, bytes, Mapping)) or not isinstance(raw, Iterable):
+        raise ValueError(
+            "strain_label_styles must be a list of rule dicts, each with "
+            f'"strains" and "style" keys; got {type(raw).__name__}.'
+        )
+    raw_rules = list(raw)
+    if not raw_rules:
+        return [], []
+
+    input_tips = set(input_tip_names)
+    drawn_tips = set(drawn_tip_names)
+    declared = _declared_params(chart_spec)
+    rule_params: dict[str, alt.Parameter] = {}
+    for rule in raw_rules:
+        when = rule.get("when") if isinstance(rule, Mapping) else None
+        if isinstance(when, alt.Parameter):
+            rule_params.setdefault(_param_name(when), when)
+
+    rules: list[LabelStyleRule] = []
+    for i, rule in enumerate(raw_rules):
+        if not isinstance(rule, Mapping):
+            raise ValueError(
+                f"strain_label_styles[{i}] must be a dict with "
+                f'"strains" and "style" keys; got {type(rule).__name__}.'
+            )
+        unknown_keys = set(rule) - _RULE_KEYS
+        if unknown_keys:
+            raise ValueError(
+                f"strain_label_styles[{i}] has unknown key(s) "
+                f"{sorted(unknown_keys)}; allowed keys are "
+                f"{sorted(_RULE_KEYS)}."
+            )
+        for required in ("strains", "style"):
+            if required not in rule:
+                raise ValueError(
+                    f"strain_label_styles[{i}] is missing the required "
+                    f"{required!r} key."
+                )
+        rules.append(
+            LabelStyleRule(
+                strains=_resolve_strains(
+                    i,
+                    rule["strains"],
+                    input_tips=input_tips,
+                    drawn_tips=drawn_tips,
+                    tree_strain_field=tree_strain_field,
+                ),
+                style=_validate_style(i, rule["style"]),
+                when=_resolve_when(
+                    i,
+                    rule.get("when"),
+                    declared=declared,
+                    rule_param_names=set(rule_params),
+                ),
+            )
+        )
+
+    to_declare = [p for name, p in rule_params.items() if name not in declared]
+    return rules, to_declare
+
+
+def mark_props(
+    rules: list[LabelStyleRule], *, default_font_weight: str
+) -> tuple[dict[str, alt.ExprRef], dict[str, alt.ExprRef]]:
+    """Return ``(halo_props, text_props)``: mark properties for the label layers.
+
+    Only properties that some rule sets get an expression; the rest keep the
+    marks' static settings. Each expression is a chain of ternaries built in
+    rule order, so the last rule's test is evaluated first and later rules
+    win where strains overlap. The fallback is the label's unstyled value:
+    `default_font_weight` for ``fontWeight``, and Vega-Lite's text defaults
+    (black, fully opaque, upright) for the others.
+    """
+    defaults = {
+        "fill": "black",
+        "opacity": 1,
+        "fontWeight": default_font_weight,
+        "fontStyle": "normal",
+    }
+    text_props: dict[str, alt.ExprRef] = {}
+    for key in STYLE_KEYS:
+        expr = json.dumps(defaults[key])
+        styled = False
+        for i, rule in enumerate(rules):
+            if key not in rule.style:
+                continue
+            test = f"datum[{json.dumps(membership_column(i))}]"
+            if rule.when is not None:
+                test = f"({rule.when}) && {test}"
+            expr = f"{test} ? {json.dumps(rule.style[key])} : ({expr})"
+            styled = True
+        if styled:
+            text_props[key] = alt.ExprRef(expr)
+    halo_props = {k: v for k, v in text_props.items() if k in _GLYPH_KEYS}
+    return halo_props, text_props
+
+
+def _resolve_strains(
+    index: int,
+    strains: Any,
+    *,
+    input_tips: set[str],
+    drawn_tips: set[str],
+    tree_strain_field: str,
+) -> frozenset[str]:
+    if isinstance(strains, (str, bytes, Mapping)) or not isinstance(strains, Iterable):
+        raise ValueError(
+            f'strain_label_styles[{index}]["strains"] must be a list of '
+            f"strain names; got {type(strains).__name__} {strains!r}."
+        )
+    strains = list(strains)
+    if not strains:
+        raise ValueError(
+            f'strain_label_styles[{index}]["strains"] is empty; a rule must '
+            "name at least one strain."
+        )
+    non_str = [s for s in strains if not isinstance(s, str)]
+    if non_str:
+        raise ValueError(
+            f'strain_label_styles[{index}]["strains"] must contain strings; '
+            f"got {non_str[:5]!r}."
+        )
+    unknown = sorted(set(strains) - input_tips)
+    if unknown:
+        raise ValueError(
+            f'strain_label_styles[{index}]["strains"] has {len(unknown)} '
+            "strain(s) that are not tips of the tree under "
+            f"tree_strain_field={tree_strain_field!r}.\n"
+            f"Sample unknown strains: {unknown[:5]}\n"
+            f"Sample tree tips:       {sorted(input_tips)[:5]}"
+        )
+    return frozenset(s for s in strains if s in drawn_tips)
+
+
+def _validate_style(index: int, style: Any) -> dict[str, Any]:
+    where = f'strain_label_styles[{index}]["style"]'
+    if not isinstance(style, Mapping) or not style:
+        raise ValueError(
+            f"{where} must be a non-empty dict of label properties (any of "
+            f"{list(STYLE_KEYS)}); got {style!r}."
+        )
+    for key, value in style.items():
+        if key not in STYLE_KEYS:
+            hint = _STYLE_KEY_HINTS.get(key)
+            raise ValueError(
+                f"{where} has unsupported key {key!r}; allowed keys are "
+                f"{list(STYLE_KEYS)}." + (f" Hint: {hint}." if hint else "")
+            )
+        if key == "fill":
+            ok = isinstance(value, str) and bool(value.strip())
+            expected = "a non-empty color string"
+        elif key == "opacity":
+            ok = (
+                isinstance(value, (int, float))
+                and not isinstance(value, bool)
+                and math.isfinite(value)
+                and 0 <= value <= 1
+            )
+            expected = "a number from 0 to 1"
+        elif key == "fontWeight":
+            ok = value in _FONT_WEIGHTS or (
+                isinstance(value, int)
+                and not isinstance(value, bool)
+                and value in _NUMERIC_FONT_WEIGHTS
+            )
+            expected = f"one of {list(_FONT_WEIGHTS)} or 100-900 in steps of 100"
+        else:  # fontStyle
+            ok = value in _FONT_STYLES
+            expected = f"one of {list(_FONT_STYLES)}"
+        if not ok:
+            raise ValueError(f"{where}[{key!r}] must be {expected}; got {value!r}.")
+    return dict(style)
+
+
+def _resolve_when(
+    index: int,
+    when: Any,
+    *,
+    declared: dict[str, dict],
+    rule_param_names: set[str],
+) -> str | None:
+    """Return `when` as a Vega expression string (None means always on)."""
+    where = f'strain_label_styles[{index}]["when"]'
+    if when is None:
+        return None
+    if isinstance(when, alt.Parameter):
+        if when.param_type != "variable":
+            raise ValueError(
+                f"{where} is a selection parameter ({_param_name(when)!r}); "
+                "only variable parameters (alt.param(...), e.g. bound to a "
+                "checkbox) are supported, since the label data doesn't carry "
+                "the fields a selection tests."
+            )
+        return _param_name(when)
+    if isinstance(when, alt.ParameterExpression):
+        expr = when.to_dict().get("expr")
+    elif isinstance(when, Expression):
+        expr = when.to_dict()
+    elif isinstance(when, str):
+        expr = when
+    else:
+        raise ValueError(
+            f"{where} must be a param name or Vega expression string, an "
+            "alt.Parameter, or an altair parameter expression; got "
+            f"{type(when).__name__}."
+        )
+    if not isinstance(expr, str) or not expr.strip():
+        raise ValueError(f"{where} must not be empty; got {when!r}.")
+    expr = expr.strip()
+    if _IDENTIFIER.fullmatch(expr) and expr not in rule_param_names:
+        if expr not in declared:
+            raise ValueError(
+                f"{where}={expr!r} names no parameter declared in the chart. "
+                f"Declared parameters: {sorted(declared) or 'none'}. Declare "
+                "it on the chart (e.g. chart.add_params(alt.param(name="
+                f"{expr!r}, value=True, bind=alt.binding_checkbox()))) before "
+                "saving it, or, in Python, pass the alt.Parameter itself."
+            )
+        if "select" in declared[expr]:
+            raise ValueError(
+                f"{where}={expr!r} is a selection parameter; only variable "
+                "parameters (e.g. bound to a checkbox) are supported, since "
+                "the label data doesn't carry the fields a selection tests."
+            )
+    return expr
+
+
+def _declared_params(spec: Any) -> dict[str, dict]:
+    """Map every param name declared anywhere in a chart spec to its definition."""
+    found: dict[str, dict] = {}
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            params = node.get("params")
+            if isinstance(params, list):
+                for p in params:
+                    if isinstance(p, dict) and isinstance(p.get("name"), str):
+                        found.setdefault(p["name"], p)
+            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)
+    return found
+
+
+def _param_name(param: alt.Parameter) -> str:
+    name = param.name
+    if hasattr(name, "to_dict"):
+        name = name.to_dict()
+    return str(name)

tree_annotated_plot/_plot.py

@@ -15,7 +15,7 @@ from typing import Any, Literal
 import altair as alt
 import pandas as pd
 
-from . import _color, _config, _tree
+from . import _color, _config, _label_style, _tree
 from ._config import PlotConfig, TreeLocation
 
 # Vega-Lite `orient` values that anchor the legend to the chart's left or
@@ -49,6 +49,7 @@ 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,
@@ -60,6 +61,7 @@ def plot(
     connect_leader_to_label: bool = False,
     strain_label_font_size: float = 10.0,
     strain_label_font_weight: Literal["normal", "bold"] = "normal",
+    strain_label_styles: list[dict[str, Any]] | None = None,
     shift_tree_loc: int = 0,
     color_tree_by: str | None = None,
     tree_color_scale: dict[str, str] | None = None,
@@ -77,6 +79,7 @@ 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,
@@ -88,6 +91,7 @@ def plot(
             connect_leader_to_label=connect_leader_to_label,
             strain_label_font_size=strain_label_font_size,
             strain_label_font_weight=strain_label_font_weight,
+            strain_label_styles=strain_label_styles,
             shift_tree_loc=shift_tree_loc,
             color_tree_by=color_tree_by,
             tree_color_scale=tree_color_scale,
@@ -122,10 +126,12 @@ _PLOT_DOC_FOOTER = """
 Returns
 -------
 altair.HConcatChart | altair.VConcatChart
-    For vertical layout (chart strain on `y`), an `HConcatChart` with the
-    tree on the left and the user's chart on the right. For horizontal
-    layout (chart strain on `x`), a `VConcatChart` with the tree on top
-    and the chart below.
+    For vertical layout (chart strain on `y`), an `HConcatChart` whose
+    panels are the tree then the chart for `tree_location="left"` (the
+    default), or the chart then the tree for `"right"`. For horizontal
+    layout (chart strain on `x`), a `VConcatChart` whose panels are the
+    chart then the tree for `tree_location="bottom"` (the default), or the
+    tree then the chart for `"top"`.
 """
 
 
@@ -147,6 +153,14 @@ def _build(
     set on a config object); `config` carries every styling / behavior
     knob. Both surfaces converge here so they can never disagree.
     """
+    if config.strain_label_styles and not config.connect_leader_to_label:
+        raise ValueError(
+            "strain_label_styles styles the strain labels rendered in the "
+            "tree panel, which exist only when connect_leader_to_label=True. "
+            "With it off, the strain labels are your chart's own axis labels; "
+            "style those with Vega-Lite's conditional axis-label properties "
+            "(e.g. labelColor / labelFontWeight expressions on datum.value)."
+        )
     root, auspice_meta = _ensure_tree(
         tree,
         config.tree_strain_field,
@@ -155,6 +169,9 @@ def _build(
     )
     tip_list = _tree.layout(root)
     tip_names = [t.name for t in tip_list]
+    # Kept for `strain_label_styles` validation: a styled strain must be a tip
+    # of the input tree even if `prune_tree_to_chart` later drops it.
+    input_tip_names = list(tip_names)
 
     _check_no_duplicate_tip_strains(
         tip_names, tree_strain_field=config.tree_strain_field
@@ -206,6 +223,14 @@ def _build(
         tip_list = _tree.layout(root)
         tip_names = [t.name for t in tip_list]
 
+    label_style_rules, label_style_params = _label_style.resolve_rules(
+        config.strain_label_styles,
+        input_tip_names=input_tip_names,
+        drawn_tip_names=tip_names,
+        chart_spec=spec,
+        tree_strain_field=config.tree_strain_field,
+    )
+
     strain_dim = _coerce_dim(
         _chart_strain_dim(spec, axis_hits, axis), n_tips=len(tip_names)
     )
@@ -240,6 +265,7 @@ def _build(
         connect_leader_to_label=config.connect_leader_to_label,
         strain_label_font_size=config.strain_label_font_size,
         strain_label_font_weight=config.strain_label_font_weight,
+        label_style_rules=label_style_rules,
         shift_tree_loc=config.shift_tree_loc,
         tip_names=tip_names,
         color_mapping=color_mapping,
@@ -281,11 +307,23 @@ 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():
         combined._kwds[k] = v
+    # Declare any `when` parameter the user's chart doesn't already declare.
+    # Appended to the top-level `params` directly: `combined.add_params(...)`
+    # pushes params down into each sub-chart instead, which raises on charts
+    # loaded from a spec (e.g. a `FacetSpec` has no `add_params`).
+    if label_style_params:
+        existing = _live_attr(combined, "params") or []
+        combined._kwds["params"] = list(existing) + [
+            p.param for p in label_style_params
+        ]
     return combined
 
 
@@ -320,6 +358,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.
 
@@ -333,19 +372,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}")
@@ -384,9 +423,15 @@ def _load_chart(chart_input: ChartInput, *, strict_version: bool) -> alt.TopLeve
     A live `alt.TopLevelMixin` is returned as-is — its `$schema` is
     irrelevant since the constructing altair version is necessarily the
     running altair version. For dict / JSON path / HTML path inputs we run
-    the Vega-Lite version check (under `strict_version`), strip altair's
-    `params[].views` round-trip annotations, and then dispatch to the right
-    chart subclass via `alt.Chart.from_dict(...)`.
+    the Vega-Lite version check (under `strict_version`) and then dispatch to
+    the right chart subclass via `alt.Chart.from_dict(...)`.
+
+    The spec goes to `from_dict` unmodified. In particular, each selection
+    param's `views` must survive: when `_build` nests a compound chart (layer
+    / facet / concat), altair keeps its params' existing `views`, and an
+    emptied list makes Vega-Lite define the selection in every view, which
+    fails with "Duplicate signal name". `views` is valid on top-level params,
+    which is the only place altair emits it.
     """
     if isinstance(chart_input, alt.TopLevelMixin):
         return chart_input
@@ -414,8 +459,9 @@ def _load_chart(chart_input: ChartInput, *, strict_version: bool) -> alt.TopLeve
         )
 
     _check_chart_schema_version(spec, strict_version=strict_version)
+    # `from_dict` keeps references into the spec (e.g. the `datasets` row
+    # lists), so copy it to keep the caller's dict out of later mutation.
     spec = copy.deepcopy(spec)
-    _strip_params_views(spec)
     # `from_dict` with validate=True dispatches to the right subclass
     # (Chart / LayerChart / FacetChart / HConcatChart / VConcatChart /
     # ConcatChart) based on the spec's shape.
@@ -479,26 +525,6 @@ def _check_chart_schema_version(spec: dict, *, strict_version: bool) -> None:
         )
 
 
-def _strip_params_views(spec: Any) -> None:
-    """Recursively delete `views` from every params[] entry.
-
-    altair's `to_dict()` annotates each selection-param with the views it's
-    bound to, but altair's own `from_dict()` validation rejects the field.
-    Stripping is safe: the renderer rebinds params to views on its own.
-    """
-    if isinstance(spec, dict):
-        params = spec.get("params")
-        if isinstance(params, list):
-            for p in params:
-                if isinstance(p, dict):
-                    p.pop("views", None)
-        for v in spec.values():
-            _strip_params_views(v)
-    elif isinstance(spec, list):
-        for item in spec:
-            _strip_params_views(item)
-
-
 class _ScriptCollector(HTMLParser):
     """Collect the text content of every <script> tag in an HTML document."""
 
@@ -1475,6 +1501,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
 
@@ -1497,6 +1528,7 @@ def _build_tree_chart(
     connect_leader_to_label: bool = False,
     strain_label_font_size: float = 10.0,
     strain_label_font_weight: str = "normal",
+    label_style_rules: list[_label_style.LabelStyleRule] | None = None,
     shift_tree_loc: int = 0,
     tip_names: list[str] | None = None,
     color_mapping: _color.ColorMapping | None = None,
@@ -1602,6 +1634,10 @@ def _build_tree_chart(
     #     text — and masks the dashed leader behind each label without any
     #     width estimation. Vega-Lite doesn't expose `paintOrder`, so the
     #     two-layer trick stands in for a single text-with-halo mark.
+    #   - `strain_label_styles` rules restyle individual labels by replacing
+    #     these layers' mark properties with per-label `datum` expressions
+    #     (see `_label_style`); the halo follows the glyph-shape ones
+    #     (fontWeight / fontStyle) so it keeps matching the text.
     #   - `shift_tree_loc` (pixels) shrinks the strip — bringing the tree
     #     visually closer to the labels — by reducing the data-units between
     #     branch_max and chart_edge_branch. The tree's tree_size-pixel
@@ -1609,14 +1645,37 @@ def _build_tree_chart(
     # When connect_leader_to_label is off, the chart's natural strain-axis
     # labels are kept and leaders stop at branch_max (the prior behavior).
     halo_px = max(2.0, strain_label_font_size * _LABEL_HALO_RATIO)
+    halo_style, text_style = _label_style.mark_props(
+        label_style_rules or [], default_font_weight=strain_label_font_weight
+    )
+    label_font_kwargs = {
+        "baseline": "middle",
+        "fontSize": strain_label_font_size,
+        "fontWeight": strain_label_font_weight,
+    }
+    label_halo_mark_kwargs = {
+        **label_font_kwargs,
+        "fill": "white",
+        "stroke": "white",
+        "strokeWidth": halo_px,
+        "strokeJoin": "round",
+        **halo_style,
+    }
+    label_text_mark_kwargs = {**label_font_kwargs, **text_style}
     if connect_leader_to_label:
         names = tip_names if tip_names is not None else list(tips_df["name"])
         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(
@@ -1629,9 +1688,19 @@ 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
+        )
+        tips_df = tips_df.assign(
+            **{
+                _label_style.membership_column(i): tips_df["name"].isin(rule.strains)
+                for i, rule in enumerate(label_style_rules or [])
+            }
         )
         extended_tree_size = tree_size + strip_pixel_width
     else:
@@ -1680,9 +1749,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"
@@ -1748,26 +1817,12 @@ def _build_tree_chart(
             )
             layers.append(
                 alt.Chart(tips_df)
-                .mark_text(
-                    align=text_align,
-                    baseline="middle",
-                    fontSize=strain_label_font_size,
-                    fontWeight=strain_label_font_weight,
-                    fill="white",
-                    stroke="white",
-                    strokeWidth=halo_px,
-                    strokeJoin="round",
-                )
+                .mark_text(align=text_align, **label_halo_mark_kwargs)
                 .encode(**label_text_enc)
             )
             layers.append(
                 alt.Chart(tips_df)
-                .mark_text(
-                    align=text_align,
-                    baseline="middle",
-                    fontSize=strain_label_font_size,
-                    fontWeight=strain_label_font_weight,
-                )
+                .mark_text(align=text_align, **label_text_mark_kwargs)
                 .encode(**label_text_enc)
             )
         if scale_bar_layer is not None:
@@ -1783,7 +1838,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
@@ -1853,28 +1909,12 @@ def _build_tree_chart(
             )
             layers.append(
                 alt.Chart(tips_df)
-                .mark_text(
-                    align=text_align,
-                    baseline="middle",
-                    angle=270,
-                    fontSize=strain_label_font_size,
-                    fontWeight=strain_label_font_weight,
-                    fill="white",
-                    stroke="white",
-                    strokeWidth=halo_px,
-                    strokeJoin="round",
-                )
+                .mark_text(align=text_align, angle=270, **label_halo_mark_kwargs)
                 .encode(**label_text_enc)
             )
             layers.append(
                 alt.Chart(tips_df)
-                .mark_text(
-                    align=text_align,
-                    baseline="middle",
-                    angle=270,
-                    fontSize=strain_label_font_size,
-                    fontWeight=strain_label_font_weight,
-                )
+                .mark_text(align=text_align, angle=270, **label_text_mark_kwargs)
                 .encode(**label_text_enc)
             )
         if scale_bar_layer is not None:

tree_annotated_plot/cli.py

@@ -74,19 +74,26 @@ class _ColorScaleParamType(click.ParamType):
 _COLOR_SCALE_PARAM_TYPE = _ColorScaleParamType()
 
 
-class _JsonDictParamType(click.ParamType):
-    """Parse a JSON-object string into a dict.
-
-    Used for ``--tree-color-legend-format``: any subset of Vega-Lite's
-    Legend properties as a JSON object (e.g.
-    ``'{"orient":"left","labelFontSize":13}'``). The user must quote the
-    whole argument so the shell doesn't interpret braces or quotes.
+class _JsonParamType(click.ParamType):
+    """Parse a JSON string into a dict, or into a list of dicts.
+
+    `container=dict` expects a JSON object; used for
+    ``--tree-color-legend-format``: any subset of Vega-Lite's Legend
+    properties (e.g. ``'{"orient":"left","labelFontSize":13}'``).
+    `container=list` expects a JSON array of objects; used for
+    ``--strain-label-styles`` (e.g.
+    ``'[{"strains":["K"],"style":{"fill":"red"}}]'``). The user must quote
+    the whole argument so the shell doesn't interpret braces or quotes.
+    `example` is shown in the error message when the JSON has the wrong shape.
     """
 
-    name = "json_dict"
+    def __init__(self, container: type, *, name: str, example: str) -> None:
+        self.container = container
+        self.name = name
+        self.example = example
 
     def convert(self, value, param, ctx):  # type: ignore[override]
-        if value is None or isinstance(value, dict):
+        if value is None or isinstance(value, self.container):
             return value
         text = str(value).strip()
         if not text:
@@ -95,17 +102,34 @@ class _JsonDictParamType(click.ParamType):
             parsed = json.loads(text)
         except json.JSONDecodeError as exc:
             self.fail(f"invalid JSON: {exc}", param, ctx)
-        if not isinstance(parsed, dict):
+        kind = "object" if self.container is dict else "array of objects"
+        if not isinstance(parsed, self.container):
             self.fail(
-                f'expected a JSON object (e.g. \'{{"orient":"left"}}\'); '
+                f"expected a JSON {kind} (e.g. {self.example}); "
                 f"got {type(parsed).__name__}.",
                 param,
                 ctx,
             )
+        if self.container is list:
+            for i, item in enumerate(parsed):
+                if not isinstance(item, dict):
+                    self.fail(
+                        f"expected a JSON {kind} (e.g. {self.example}); "
+                        f"element {i} is {type(item).__name__}.",
+                        param,
+                        ctx,
+                    )
         return parsed
 
 
-_JSON_DICT_PARAM_TYPE = _JsonDictParamType()
+_JSON_DICT_PARAM_TYPE = _JsonParamType(
+    dict, name="json_dict", example='\'{"orient":"left"}\''
+)
+_JSON_LIST_PARAM_TYPE = _JsonParamType(
+    list,
+    name="json_list",
+    example='\'[{"strains":["K"],"style":{"fill":"red"}}]\'',
+)
 
 
 def _is_str_dict(tp: Any) -> bool:
@@ -126,6 +150,14 @@ def _is_dict_any(tp: Any) -> bool:
     return False
 
 
+def _is_list_of_dicts(tp: Any) -> bool:
+    """Return True for `list[dict[str, Any]]`."""
+    if get_origin(tp) is list:
+        args = get_args(tp)
+        return len(args) == 1 and _is_dict_any(args[0])
+    return False
+
+
 def _option_for_field(field: dataclasses.Field, hints: dict) -> Any:
     """Build a `click.option(...)` decorator from a PlotConfig field.
 
@@ -188,6 +220,16 @@ def _option_for_field(field: dataclasses.Field, hints: dict) -> Any:
             show_default=False,
         )
 
+    # list[dict[str, Any]] (with or without `| None`) → JSON-array parser.
+    if _is_list_of_dicts(real_type):
+        return click.option(
+            cli_name,
+            type=_JSON_LIST_PARAM_TYPE,
+            default=field.default if has_default else None,
+            help=description,
+            show_default=False,
+        )
+
     # Optional / Union — unwrap to the non-None branch.
     origin = get_origin(real_type)
     if origin in (typing.Union, types.UnionType):
@@ -210,6 +252,14 @@ def _option_for_field(field: dataclasses.Field, hints: dict) -> Any:
                     help=description,
                     show_default=False,
                 )
+            if _is_list_of_dicts(inner):
+                return click.option(
+                    cli_name,
+                    type=_JSON_LIST_PARAM_TYPE,
+                    default=field.default if has_default else None,
+                    help=description,
+                    show_default=False,
+                )
             if get_origin(inner) is Literal:
                 choices = [str(c) for c in get_args(inner)]
                 return click.option(

{tree_annotated_plot-0.3.0.dist-info → tree_annotated_plot-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: tree-annotated-plot
-Version: 0.3.0
+Version: 0.5.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
@@ -43,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'

tree_annotated_plot-0.5.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+tree_annotated_plot/__init__.py,sha256=R39gjVnl3K2VjLba6zwtwPGADFmtNOE2UYNk1y9_z6k,351
+tree_annotated_plot/_color.py,sha256=nOZp-KIPy6s-6gBkzW36oHrwDk_SmvVNsMiIJ-dY1Io,26519
+tree_annotated_plot/_config.py,sha256=sDFaOoTcQ87IG7Yx4bOnWsv44uPHHhk_wvA4xeQ-NoA,15412
+tree_annotated_plot/_label_style.py,sha256=dyayJZeXT7TvldsRvEP-LhZgqJJoez_luqkk8lRAPvE,13281
+tree_annotated_plot/_plot.py,sha256=k8CygwCWa9Fl-EANDzAO-LfE3Wjj2pC0-PwHDIjt7JI,79668
+tree_annotated_plot/_tree.py,sha256=Bj-ABt8aooSwV7wAVTbwFGMmCnTPGOKweUWAdfb7aEI,13563
+tree_annotated_plot/cli.py,sha256=Q8dtm3vWmAOJYwu4mrlrYsO0Ys59HYCyKBtBHIryvKo,11804
+tree_annotated_plot-0.5.0.dist-info/METADATA,sha256=WyWmNl77MJQBDk8yWZiJJfvSMyaGu4S8O0qt2tpbICQ,11462
+tree_annotated_plot-0.5.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+tree_annotated_plot-0.5.0.dist-info/entry_points.txt,sha256=K7edTocRbwmtM2OeZmCy3DLjmY3MR-q2EJmQQq4rj0E,69
+tree_annotated_plot-0.5.0.dist-info/licenses/LICENSE,sha256=UIp30ue1HZit7tMmSK0SS3swJBqOcLLnLJn5LY5YdNE,1036
+tree_annotated_plot-0.5.0.dist-info/RECORD,,

{tree_annotated_plot-0.3.0.dist-info → tree_annotated_plot-0.5.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.29.0
+Generator: hatchling 1.33.0
 Root-Is-Purelib: true
 Tag: py3-none-any

tree_annotated_plot-0.3.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-tree_annotated_plot/__init__.py,sha256=R39gjVnl3K2VjLba6zwtwPGADFmtNOE2UYNk1y9_z6k,351
-tree_annotated_plot/_color.py,sha256=nOZp-KIPy6s-6gBkzW36oHrwDk_SmvVNsMiIJ-dY1Io,26519
-tree_annotated_plot/_config.py,sha256=Xs9XfuPAaIhGuffYbsDOfcJW_f4etpgPW4ombHNuIAg,12630
-tree_annotated_plot/_plot.py,sha256=a-sxcZ83Sp-bc0swwisOlvhV7L6bhJQWeh5kppANMX0,76901
-tree_annotated_plot/_tree.py,sha256=Bj-ABt8aooSwV7wAVTbwFGMmCnTPGOKweUWAdfb7aEI,13563
-tree_annotated_plot/cli.py,sha256=OG6Qmzk5BaHUNrfOopX20FbzBN2ahr_SBxHpaCk6Z5c,9848
-tree_annotated_plot-0.3.0.dist-info/METADATA,sha256=oQGwnxJxdq3g_fx_gfn6mjsskj0RHpBcMw2pGcJNZPo,11455
-tree_annotated_plot-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-tree_annotated_plot-0.3.0.dist-info/entry_points.txt,sha256=K7edTocRbwmtM2OeZmCy3DLjmY3MR-q2EJmQQq4rj0E,69
-tree_annotated_plot-0.3.0.dist-info/licenses/LICENSE,sha256=UIp30ue1HZit7tMmSK0SS3swJBqOcLLnLJn5LY5YdNE,1036
-tree_annotated_plot-0.3.0.dist-info/RECORD,,