apmtools 0.2.45__tar.gz → 0.2.47__tar.gz

{apmtools-0.2.45 → apmtools-0.2.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: apmtools
-Version: 0.2.45
+Version: 0.2.47
 Summary: A collection of tools for processing air pollution monitoring data
 Project-URL: Homepage, https://github.com/federlorenz/apmtools
 Author-email: Federico Lorenzetti <lorenzetti.federico@gmail.com>

{apmtools-0.2.45 → apmtools-0.2.47}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "apmtools"
-version = "0.2.45"
+version = "0.2.47"
 authors = [
   { name="Federico Lorenzetti", email="lorenzetti.federico@gmail.com" },
 ]

{apmtools-0.2.45 → apmtools-0.2.47}/src/apmtools/shiny/appearance.py

@@ -1,5 +1,6 @@
 """Figure labels and appearance controls."""
 from __future__ import annotations
+import re
 import threading
 from datetime import date, datetime, time, timedelta
 from collections.abc import Sequence
@@ -38,12 +39,10 @@ def _label_plot_axes(fig, plot_type, x_column, y_columns, *,
     elif plot_type in {"box", "bar"}:
         categories = category_columns or [x_column]
         fig.update_xaxes(title_text=" | ".join(_axis_label(c) for c in categories))
-        fig.update_yaxes(title_text=_axis_label(y_columns[0]))
+        fig.update_yaxes(title_text="<br>".join(_axis_label(y) for y in y_columns))
     elif plot_type == "line" and len(y_columns) > 1:
         fig.update_xaxes(title_text=_axis_label(x_column))
-        # The values axis is shared by multiple series; facet headings carry
-        # the variable-specific unit rather than misleadingly naming one unit.
-        fig.update_yaxes(title_text="Value")
+        fig.update_yaxes(title_text="<br>".join(_axis_label(y) for y in y_columns))
         for annotation in fig.layout.annotations:
             label = str(annotation.text)
             if label.startswith("variable="):
@@ -61,7 +60,7 @@ def _label_plot_axes(fig, plot_type, x_column, y_columns, *,
 def _parse_label_map(value):
     """Parse semicolon-separated original=replacement entries."""
     result = {}
-    for entry in (value or "").split(";"):
+    for entry in re.split(r"[;\r\n]+", value or ""):
         if "=" in entry:
             key, replacement = entry.split("=", 1)
             if key.strip() and replacement.strip():
@@ -125,7 +124,7 @@ def _apply_plot_appearance(fig, *, title, x_label="", y_label="",
     if x_label.strip():
         fig.update_xaxes(title_text=x_label.strip())
     if y_label.strip():
-        fig.update_yaxes(title_text=y_label.strip())
+        fig.update_yaxes(title_text=y_label.strip().replace("\n", "<br>"))
     fig.update_xaxes(showgrid=show_grid)
     fig.update_yaxes(showgrid=show_grid)
     use_x, use_y = _numeric_axis_controls(plot_kind, box_orientation)

apmtools-0.2.47/src/apmtools/shiny/color_editor.py

@@ -0,0 +1,64 @@
+"""Stable colour-editor keys for the actual prepared plotting data."""
+from __future__ import annotations
+import re
+import pandas as pd
+
+_HEX = re.compile(r"#[0-9a-fA-F]{6}\Z")
+
+def valid_hex_color(value):
+    return isinstance(value, str) and _HEX.fullmatch(value.strip()) is not None
+
+
+def active_color_keys(spec, *, mode="group", panel_by=()):
+    """Return colour dimensions with nonempty plotted observations.
+
+    Faceting removes its grouping columns. For multi-Y plots, 'both' uses
+    combinations, while group/variable/none use the corresponding colour
+    dimension (the same keys accepted by multi_y_styles).
+    """
+    if "error" in spec or spec["data"].empty:
+        return ()
+    if spec.get("hist_variables"):
+        return tuple(dict.fromkeys(spec["data"].loc[
+            spec["data"][spec["x"]].notna(), "__hist_series"].astype(str)))
+    from .matplotlib_renderer import _panel_partitions
+    from .multi_axis import records
+    parts = (_panel_partitions(spec, panel_by) if panel_by
+             else [(None, spec["data"], spec["groups"])])
+    keys = []
+    for _, frame, remaining in parts:
+        if frame.empty:
+            continue
+        sub = {**spec, "data": frame, "groups": remaining,
+               "_original_groups": spec["groups"]} if panel_by else {**spec, "data": frame, "groups": remaining}
+        if spec.get("multi_axis"):
+            pairs = [(str(y), str(g) if remaining else None)
+                     for _, g, y, _, _, _ in records(sub)]
+        else:
+            ys = list(sub["ys"])
+            groups = (list(pd.unique(frame["__plot_group"].astype(str)))
+                      if remaining and "__plot_group" in frame else [None])
+            pairs = []
+            for g in groups:
+                rows = (frame.loc[frame["__plot_group"].astype(str) == g]
+                        if g is not None else frame)
+                for y in ys:
+                    if y in rows and rows[y].notna().any():
+                        pairs.append((str(y), g))
+        multi = bool(spec.get("multi_axis") or len(sub["ys"]) > 1)
+        for y, g in pairs:
+            if not multi or mode in ("group", "none"):
+                key = g if g is not None else y
+            elif mode == "variable":
+                key = y
+            else:
+                key = f"{g}, {y}" if g is not None else y
+            if key not in keys and key != "All observations":
+                keys.append(key)
+    return tuple(keys)
+
+
+def color_defaults(spec, keys, palette="Default"):
+    from .config import _MPL_PALETTES
+    values = _MPL_PALETTES.get(palette, _MPL_PALETTES["Default"])
+    return {key: values[i % len(values)] for i, key in enumerate(keys)}

{apmtools-0.2.45 → apmtools-0.2.47}/src/apmtools/shiny/data.py

@@ -23,7 +23,8 @@ def _composite_labels(data: pd.DataFrame, columns: list[str]) -> pd.Series:
         return "None" if pd.isna(value) else str(value)
     if len(columns) == 1:
         return data[columns[0]].map(label)
-    return pd.Series((" | ".join(label(value) for value in row)
+    return pd.Series(
+        (" | ".join(label(value) for value in row)
          for row in data[columns].itertuples(index=False, name=None)),
         index=data.index,
         dtype="str",
@@ -130,8 +131,12 @@ def _aggregate(data, value_columns, frequency, grouping_by, aggregate, *,
     is selected, matching Summary.group_stat(frequency=None, grouping_by=...).
     This function is called only when aggregation is explicitly requested.
     """
+    if data is None or data.empty:
+        return pd.DataFrame()
     if frequency is None and not grouping_by:
-        raise ValueError("Select at least one categorical grouping variable for categorical-only aggregation.")
+        # Invalid/incomplete UI selection: no aggregation groups exist.
+        # Return empty rather than breaking Shiny's reactive graph.
+        return pd.DataFrame()
 
     result = data.group_stat(
         value_cols=value_columns,
@@ -142,10 +147,9 @@ def _aggregate(data, value_columns, frequency, grouping_by, aggregate, *,
            if frequency is not None else {}),
     )
     if result is None:
-        raise ValueError(
-            "Summary.group_stat() returned None. Check the selected variables, "
-            "grouping columns, frequency, and completeness settings."
-        )
+        # group_stat() may return None when no rows survive completeness
+        # requirements or other filtering. Treat this as an empty plot.
+        return pd.DataFrame()
     return result
 
 

apmtools-0.2.47/src/apmtools/shiny/elements.py

@@ -0,0 +1,96 @@
+"""Selectable plotted elements, independent of the rendering backend."""
+import pandas as pd
+
+
+def _group_labels(spec):
+    frame = spec['data']
+    if spec.get('groups') and '__plot_group' in frame:
+        return frame['__plot_group'].astype(str)
+    return pd.Series('All observations', index=frame.index)
+
+
+def element_keys(spec):
+    """Selectable element identifiers with at least one valid plotted value.
+
+    Elements with exclusively missing observations are not selectable, rather
+    than merely being unchecked by default.
+    """
+    return default_visible_keys(spec)
+
+
+def filter_elements(spec, selected):
+    """Remove hidden elements without changing the underlying Summary or filters.
+
+    For multi-Y lines, individual group/variable combinations are removed by
+    masking only their Y values. Panels with no remaining values disappear.
+    """
+    if 'error' in spec or selected is None:
+        return spec
+    allowed = set(selected)
+    if spec.get('hist_variables'):
+        frame = spec['data'].loc[spec['data']['__hist_series'].isin(allowed)].copy()
+        return {**spec, 'data': frame, '_visible_elements': allowed}
+    if spec.get('multi_axis'):
+        from .multi_axis import records
+        filtered = {**spec, '_visible_elements': allowed}
+        keep = pd.Index([])
+        for _, _, _, _, _, rows in records(filtered):
+            keep = keep.union(rows.index, sort=False)
+        return {**filtered, 'data': spec['data'].loc[spec['data'].index.isin(keep)].copy()}
+    frame = spec['data'].copy()
+    kind = spec['kind']
+    groups = _group_labels(spec)
+    if kind == 'line':
+        keep_any = pd.Series(False, index=frame.index)
+        for y in spec['ys']:
+            keys = groups.map(lambda g: f'{g} | {y}' if len(spec['ys']) > 1 else g)
+            permitted = keys.isin(allowed)
+            frame.loc[~permitted, y] = float('nan')
+            keep_any |= permitted & frame[y].notna()
+        frame = frame.loc[keep_any].copy()
+    elif kind in ('box', 'bar'):
+        keys = [f'{c} | {g}' if spec['groups'] else c
+                for c, g in zip(frame[spec['x']].astype(str), groups)]
+        frame = frame.loc[pd.Series(keys, index=frame.index).isin(allowed)].copy()
+    else:
+        frame = frame.loc[groups.isin(allowed)].copy()
+    return {**spec, 'data': frame, '_visible_elements': allowed}
+
+
+def default_visible_keys(spec):
+    """Elements with at least one nonmissing plotted value (not merely rows)."""
+    if 'error' in spec:
+        return []
+    if spec.get('multi_axis'):
+        from .multi_axis import all_keys
+        return all_keys(spec, nonmissing=True)
+    frame, kind, x = spec['data'], spec['kind'], spec['x']
+    if spec.get('hist_variables'):
+        return list(dict.fromkeys(frame.loc[frame[x].notna(), '__hist_series'].astype(str)))
+    groups = _group_labels(spec)
+    if kind == 'line':
+        return list(dict.fromkeys(
+            f'{group} | {y}' if len(spec['ys']) > 1 else group
+            for y in spec['ys'] if y in frame
+            for group in groups[frame[y].notna()]
+        ))
+    if kind in ('box', 'bar'):
+        y = next((y for y in spec['ys'] if y in frame), None)
+        if y is None:
+            return []
+        valid = frame[y].notna()
+        return list(dict.fromkeys(
+            f'{category} | {group}' if spec['groups'] else str(category)
+            for category, group in zip(frame.loc[valid, x].astype(str), groups.loc[valid])
+        ))
+    # Scatter requires both coordinates; histogram requires its numeric x.
+    if kind == 'scatter':
+        valid = frame[x].notna()
+        for y in spec['ys']:
+            if y in frame:
+                valid &= frame[y].notna()
+    else:
+        valid = frame[x].notna()
+    return list(dict.fromkeys(groups.loc[valid]))
+
+

apmtools-0.2.47/src/apmtools/shiny/histogram_multi.py

@@ -0,0 +1,32 @@
+"""Long-format data preparation for overlaid multi-variable histograms."""
+import pandas as pd
+from .data import _composite_labels
+
+
+def histogram_long_data(frame, variables, *, group_columns=()):
+    """Create one histogram series per variable/group using a shared numeric axis.
+
+    Non-histogram columns are retained so faceting, export, and filtering work.
+    """
+    variables = list(dict.fromkeys(variables))
+    if not variables:
+        raise ValueError("At least one histogram variable is required")
+    missing = [name for name in variables if name not in frame]
+    if missing:
+        raise KeyError(f"Missing histogram variables: {missing}")
+    groups = list(group_columns)
+    for col in groups:
+        if col not in frame:
+            raise KeyError(col)
+    chunks = []
+    for name in variables:
+        part = frame.copy()
+        part["__hist_value"] = pd.to_numeric(part[name], errors="coerce")
+        part["__hist_variable"] = name
+        part["__hist_series"] = (name + " | " + _composite_labels(part, groups)
+                                 if groups else name)
+        part = part.loc[part["__hist_value"].notna()]
+        chunks.append(part)
+    if not chunks:
+        return frame.iloc[0:0].copy()
+    return pd.concat(chunks, ignore_index=True)

{apmtools-0.2.45 → apmtools-0.2.47}/src/apmtools/shiny/matplotlib_renderer.py

@@ -16,7 +16,9 @@ def _matplotlib_defaults(spec, *, palette="Default"):
     """Derive labels and series colours directly from prepared pandas data."""
     kind, df = spec["kind"], spec["data"]
     x, ys, groups = spec["x"], spec["ys"], spec["groups"]
-    names = ([str(v) for v in pd.unique(df["__plot_group"])]
+    names = ([str(v) for v in pd.unique(df["__hist_series"])]
+             if kind == "histogram" and spec.get("hist_variables") and "__hist_series" in df
+             else [str(v) for v in pd.unique(df["__plot_group"])]
              if groups and "__plot_group" in df else [])
     if not names and kind == "line" and len(ys) > 1:
         names = [str(y) for y in ys]
@@ -27,8 +29,10 @@ def _matplotlib_defaults(spec, *, palette="Default"):
     x_label = (" | ".join(_axis_label(c) for c in spec["categories"])
                if kind in ("box", "bar") else _axis_label(x))
     y_label = ("Probability density" if kind == "histogram" else
-               "Value" if kind == "line" and len(ys) > 1 else
+               "\n".join(_axis_label(y) for y in ys) if len(ys) > 1 else
                _axis_label(ys[0]) if ys else "Count")
+    if kind == "scatter" and len(spec.get("x_variables", [])) > 1:
+        x_label = "\n".join(_axis_label(c) for c in spec["x_variables"])
     x_label = spec.get("x_label_override") or x_label
     return dict(x_label=x_label, y_label=y_label, names=names, colors=colors)
 
@@ -43,6 +47,8 @@ def _axis_bounds_from_spec(spec, *, bins=30, density=False, stacked=False, cumul
     if "error" in spec:
         return {key: "" for key in ("x_min", "x_max", "y_min", "y_max")}
     df, kind, x, ys = spec["data"], spec["kind"], spec["x"], spec["ys"]
+    if df.empty:
+        return {key: "" for key in ("x_min", "x_max", "y_min", "y_max")}
     bounds = {key: "" for key in ("x_min", "x_max", "y_min", "y_max")}
 
     def fill(axis, values):
@@ -147,6 +153,9 @@ def _panel_partitions(spec, panel_by):
     for value, part in spec["data"].groupby(grouper, sort=False, dropna=False):
         values = value if isinstance(value, tuple) else (value,)
         title = " | ".join("None" if pd.isna(v) else str(v) for v in values)
+        if spec.get("multi_axis") and spec["groups"] and "__plot_group" in part:
+            part = part.copy()
+            part["__plot_global_group"] = part["__plot_group"]
         if remaining:
             part = part.copy(deep=False)
             part["__plot_group"] = (_composite_labels(part, remaining))
@@ -262,7 +271,8 @@ def _fit_inside_legends(fig, axes, font_size=12, ncol=1):
                              pos.height * old_h / (old_h + extra_h) + extra_h / (old_h + extra_h)))
 
 
-def _place_outside_legend(fig, axes, position="right", font_size=12, ncol=1):
+def _place_outside_legend(fig, axes, position="right", font_size=12, ncol=1,
+                          panel_hspace=0.90, panel_wspace=0.38):
     """Use exactly the requested columns and reserve their measured footprint.
 
     A single legend is shared across panels. Only one full canvas draw is used
@@ -314,22 +324,23 @@ def _place_outside_legend(fig, axes, position="right", font_size=12, ncol=1):
         legend.set_bbox_to_anchor((.5, y), transform=fig.transFigure)
     legend.set_in_layout(False)
     if len(axes) > 1:
-        # Keep the legend reservation, but restore V77-like breathing room
+        # Keep the legend reservation, but reserve more breathing room
         # between facet axes.  This changes only the internal subplot gaps.
-        fig.subplots_adjust(wspace=0.34, hspace=0.44)
+        fig.subplots_adjust(wspace=panel_wspace, hspace=panel_hspace)
 
 def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
                               legend_labels="", trace_colors="", palette="Default",
                               x_min="", x_max="", y_min="", y_max="",
                               template="plotly", legend_position="right",
-                              legend_inside=False, legend_columns=1, show_grid=True, font_size=12,
+                              legend_inside=False, legend_columns=1, multi_y_color_by="group", show_grid=True, font_size=12,
                               line_width=2, marker_size=7, line_alpha="", line_style="",
                               scatter_size="", scatter_marker="", scatter_alpha="", hist_alpha="",
-                              box_showfliers=True, box_orientation="vertical",
+                              box_showfliers=True, box_orientation="vertical", bar_box_width=1.0,
                               title_font_size=14, axis_font_size=12, tick_font_size=10,
                               legend_font_size=12, panel_font_size=14, plot_dpi=100, bins=30, density=False,
                               stacked=False, histtype="bar", cumulative=0,
-                              panel_by=None, independent_panel_limits=True, panel_titles="", _axes=None,
+                              panel_by=None, independent_panel_limits=True, panel_titles="",
+                              panel_hspace=0.90, panel_wspace=0.38, _axes=None,
                               x_major_ticks=6, y_major_ticks=6, x_minor_ticks=False, y_minor_ticks=False):
     """Draw directly from the filtered/aggregated DataFrame, without Plotly."""
     import matplotlib
@@ -364,11 +375,12 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
             plt.close(fig)
             ncols = (2 if len(partitions) == 4 else min(3, len(partitions)))
             nrows = math.ceil(len(partitions) / ncols)
-            fig, axes = plt.subplots(nrows, ncols, figsize=(5*ncols, 3.8*nrows), dpi=plot_dpi,
+            fig, axes = plt.subplots(nrows, ncols, figsize=(5.4*ncols, 4.7*nrows), dpi=plot_dpi,
                                      squeeze=False, sharex=False, sharey=False)
             for idx, (panel_title, panel_df, other_groups) in enumerate(partitions):
                 panel_spec = {**spec, "data": panel_df, "groups": other_groups,
-                              "_hide_ungrouped_legend": not bool(other_groups)}
+                              "_original_groups": spec["groups"],
+                              "_hide_ungrouped_legend": not bool(other_groups) and not bool(spec.get("hist_variables"))}
                 panel_ax = axes.flat[idx]
                 _matplotlib_direct_figure(panel_spec, title=panel_title_map.get(panel_title, panel_title), x_label=x_label,
                     y_label=y_label, legend_labels=legend_labels, trace_colors=trace_colors,
@@ -376,10 +388,11 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
                     x_min=_panel_limit_value(x_min, panel_title), x_max=_panel_limit_value(x_max, panel_title),
                     y_min=_panel_limit_value(y_min, panel_title), y_max=_panel_limit_value(y_max, panel_title),
                     template=template, legend_position=legend_position,
-                    legend_inside=legend_inside, legend_columns=legend_columns, show_grid=show_grid, font_size=font_size,
+                    legend_inside=legend_inside, legend_columns=legend_columns, multi_y_color_by=multi_y_color_by, show_grid=show_grid, font_size=font_size,
                     line_width=line_width, marker_size=marker_size, line_alpha=line_alpha, line_style=line_style,
                     scatter_size=scatter_size, scatter_marker=scatter_marker, scatter_alpha=scatter_alpha,
                     hist_alpha=hist_alpha, box_showfliers=box_showfliers, box_orientation=box_orientation,
+                    bar_box_width=bar_box_width,
                     title_font_size=panel_font_size, axis_font_size=axis_font_size,
                     tick_font_size=tick_font_size, legend_font_size=legend_font_size,
                     panel_font_size=panel_font_size, plot_dpi=plot_dpi,
@@ -394,15 +407,17 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
                     if panel_ax.get_legend() is not None:
                         panel_ax.get_legend().set_in_layout(False)
                 fig.tight_layout()
-                # V77 used tight_layout for facets; restore visible gutters
+                # V77 used tight_layout for facets; reserve generous gutters
                 # without changing V83's legend behaviour or column control.
-                fig.subplots_adjust(wspace=0.34, hspace=0.44)
+                fig.subplots_adjust(wspace=panel_wspace, hspace=panel_hspace)
                 _fit_inside_legends(fig, list(axes.flat)[:len(partitions)], legend_font_size, legend_columns)
             else:
                 _place_outside_legend(fig, list(axes.flat)[:len(partitions)],
-                                      legend_position, legend_font_size, legend_columns)
+                                      legend_position, legend_font_size, legend_columns,
+                                      panel_hspace=panel_hspace, panel_wspace=panel_wspace)
             return fig
-    group_col = "__plot_group" if spec["groups"] and "__plot_group" in df.columns else None
+    group_col = ("__hist_series" if kind == "histogram" and spec.get("hist_variables")
+                 else "__plot_group" if spec["groups"] and "__plot_group" in df.columns else None)
     defaults = _matplotlib_defaults(spec, palette=palette)
     rename = _parse_label_map(legend_labels)
     overrides = _parse_label_map(trace_colors)
@@ -413,6 +428,11 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
     labels = defaults["names"] if group_col else ([str(y) for y in ys] if len(ys) > 1 else ["All observations"])
     colors = {name: overrides.get(name, defaults["colors"].get(name, palette_values[i % len(palette_values)]))
               for i, name in enumerate(labels)}
+    multi_y = kind == "line" and len(ys) > 1
+    if multi_y:
+        from .multi_y import multi_y_styles
+        multi_colors, multi_dashes, variable_names, group_names = multi_y_styles(
+            ys, labels if group_col else [], palette_values, multi_y_color_by, overrides, styles)
     for name, color in list(colors.items()):
         if not mcolors.is_color_like(color):
             colors[name] = defaults["colors"].get(name, palette_values[0])
@@ -420,11 +440,101 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
     def series():
         if group_col:
             for name in labels:
-                yield name, df.loc[df[group_col] == name]
+                yield name, df.loc[df[group_col].astype(str) == str(name)]
         else:
             yield "All observations", df
 
-    if kind == "histogram":
+    if spec.get("multi_axis"):
+        from .multi_axis import records, style_maps
+        from matplotlib.lines import Line2D
+        from matplotlib.patches import Patch
+        entries = list(records(spec))
+        color_map, dash_map, style_groups = style_maps(spec, multi_y_color_by, palette, trace_colors)
+        variable_names = list(ys)
+        x_names = list(spec.get("x_variables", [x]))
+        group_names = style_groups if group_col else []
+        active = set()
+        if kind == "scatter":
+            scatter_markers = ['o', 's', 'D', 'x', '^', 'v', 'P', '*']
+            for key, group, y, xv, category, rows in entries:
+                g = group if group_col else None
+                active.add((y, g))
+                ax.scatter(rows[xv], rows[y], color=color_map[(y, g)],
+                           marker=scatter_markers[x_names.index(xv) % len(scatter_markers)],
+                           s=marker_size**2, alpha=.8)
+        else:
+            cats = list(pd.unique(df[x].astype(str)))
+            combinations = [(g, y) for g in (group_names or ['All observations']) for y in ys]
+            n = max(1, len(combinations))
+            width = .82 / n
+            from collections import defaultdict
+            buckets = defaultdict(list)
+            for key, group, y, xv, category, rows in entries:
+                g = group if group_col else None
+                active.add((y, g))
+                idx = combinations.index((group, y))
+                pos = cats.index(category) + (idx - (n - 1)/2)*width
+                values = pd.to_numeric(rows[y], errors='coerce').dropna().to_numpy(dtype=float)
+                buckets[(pos, y, g)].extend(values)
+            for (pos, y, g), values in buckets.items():
+                if not values:
+                    continue
+                color = color_map[(y, g)]
+                hatch_options = ['', '/', '\\', 'x', '.', '+', '-']
+                hatch_index = ys.index(y) if multi_y_color_by == 'group' else (group_names.index(g) if g in group_names else 0)
+                hatch = '' if multi_y_color_by in ('none', 'both') else hatch_options[hatch_index % len(hatch_options)]
+                if kind == 'bar':
+                    ax.bar(pos, sum(values), width=width*.92*bar_box_width, color=color, hatch=hatch)
+                else:
+                    bp = ax.boxplot([values], positions=[pos], widths=width*.92*bar_box_width,
+                                    manage_ticks=False, patch_artist=True,
+                                    showfliers=bool(box_showfliers),
+                                    vert=(box_orientation != 'horizontal'))
+                    bp['boxes'][0].set_facecolor(color)
+                    bp['boxes'][0].set_hatch(hatch)
+                    bp['boxes'][0].set_alpha(.7)
+            if kind == 'box' and box_orientation == 'horizontal':
+                ax.set_yticks(range(len(cats)), cats)
+                ax.set_ylim(-.5, max(.5, len(cats)-.5))
+            else:
+                ax.set_xticks(range(len(cats)), cats)
+                ax.set_xlim(-.5, max(.5, len(cats)-.5))
+        handles, legend_names = [], []
+        def legend_entry(label, color, marker=None):
+            handles.append(Line2D([], [], color=color, marker=marker or None,
+                                  linestyle='None' if marker else '-', linewidth=2))
+            legend_names.append(rename.get(label, label))
+        if multi_y_color_by == 'none':
+            for g in group_names:
+                if any((y, g) in active for y in ys):
+                    legend_entry(g, color_map[(ys[0], g)])
+        elif multi_y_color_by == 'both':
+            for g in (group_names or [None]):
+                for y in ys:
+                    if (y, g) in active:
+                        legend_entry(f'{g}, {y}' if g is not None else y, color_map[(y, g)])
+        else:
+            for y in ys:
+                pairs = [(y, g) for g in (group_names or [None]) if (y, g) in active]
+                if pairs:
+                    legend_entry(y, color_map[pairs[0]])
+            if group_names:
+                handles.append(Line2D([], [], color='none'))
+                legend_names.append(' ')
+                for g in group_names:
+                    pairs = [(y, g) for y in ys if (y, g) in active]
+                    if pairs:
+                        legend_entry(g, color_map[pairs[0]])
+        if kind == 'scatter' and len(x_names) > 1:
+            if handles:
+                handles.append(Line2D([], [], color='none'))
+                legend_names.append(' ')
+            for i, xv in enumerate(x_names):
+                if any(entry[3] == xv for entry in entries):
+                    legend_entry(xv, '#666666', ['o', 's', 'D', 'x', '^', 'v', 'P', '*'][i % 8])
+        if handles and not spec.get('_hide_ungrouped_legend', False):
+            ax.legend(handles, legend_names)
+    elif kind == "histogram":
         arrays = []
         for name, rows in series():
             vals = pd.to_numeric(rows[x], errors="coerce").to_numpy(dtype=float)
@@ -476,15 +586,19 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
             else:
                 sets = [(str(y) if len(ys) > 1 else "All observations", line_df)]
             for name, rows in sets:
+                rows = rows.loc[rows[y].notna()]
+                if rows.empty:
+                    continue
                 segment_col = section_col or id_col
                 parts = (rows.groupby(segment_col, dropna=False, sort=False) if segment_col else [(None, rows)])
                 for _, part in parts:
                     part = part.sort_values(x)
-                    ax.plot(part[x], part[y], color=colors.get(name, palette_values[0]),
+                    key = (str(y), str(name) if group_col else None)
+                    ax.plot(part[x], part[y], color=(multi_colors[key] if multi_y else colors.get(name, palette_values[0])),
                             linewidth=float(line_width),
-                            linestyle=_line_style(styles, name),
+                            linestyle=(multi_dashes[key] if multi_y else _line_style(styles, name)),
                             alpha=_bounded_float(alphas, name, 1, 0, 1),
-                            label=rename.get(name, name))
+                            label=("_nolegend_" if multi_y else rename.get(name, name)))
     elif kind in ("box", "bar"):
         # Build categorical groups in a single pass. The former implementation
         # repeatedly scanned the full DataFrame for every category × group,
@@ -534,7 +648,7 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
             for category_index, group_index, position in zip(ci[valid_array], names, positions):
                 palette_for_positions[float(position)] = colors.get(group_names[group_index], palette_values[0])
             if xpos:
-                ax.bar(xpos, [totals[pos] for pos in xpos], width=width * .92,
+                ax.bar(xpos, [totals[pos] for pos in xpos], width=width * .92 * bar_box_width,
                        color=[palette_for_positions[pos] for pos in xpos])
         else:
             # Calculate group memberships once and make one boxplot call.
@@ -547,13 +661,25 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
             if buckets:
                 box_positions = sorted(buckets)
                 bp = ax.boxplot([buckets[pos] for pos in box_positions],
-                                positions=box_positions, widths=width * .92,
+                                positions=box_positions, widths=width * .92 * bar_box_width,
                                 manage_ticks=False, patch_artist=True,
                                 showfliers=bool(box_showfliers),
                                 vert=(box_orientation != "horizontal"))
                 for patch, position in zip(bp["boxes"], box_positions):
                     patch.set_facecolor(bucket_colors[position])
                     patch.set_alpha(.7)
+                if box_showfliers:
+                    # Explicitly reset numeric limits using all observations;
+                    # avoids retaining whisker-only limits after facet changes.
+                    all_values = np.asarray(numeric, dtype=float)
+                    all_values = all_values[np.isfinite(all_values)]
+                    if all_values.size:
+                        low, high = float(all_values.min()), float(all_values.max())
+                        margin = .05 * (high - low) if high > low else max(abs(low) * .05, .5)
+                        if box_orientation == "horizontal":
+                            ax.set_xlim(low - margin, high + margin)
+                        else:
+                            ax.set_ylim(low - margin, high + margin)
                 if not box_showfliers:
                     # Autoscaling normally includes every observation in the
                     # data; instead use only the whisker endpoints.
@@ -588,11 +714,52 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
     else:
         raise ValueError(f"Unknown plot type: {kind}")
 
-    if kind not in ("box", "bar"):
+    if kind not in ("box", "bar") and not spec.get("multi_axis"):
         handles, texts = ax.get_legend_handles_labels()
         unique = dict(zip(texts, handles))
         if unique and not spec.get("_hide_ungrouped_legend", not bool(spec["groups"])):
             ax.legend(unique.values(), unique.keys(), title="Legend")
+    if multi_y:
+        from matplotlib.lines import Line2D
+        # Independent legend keys for the two dimensions, with explicit headings.
+        legend_handles = []
+        legend_labels_out = []
+        active = {(str(y), str(g) if group_col else None)
+                  for y in ys for g in (group_names if group_col else [None])
+                  if not df.loc[(df[group_col] == g) if group_col else slice(None), y].dropna().empty}
+        if multi_y_color_by == "none":
+            for group in group_names if group_col else []:
+                if not any((v, group) in active for v in variable_names):
+                    continue
+                key = (variable_names[0], group)
+                legend_handles.append(Line2D([], [], color=multi_colors[key], linestyle=multi_dashes[key], linewidth=line_width))
+                legend_labels_out.append(rename.get(group, group))
+        if multi_y_color_by == "both":
+            for group in (group_names or [None]):
+                for variable in variable_names:
+                    key = (variable, group)
+                    label = f"{group}, {variable}" if group is not None else variable
+                    legend_handles.append(Line2D([], [], color=multi_colors[key], linestyle=multi_dashes[key], linewidth=line_width))
+                    legend_labels_out.append(rename.get(label, label))
+        added_section = False
+        for heading, keys, by_var in (() if multi_y_color_by in ("both", "none") else (("Y variable", variable_names, True), ("Grouping", group_names, False))):
+            if not keys or (not by_var and not group_col):
+                continue
+            if added_section:
+                legend_handles.append(Line2D([], [], color="none"))
+                legend_labels_out.append(" ")
+            added_section = True
+            legend_handles.append(Line2D([], [], color="none"))
+            legend_labels_out.append(heading)
+            for value in keys:
+                relevant = [pair for pair in active if (pair[0] == value if by_var else pair[1] == value)]
+                if not relevant:
+                    continue
+                key = relevant[0]
+                legend_handles.append(Line2D([], [], color=multi_colors[key], linestyle=multi_dashes[key], linewidth=line_width))
+                legend_labels_out.append(rename.get(value, value))
+        if legend_handles:
+            ax.legend(legend_handles, legend_labels_out, title=None)
     legend = ax.get_legend()
     if legend is not None:
         locs = {"right":"upper right", "left":"upper left", "top":"upper center", "bottom":"lower center"}