tree-annotated-plot 0.2.2__py3-none-any.whl → 0.4.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.",
@@ -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/_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/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.dist-info → tree_annotated_plot-0.4.0.dist-info}/METADATA

@@ -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.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+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=0ib600JaMpMz4ZjFYtvFu3nhUhliJRexTJcFpDKVOD0,13171
+tree_annotated_plot/_plot.py,sha256=pqhR9PgQUML2-taP_k1FEidpIdBgJ6tulMEpFJbD8WI,77969
+tree_annotated_plot/_tree.py,sha256=Bj-ABt8aooSwV7wAVTbwFGMmCnTPGOKweUWAdfb7aEI,13563
+tree_annotated_plot/cli.py,sha256=OG6Qmzk5BaHUNrfOopX20FbzBN2ahr_SBxHpaCk6Z5c,9848
+tree_annotated_plot-0.4.0.dist-info/METADATA,sha256=JQNY2-mmZIQA7TjABRX_YkvoZXxqix-Ixs5n23EQ1FY,11462
+tree_annotated_plot-0.4.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+tree_annotated_plot-0.4.0.dist-info/entry_points.txt,sha256=K7edTocRbwmtM2OeZmCy3DLjmY3MR-q2EJmQQq4rj0E,69
+tree_annotated_plot-0.4.0.dist-info/licenses/LICENSE,sha256=UIp30ue1HZit7tMmSK0SS3swJBqOcLLnLJn5LY5YdNE,1036
+tree_annotated_plot-0.4.0.dist-info/RECORD,,

{tree_annotated_plot-0.2.2.dist-info → tree_annotated_plot-0.4.0.dist-info}/WHEEL

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

tree_annotated_plot-0.2.2.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=XwokRKY-ytNXelxwuapRKedTBaEedDi_erUp3su7zUs,12498
-tree_annotated_plot/_plot.py,sha256=GCdcPyfTlem9YTlPkgdkJGPb5g4w2Vt0fevJcHEo9HI,72720
-tree_annotated_plot/_tree.py,sha256=Bj-ABt8aooSwV7wAVTbwFGMmCnTPGOKweUWAdfb7aEI,13563
-tree_annotated_plot/cli.py,sha256=yXI5fcLoIoLf6EjgPLmIQIAzDfkVoS5mSZ26_HSHVmk,9786
-tree_annotated_plot-0.2.2.dist-info/METADATA,sha256=8yAZMK69Tos2TmV-_Gb359Xm6OlmC8Elzzgzdp3yM04,11353
-tree_annotated_plot-0.2.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-tree_annotated_plot-0.2.2.dist-info/entry_points.txt,sha256=K7edTocRbwmtM2OeZmCy3DLjmY3MR-q2EJmQQq4rj0E,69
-tree_annotated_plot-0.2.2.dist-info/licenses/LICENSE,sha256=UIp30ue1HZit7tMmSK0SS3swJBqOcLLnLJn5LY5YdNE,1036
-tree_annotated_plot-0.2.2.dist-info/RECORD,,