scistackplot 0.1.34__tar.gz → 0.1.35__tar.gz

{scistackplot-0.1.34 → scistackplot-0.1.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scistackplot
-Version: 0.1.34
+Version: 0.1.35
 Summary: Spec-driven plotting for long-format scientific data — standalone, GUI-friendly
 Author: SciStack Contributors
 License-Expression: MIT
@@ -19,7 +19,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: numpy>=1.21
 Requires-Dist: pandas>=1.5
-Requires-Dist: scistacklog==0.1.34
+Requires-Dist: scistacklog==0.1.35
 Provides-Extra: dev
 Requires-Dist: matplotlib>=3.6; extra == 'dev'
 Requires-Dist: plotly>=5.0; extra == 'dev'
@@ -262,6 +262,18 @@ that looks like a data problem. `LongTable` carries each factor's real level
 order; sources that know better (SciDB knows its declared `schema_key_types`)
 supply it explicitly, and everything else falls back to a natural sort.
 
+## Missing levels stay visible
+
+A figure with no data for an x level that the rest of the plot has keeps an
+empty tick for it: under `subject=ITERATE`, the figure of a subject who never
+ran session 2 still shows a session 2 slot, so the gap reads as missing data.
+`PlotSpec.show_missing_levels=False` leaves those ticks off, which makes the
+remaining marks wider. "Missing" is measured against the plot's filtered
+rows, so a level you filtered out never comes back as an empty tick. Leaves
+of a nested axis work the same way, and no position is ever made for a
+combination no figure has. Either way `ResolvedPlot.missing_x` lists the
+levels, and the exported code draws the same ticks as the preview.
+
 ## Rendering
 
 Two backends translate the same reduced plot, so the interactive view and the

{scistackplot-0.1.34 → scistackplot-0.1.35}/README.md

@@ -223,6 +223,18 @@ that looks like a data problem. `LongTable` carries each factor's real level
 order; sources that know better (SciDB knows its declared `schema_key_types`)
 supply it explicitly, and everything else falls back to a natural sort.
 
+## Missing levels stay visible
+
+A figure with no data for an x level that the rest of the plot has keeps an
+empty tick for it: under `subject=ITERATE`, the figure of a subject who never
+ran session 2 still shows a session 2 slot, so the gap reads as missing data.
+`PlotSpec.show_missing_levels=False` leaves those ticks off, which makes the
+remaining marks wider. "Missing" is measured against the plot's filtered
+rows, so a level you filtered out never comes back as an empty tick. Leaves
+of a nested axis work the same way, and no position is ever made for a
+combination no figure has. Either way `ResolvedPlot.missing_x` lists the
+levels, and the exported code draws the same ticks as the preview.
+
 ## Rendering
 
 Two backends translate the same reduced plot, so the interactive view and the

{scistackplot-0.1.34 → scistackplot-0.1.35}/src/scistackplot/codegen.py

@@ -30,7 +30,15 @@ from .cell import cell_collapses, effective_shape
 from .compare import comparison_title, plan_comparison
 from .groups import active_level_groups, apply_level_groups, effective_mapping
 from .panels import Y_TITLES_FIRST_COLUMN, overrides_by_key, panel_key_text
-from .reduce import plan_layout, planned_y_limits, x_axis_title
+from .reduce import (
+    apply_filters,
+    axis_combinations,
+    axis_values,
+    nested_layer_orders,
+    plan_layout,
+    planned_y_limits,
+    x_axis_title,
+)
 from .resolved import DASH_CYCLE
 from .roles import (
     collapse_steps,
@@ -847,15 +855,23 @@ def _spaghetti_position_lines(spec, table: LongTable, roles, shape) -> list[str]
     if layers:
         # The composed, spacer-free order the nested axis is exported with.
         declared = _nested_x_order(spec, table, roles, shape)
+        plot_levels = declared
     elif x == _X_CONSTANT:
         declared = [""]
+        plot_levels = []
     else:
         declared = [str(level) for level in table.factor(x).levels]
+        plot_levels = [str(v) for v in axis_values(_plot_frame(spec, table), x)]
+    # PlotSpec.show_missing_levels: a level another figure of the plot holds
+    # keeps its (empty) slot here too, as the preview's tick does.
+    present = f"set(df[{x!r}].astype(str))"
+    if spec.show_missing_levels and plot_levels:
+        present = f"{present} | set({plot_levels!r})"
     return [
         "# spaghetti: each level at its index, each series shifted a fixed",
         "# fraction of a tick so every line ends on its own markers",
         f"_declared = {declared!r}",
-        f"_present = set(df[{x!r}].astype(str))",
+        f"_present = {present}",
         "_order = [v for v in _declared if v in _present]",
         "_natural = lambda s: [(0, int(c)) if c.isdigit() else (1, c) "
         'for c in re.split(r"(\\d+)", s) if c]',
@@ -1173,7 +1189,7 @@ def _sample_draw_lines(
         # (`_order`), the nested order catplot was given, the declared order
         # it was given (`_level_order_lines`), or — with neither — the order
         # of appearance seaborn infers.
-        "_x_levels = list(_order)" if spaghetti else f"_x_levels = {nested!r}" if nested else (
+        "_x_levels = list(_order)" if spaghetti else "_x_levels = list(_x_order)" if nested else (
             "_x_levels = [str(v) for v in _x_order]"
             if _emits_x_order(spec, table, roles, shape, _seaborn_call(spec, table, roles, shape))
             else f"_x_levels = list(dict.fromkeys(df[{x!r}].astype(str)))"
@@ -1436,41 +1452,27 @@ def _facet_layout_args(spec, table: LongTable, facets: list[str]) -> list[str]:
     return args
 
 
-def _nested_x_args(spec, table: LongTable, roles, shape) -> list[str]:
-    """``order=[...]`` reproducing the composed nested axis.
-
-    The RESOLVED order, computed by the same :func:`~scistackplot.xaxis.plan_x_axis`
-    the preview used, rather than the nesting rules re-applied in generated
-    code. A second implementation is a second thing that can drift, and the
-    failure would be a re-ordered axis nobody notices.
-
-    Spacers are dropped: seaborn has no concept of an empty category, so the
-    exported figure groups by ordering alone. The docstring says so — the
-    interactive view's gaps are the one thing the export cannot reproduce.
-    """
-    order = _nested_x_order(spec, table, roles, shape)
-    return [f"order={order!r}"] if order else []
-
-
 def _nested_x_order(spec, table: LongTable, roles, shape) -> list[str]:
-    """The composed nested-axis order, spacers dropped (see ``_nested_x_args``)."""
+    """The composed nested-axis order over the PLOT's filtered rows: every
+    leaf any figure of the fan-out holds, in the RESOLVED order the same
+    :func:`~scistackplot.xaxis.plan_x_axis` gave the preview — never the
+    nesting rules replayed in generated code, a second thing that can drift.
+
+    Spacers are dropped: seaborn has no empty category, so the export groups
+    by ordering alone (the docstring says so). The generated ``_x_order``
+    keeps every leaf under ``PlotSpec.show_missing_levels`` and the frame's
+    own leaves otherwise (``_x_order_lines``) — the preview's
+    ``reduce._x_axis_levels``."""
     layers = _nested_x_layers(spec, table, roles, shape)
     if not layers:
         return []
 
     from .xaxis import LEAF_SEPARATOR, is_spacer, plan_x_axis
 
-    frame = table.frame
-    present = [name for name in layers if name in frame.columns]
-    if len(present) != len(layers):
+    combinations = axis_combinations(_plot_frame(spec, table), layers)
+    if not combinations:
         return []
-    combinations = list(
-        frame[layers].astype(str).drop_duplicates().itertuples(index=False, name=None)
-    )
-    plan = plan_x_axis(
-        combinations,
-        [[str(level) for level in table.factor(name).levels] for name in layers],
-    )
+    plan = plan_x_axis(combinations, nested_layer_orders(table, layers))
     return [
         key.replace(LEAF_SEPARATOR, _NESTED_JOIN)
         for key in plan.order
@@ -1478,6 +1480,49 @@ def _nested_x_order(spec, table: LongTable, roles, shape) -> list[str]:
     ]
 
 
+def _plot_frame(spec, table: LongTable):
+    """The plot's rows after the spec's filters — every figure of the fan-out,
+    which is what a "missing" x level is missing FROM (``_Plan.frame`` in the
+    preview, cut by the same ``apply_filters``)."""
+    return apply_filters(table.frame, spec)
+
+
+def _x_order_lines(spec, table: LongTable, roles, shape, x: str) -> list[str]:
+    """``_x_order = …`` for a categorical x the call orders: the nested
+    composed order, or a flat factor's levels through ``_in_order``.
+
+    ``PlotSpec.show_missing_levels`` on: the levels of the whole PLOT, baked
+    in, so a figure of an ITERATE fan-out keeps an empty slot for a level
+    another figure has (the preview's empty tick). Off: only what this
+    frame holds. One variable, read by the call, the sample overlay and the
+    difference bars alike.
+    """
+    nested = _nested_x_order(spec, table, roles, shape)
+    Log.info(
+        "generated code: x order over %s — %s",
+        "the nested leaves" if nested else repr(x),
+        "the plot's levels baked in (show_missing_levels: a figure keeps "
+        "empty slots for the others')"
+        if spec.show_missing_levels
+        else "each frame's own levels (show_missing_levels off)",
+        layer=LAYER,
+    )
+    if nested:
+        if spec.show_missing_levels:
+            return [f"_x_order = {nested!r}"]
+        return [
+            f"_x_present = set(df[{_X_NESTED!r}])",
+            f"_x_order = [_k for _k in {nested!r} if _k in _x_present]",
+        ]
+    declared = _declared_levels(table, x)
+    if spec.show_missing_levels:
+        plot_levels = axis_values(_plot_frame(spec, table), x)
+        return [
+            f"_x_order = {_IN_ORDER}(pd.Series([*df[{x!r}], *{plot_levels!r}]), {declared!r})"
+        ]
+    return [f"_x_order = {_IN_ORDER}(df[{x!r}], {declared!r})"]
+
+
 def _seaborn_can_express_layout(spec, table: LongTable, roles) -> bool:
     """Whether ``_facet_layout_args`` reproduced the rules (see ``_docstring``)."""
     facets = [name for name, role in roles.items() if role is Role.FACET]
@@ -1681,9 +1726,6 @@ def _plot_call(
     if len(facets) > 1:
         args.append(f"row={facets[1]!r}")
     args.extend(_facet_layout_args(spec, table, facets))
-    if kind is not PlotKind.SPAGHETTI:
-        # relplot has no `order=`; the spaghetti preamble applies it itself.
-        args.extend(_nested_x_args(spec, table, roles, shape))
 
     estimator = (
         '"median"' if spec.aggregate.statistic is Statistic.MEDIAN else '"mean"'
@@ -2061,7 +2103,7 @@ def _seaborn_call(spec, table, roles, shape) -> str:
 def _emits_x_order(spec, table, roles, shape, call: str) -> bool:
     """Whether the call gets ``order=_x_order`` — a flat categorical x.
 
-    Nested x has its own composed ``order=`` (``_nested_x_args``) and the
+    Nested x has its own composed order (``_x_order_lines``) and the
     constant x has one level; spaghetti places levels itself.
     """
     if call not in _ORDERED_X_CALLS or _nested_x_layers(spec, table, roles, shape):
@@ -2090,8 +2132,11 @@ def _level_order_lines(
         lines.append(f"{variable} = {_IN_ORDER}(df[{column!r}], {declared!r})")
         call_args.append(f"{arg}={variable}")
 
-    if _emits_x_order(spec, table, roles, shape, call):
-        order("_x_order", x, "order")
+    if _emits_x_order(spec, table, roles, shape, call) or (
+        call in _ORDERED_X_CALLS and _nested_x_order(spec, table, roles, shape)
+    ):
+        lines.extend(_x_order_lines(spec, table, roles, shape, x))
+        call_args.append("order=_x_order")
     if color:
         order("_hue_order", color, "hue_order")
     # A RULED layout is `_facet_layout_args`' business: it emits its own
@@ -2383,7 +2428,7 @@ def _difference_bar_export(
     if spec.kind is PlotKind.SPAGHETTI:
         order_expr: str | None = "_order"
     elif nested:
-        order_expr = repr(_nested_x_order(spec, table, roles, shape))
+        order_expr = "_x_order"
     elif _emits_x_order(spec, table, roles, shape, _seaborn_call(spec, table, roles, shape)):
         order_expr = "_x_order"
     else:

{scistackplot-0.1.34 → scistackplot-0.1.35}/src/scistackplot/presets.py

@@ -91,6 +91,7 @@ FIELD_CLASSES: dict[str, FieldClass] = {
     "join_sample": _T,
     "sample_color": _T,
     "sample_in_legend": _T,
+    "show_missing_levels": _T,
     "facet": _T,
     "y_axis.scope": _T,
     "y_axis.minimum": _V,

{scistackplot-0.1.34 → scistackplot-0.1.35}/src/scistackplot/reduce.py

@@ -371,6 +371,7 @@ def resolve(
                     y_limits=plan.y_limits,
                     text=text,
                     colors=colors,
+                    axis_frame=plan.frame,
                 )
             )
         for figure in figures:
@@ -807,6 +808,7 @@ def resolve_one(
             y_limits=plan.y_limits,
             text=text,
             colors=colors,
+            axis_frame=plan.frame,
         )
         figure.fanout_notes = plan.notes
         siblings = _difference_sibling_indices(plan, position)
@@ -827,6 +829,7 @@ def resolve_one(
                         y_limits=plan.y_limits,
                         text=text,
                         colors=colors,
+                        axis_frame=plan.frame,
                     )
                     for other in siblings
                 ]
@@ -1236,6 +1239,7 @@ def _build_figure(
     y_limits: dict | None = None,
     text: DisplayText | None = None,
     colors: MarkColors | None = None,
+    axis_frame: pd.DataFrame | None = None,
 ) -> ResolvedPlot:
     # ``narrate`` makes this function announce each phase as it starts. A
     # full-resolution figure is minutes of work (scidb.log 2026-09-11: 1543s for
@@ -1402,7 +1406,6 @@ def _build_figure(
             color,
             layer=LAYER,
         )
-        x_factor = x_layers[0] if x_layers else None
         # Several factors may be faceted at once; their combined levels are the
         # panels, and FacetOptions decides how those panels are arranged.
         facet_names = [
@@ -1557,11 +1560,25 @@ def _build_figure(
             # renderers draw the same brackets and codegen can replay the result
             # instead of re-deriving it (same bargain as plan_layout).
             # Its TEXT is aliased; its `order` (the keys marks are placed by) is not.
-            x_plan = (
-                figure_text.x_plan(_plan_nested_x(panels, table, x_layers))
-                if len(x_layers) > 1
+            x_axis = (
+                _x_axis_levels(
+                    panels, table, x_layers, axis_frame, spec.show_missing_levels
+                )
+                if x_layers
                 else None
             )
+            x_plan = figure_text.x_plan(x_axis.plan) if x_axis and x_axis.plan else None
+            if x_axis is not None and x_axis.missing:
+                Log.info(
+                    "x axis: %d level(s) of the plot have no data in this figure "
+                    "(%s): %s",
+                    len(x_axis.missing),
+                    "drawn as empty ticks"
+                    if spec.show_missing_levels
+                    else "left off the axis (show_missing_levels=False)",
+                    _describe_missing(x_axis.missing),
+                    layer=LAYER,
+                )
 
         # The FIGURE's limits: the panels' own, when they all agree. Not a
         # second computation — every consumer that reads one number per figure
@@ -1642,12 +1659,16 @@ def _build_figure(
                 list(x_plan.order)
                 if x_plan
                 else (
-                    _level_order(table, x_factor, [p.frame for p in panels], X)
-                    if x_factor
+                    x_axis.order
+                    if x_axis is not None
                     else _unlabelled_x_order(panels)
                 )
             ),
             x_plan=x_plan,
+            missing_x=[
+                MISSING_X_JOIN.join(values)
+                for values in (x_axis.missing if x_axis is not None else [])
+            ],
             x_layers=list(x_layers),
             color_factor=color,
             color_order=color_order,
@@ -1981,7 +2002,7 @@ def _panel_frame(
         # Carry the nested axis's LAYER columns through the summary. They are a
         # function of the composed key, so grouping by them as well changes no
         # group — but without them `_summarize`'s `reset_index` returns three
-        # columns and the layer values are gone, and `_plan_nested_x` (which
+        # columns and the layer values are gone, and `_x_axis_levels` (which
         # requires every layer to be present in a panel) then skips every panel
         # and composes an EMPTY axis: no order, no ticks, no brackets.
         #
@@ -2120,7 +2141,7 @@ def _summarize(
     functionally determined by ``__x`` (the composed leaf key IS their
     combination), so grouping by them splits nothing that was not already
     split; it only keeps them from being dropped by the ``reset_index`` below,
-    which is what the renderers and ``_plan_nested_x`` read the group labels
+    which is what the renderers and ``_x_axis_levels`` read the group labels
     from.
 
     ``__color`` is carried the same way, and for the same reason: the
@@ -2255,33 +2276,115 @@ def _level_rank(table: LongTable, column: str, value: Any) -> tuple:
     return (1,) + natural_sort_key(value)
 
 
-def _plan_nested_x(
-    panels: list[Panel], table: LongTable, x_layers: list[str]
-) -> XPlan:
-    """Compose the nested axis from the combinations the panels actually hold.
+def axis_combinations(frame: pd.DataFrame, layers: list[str]) -> list[tuple[str, ...]]:
+    """The distinct combinations of ``layers`` in ``frame``, as text, in
+    order of appearance — ``[]`` when a layer is absent or the frame empty.
+
+    THE rule for which leaves a nested x axis can hold, read by the preview
+    (over a figure's panels, and over the plot's filtered frame for the
+    missing ones) and by ``codegen`` (over the same filtered frame). Observed
+    combinations, never the Cartesian product: real designs are ragged — a
+    sham group with no post session — and a position for a combination
+    nobody ran anywhere in the plot is not "missing data", it is no data.
+    """
+    if not layers or frame.empty or any(name not in frame.columns for name in layers):
+        return []
+    return list(
+        frame[layers].astype(str).drop_duplicates().itertuples(index=False, name=None)
+    )
+
+
+def axis_values(frame: pd.DataFrame, column: str) -> list[Any]:
+    """The distinct non-null values of a flat x factor in ``frame``, as the
+    frame holds them (a numeric level stays a number). The flat-axis twin of
+    :func:`axis_combinations`, with the same two readers."""
+    if column not in frame.columns or frame.empty:
+        return []
+    return frame[column].dropna().unique().tolist()
+
+
+def nested_layer_orders(table: LongTable, x_layers: list[str]) -> list[list[str]]:
+    """Each nested layer's declared level order, as text (``plan_x_axis``)."""
+    return [[str(level) for level in _factor_levels(table, name)] for name in x_layers]
+
+
+@dataclass(frozen=True)
+class _XAxis:
+    """What :func:`_x_axis_levels` decided for one figure."""
+
+    #: The flat axis' levels in order (natives), or None for a nested axis.
+    order: list[Any] | None
+    #: The composed nested axis, or None for a flat one.
+    plan: XPlan | None
+    #: Leaves of the plot this figure has no data for, as text, outermost
+    #: layer first — listed whether or not they are drawn.
+    missing: list[tuple[str, ...]]
 
-    Observed combinations, never the Cartesian product: real designs are ragged
-    — a sham group with no post session — and reserving a position for a
-    combination nobody ran leaves a hole that reads as missing data.
 
-    Taken across ALL panels so a faceted figure shares one axis; a panel missing
-    a combination gets a gap in the same place as its neighbours rather than a
-    differently-shaped axis.
+def _x_axis_levels(
+    panels: list[Panel],
+    table: LongTable,
+    x_layers: list[str],
+    axis_frame: pd.DataFrame | None,
+    show_missing: bool,
+) -> _XAxis:
+    """The figure's x levels: its own, plus — under
+    ``PlotSpec.show_missing_levels`` — the plot's levels it has no data for.
+
+    ``axis_frame`` is the plot's post-filter frame (``_Plan.frame``, every
+    figure of the fan-out), so "missing" is relative to what the plot holds
+    after the user's filters: a filtered-out level never returns as an empty
+    tick. Taken across ALL panels so a faceted figure shares one axis; a
+    panel missing a combination gets a gap in the same place as its
+    neighbours rather than a differently-shaped axis.
     """
-    combinations: list[tuple] = []
-    for panel in panels:
-        present = [name for name in x_layers if name in panel.frame.columns]
-        if len(present) != len(x_layers) or panel.frame.empty:
-            continue
-        combinations.extend(
-            panel.frame[x_layers].astype(str).drop_duplicates().itertuples(
-                index=False, name=None
+    plot_frame = axis_frame if axis_frame is not None else pd.DataFrame()
+    if len(x_layers) > 1:
+        own: list[tuple[str, ...]] = []
+        for panel in panels:
+            own.extend(axis_combinations(panel.frame, x_layers))
+        held = set(own)
+        missing = list(
+            dict.fromkeys(
+                combo
+                for combo in axis_combinations(plot_frame, x_layers)
+                if combo not in held
             )
         )
-    layer_orders = [
-        [str(level) for level in _factor_levels(table, name)] for name in x_layers
+        combinations = own + missing if show_missing else own
+        return _XAxis(
+            order=None,
+            plan=plan_x_axis(combinations, nested_layer_orders(table, x_layers)),
+            missing=sorted(missing, key=lambda combo: _combo_rank(table, x_layers, combo)),
+        )
+
+    x_factor = x_layers[0]
+    present = _level_order(table, x_factor, [p.frame for p in panels], X) or []
+    held_text = {str(value) for value in present}
+    missing_values = [
+        value for value in axis_values(plot_frame, x_factor) if str(value) not in held_text
     ]
-    return plan_x_axis(combinations, layer_orders)
+    order = present + missing_values if show_missing else present
+    order = sorted(order, key=lambda v: _level_rank(table, x_factor, v))
+    missing_values = sorted(missing_values, key=lambda v: _level_rank(table, x_factor, v))
+    return _XAxis(order=order, plan=None, missing=[(str(v),) for v in missing_values])
+
+
+#: Joins a missing nested leaf's layer values (outermost first) into the one
+#: string ``ResolvedPlot.missing_x`` lists it as.
+MISSING_X_JOIN = " / "
+
+
+def _describe_missing(missing: list[tuple[str, ...]], limit: int = 8) -> str:
+    names = [MISSING_X_JOIN.join(values) for values in missing]
+    more = f" … +{len(names) - limit} more" if len(names) > limit else ""
+    return ", ".join(names[:limit]) + more
+
+
+def _combo_rank(table: LongTable, layers: list[str], combo: tuple[str, ...]) -> tuple:
+    return tuple(
+        _level_rank(table, name, value) for name, value in zip(layers, combo, strict=True)
+    )
 
 
 def _factor_levels(table: LongTable, name: str) -> list[Any]:

{scistackplot-0.1.34 → scistackplot-0.1.35}/src/scistackplot/render/base.py

@@ -436,6 +436,21 @@ def legend_levels(resolved: ResolvedPlot) -> list[Any]:
     return ordered
 
 
+def legend_entry_labels(resolved: ResolvedPlot) -> list[str]:
+    """
+    The colour entries' TEXT, in legend order: :func:`legend_levels` as the
+    renderers label them.
+
+    The one place a legend's order comes from. Both renderers used to list
+    entries in the order they first met them while drawing panel after panel,
+    so a facet grid whose first panel lacked a level (no ``BL`` in the sham
+    group) listed that level after the others — the declared ``[schema_keys]``
+    order held in every panel and in the colours, but not in the legend
+    (2026-10-15).
+    """
+    return [resolved.text.color_level(level) for level in legend_levels(resolved)]
+
+
 def shares_y_axis(resolved: ResolvedPlot) -> bool:
     """Whether every panel draws the same y range, so one axis can serve them.
 

{scistackplot-0.1.34 → scistackplot-0.1.35}/src/scistackplot/render/mpl.py

@@ -41,6 +41,7 @@ from .base import (
     dash_style,
     grid_shape,
     is_categorical_x,
+    legend_entry_labels,
     legend_levels,
     mark_width,
     palette_for,
@@ -1269,89 +1270,6 @@ def _verify_x_ticks(fig, ticks: list[_XTicks], fit: LabelFit) -> None:
 #: figure width.
 LEGEND_PAD = 0.02
 
-#: Widest the legend strip may get, however long the level names are: past this
-#: the labels have eaten the figure, and truncating the panels is worse than
-#: truncating the legend.
-MAX_LEGEND_FRACTION = 0.4
-
-
-def _apply_legend(fig, resolved: ResolvedPlot) -> float:
-    """
-    Draw the legend to the right of the panels; return the width it claimed.
-
-    The return value is a fraction of the figure width, for ``tight_layout``'s
-    ``rect`` — see the call site. Zero means no legend was drawn, which is the
-    answer for a single colour level (``base.shows_legend``) as well as for no
-    colour at all.
-    """
-    if not shows_legend(resolved):
-        Log.debug(
-            "legend omitted: %d colour level(s) drawn for %r",
-            len(legend_levels(resolved)),
-            resolved.labels.color,
-            layer=LAYER,
-        )
-        return 0.0
-    # Every VISIBLE axes, not just the first: with facets, a level can be
-    # absent from panel 1 and present in panel 5, and reading one panel's
-    # handles would drop it from the legend of a figure that draws it.
-    unique: dict[str, Any] = {}
-    for ax in fig.axes:
-        if not ax.get_visible():
-            continue
-        handles, labels = ax.get_legend_handles_labels()
-        for handle, label in zip(handles, labels, strict=False):
-            unique.setdefault(label, handle)
-    if not unique:
-        return 0.0
-    # The overlay's block goes LAST, in its levels' order. matplotlib lists
-    # an axes' Line2D handles before its bar containers, so gathered as-is
-    # the subjects would precede the bars they sit on.
-    sample_labels = [resolved.text.sample_level(level) for level in sample_legend_levels(resolved)]
-    if len(sample_labels) > 1:
-        unique = {
-            **{k: v for k, v in unique.items() if k not in sample_labels},
-            **{k: unique[k] for k in sample_labels if k in unique},
-        }
-
-    # One title naming every block: the colours, the dash styles, and the
-    # overlay's own colour key when its levels are listed too.
-    blocks = (
-        resolved.labels.color,
-        resolved.labels.dash,
-        resolved.labels.sample if len(sample_legend_levels(resolved)) > 1 else None,
-    )
-    title = " / ".join(t for t in blocks if t) or None
-    legend = fig.legend(
-        unique.values(),
-        unique.keys(),
-        title=title,
-        loc="center right",
-        frameon=False,
-    )
-    return _legend_width_fraction(fig, legend, unique.keys(), title)
-
-
-def _legend_width_fraction(fig, legend, labels, title) -> float:
-    """How much of the figure's width the legend needs, measured if possible."""
-    figure_width = fig.get_size_inches()[0] or 1.0
-    try:
-        inches = legend.get_window_extent(fig.canvas.get_renderer()).width / fig.dpi
-    except Exception:  # a backend without a usable renderer
-        # Estimate rather than reserve nothing: a wrong-by-a-little strip still
-        # keeps the legend off the panels, an unmeasured one does not.
-        longest = max((len(str(text)) for text in [*labels, title or ""]), default=0)
-        inches = 0.55 + 0.085 * longest
-        Log.debug(
-            "legend width not measurable; estimating %.2fin from %d labels",
-            inches,
-            len(list(labels)),
-            layer=LAYER,
-        )
-#: Breathing room between the panels and the legend strip, as a fraction of the
-#: figure width.
-LEGEND_PAD = 0.02
-
 #: Share of the figure width a legend at the right may take. Past it the
 #: legend is narrowed (title wrapped, shorter line samples, smaller text) and,
 #: if still too wide, moved below the panels. The old cap was 0.4, and at it a
@@ -1431,6 +1349,15 @@ def _legend_entries(fig, resolved: ResolvedPlot):
             unique.setdefault(label, handle)
     if not unique:
         return None
+    # The colour block FIRST, in legend order (`legend_entry_labels`): handles
+    # are gathered axes by axes, so a level missing from the first panel
+    # would otherwise be listed after levels declared later.
+    colour_labels = [label for label in legend_entry_labels(resolved) if label in unique]
+    unique = {
+        **{label: unique[label] for label in colour_labels},
+        **{k: v for k, v in unique.items() if k not in colour_labels},
+    }
+    Log.debug("export legend order: %s", list(unique), layer=LAYER)
     # The overlay's block goes LAST, in its levels' order. matplotlib lists
     # an axes' Line2D handles before its bar containers, so gathered as-is
     # the subjects would precede the bars they sit on.

{scistackplot-0.1.34 → scistackplot-0.1.35}/src/scistackplot/render/plotly_.py

@@ -55,6 +55,7 @@ from .base import (
     dash_style,
     grid_shape,
     is_categorical_x,
+    legend_entry_labels,
     legend_levels,
     colorable,
     palette_for,
@@ -174,6 +175,10 @@ def render(
                 # from this, never from `spec.roles`.
                 "panel_factors": list(resolved.panel_factors),
                 "y_scope": list(resolved.y_scope),
+                # The plot's x levels this figure has no data for
+                # (ResolvedPlot.missing_x): the GUI offers "Show missing
+                # levels" only when this is non-empty, and says which.
+                "missing_x": list(resolved.missing_x),
                 # The size the SAVED figure will have. The preview fills its
                 # pane regardless, so this is how the panel states what the
                 # export produces — the same numbers `render_mpl` logs.
@@ -236,6 +241,18 @@ def render(
             panel_position(resolved, index) for index in range(len(resolved.panels))
         ]
         seen_legend: set[str] = set()
+        # plotly lists legend entries in TRACE order, which is panel order —
+        # a level missing from the first panel would be listed late. A rank
+        # per entry pins the legend to `legend_entry_labels` instead. Below
+        # plotly's default 1000, so dash entries (unranked) follow the colours
+        # and the overlay (2000) stays last.
+        legend_ranks = (
+            {label: rank for rank, label in enumerate(legend_entry_labels(resolved))}
+            if legend_on
+            else {}
+        )
+        if legend_ranks:
+            Log.debug("preview legend order: %s", list(legend_ranks), layer=LAYER)
 
         for index, panel in enumerate(resolved.panels):
             row, col = positions[index]
@@ -245,7 +262,8 @@ def render(
 
             traces.extend(
                 _panel_traces(
-                    panel.frame, resolved, x_axis, y_axis, seen_legend, legend_on
+                    panel.frame, resolved, x_axis, y_axis, seen_legend, legend_on,
+                    legend_ranks,
                 )
             )
             traces.extend(_sample_traces(panel, resolved, x_axis, y_axis, seen_legend, legend_on))
@@ -472,6 +490,7 @@ def _panel_traces(
     y_axis: str,
     seen_legend: set[str],
     legend_on: bool = True,
+    legend_ranks: dict[str, int] | None = None,
 ) -> list[dict]:
     if frame.empty:
         return []
@@ -506,6 +525,8 @@ def _panel_traces(
             "xaxis": x_axis,
             "yaxis": y_axis,
         }
+        if legend_ranks and label in legend_ranks:
+            base["legendrank"] = legend_ranks[label]
         if _positional_x(resolved):
             # A linear axis of level indices (see `_positional_x`): every mark
             # is placed by index so the overlay can shift beside it, and the

{scistackplot-0.1.34 → scistackplot-0.1.35}/src/scistackplot/resolved.py

@@ -194,6 +194,12 @@ class ResolvedPlot:
     #: so every existing consumer keeps working; renderers read this only to
     #: draw the group labels and brackets beneath the ticks.
     x_plan: Any = None
+    #: x levels of the plot (its filtered data, every figure of the fan-out)
+    #: this figure has no data for, in axis order — a nested leaf as its
+    #: layer values joined by ``reduce.MISSING_X_JOIN``. Listed whether or not
+    #: ``PlotSpec.show_missing_levels`` draws them, so the GUI can offer the
+    #: toggle exactly when it would change something.
+    missing_x: list[str] = field(default_factory=list)
     #: The factors sharing the x axis, outermost first: ``x_plan`` depth ``d``
     #: is ``x_layers[d]`` and the last entry is the tick labels' own layer.
     #: With ``color_factor``, how a renderer knows which labelled row repeats
@@ -353,6 +359,7 @@ class ResolvedPlot:
                 "layout_notes": list(self.layout_notes),
             },
             "x_order": [_jsonable(v) for v in (self.x_order or [])] or None,
+            "missing_x": list(self.missing_x),
             "x_groups": [
                 {
                     "label": group.label,

{scistackplot-0.1.34 → scistackplot-0.1.35}/src/scistackplot/spec.py

@@ -1129,6 +1129,14 @@ class PlotSpec:
     #: shown — the points keep their colours. ``roles.overlay_in_legend`` is
     #: the one reader.
     sample_in_legend: bool = True
+    #: Whether an x level this figure has no data for keeps its (empty) tick.
+    #: "Missing" means present in the plot's FILTERED data but absent from
+    #: this figure — a subject's figure without session 2 under a fan-out —
+    #: never a level a filter removed. On (the default), the empty tick says
+    #: the data is missing, at the cost of narrower marks; off, the axis holds
+    #: only the figure's own levels. ``reduce._x_axis_levels`` is the one
+    #: reader; ``ResolvedPlot.missing_x`` lists the levels either way.
+    show_missing_levels: bool = True
     facet: FacetOptions = field(default_factory=FacetOptions)
     #: What the y axis spans, and what separates spans. See :class:`YAxis`.
     y_axis: YAxis = field(default_factory=YAxis)
@@ -1359,6 +1367,7 @@ class PlotSpec:
             join_sample=_optional_bool(raw.get("join_sample")),
             sample_color=raw.get("sample_color"),
             sample_in_legend=bool(raw.get("sample_in_legend", True)),
+            show_missing_levels=bool(raw.get("show_missing_levels", True)),
             facet=_facet_from_dict(raw.get("facet") or {}),
             y_axis=YAxis.from_dict(raw.get("y_axis") or {}),
             style=StyleOptions.from_dict(raw.get("style")),