apmtools 0.2.58__tar.gz → 0.2.60__tar.gz

{apmtools-0.2.58 → apmtools-0.2.60}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: apmtools
-Version: 0.2.58
+Version: 0.2.60
 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.58 → apmtools-0.2.60}/pyproject.toml

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

{apmtools-0.2.58 → apmtools-0.2.60}/src/apmtools/completeness.py

@@ -82,10 +82,25 @@ def analyse_completeness(data, value_cols, frequency, *, time_col='datetime',
     values = list(value_cols)
     if not values:
         raise ValueError('value_cols must not be empty')
+    # Each column must have one unambiguous role.  In particular, selecting
+    # the timestamp as the monitor ID makes pandas return a two-column frame
+    # for frame[time_col], which pd.to_datetime cannot convert.
     required = [id_col, time_col, *values]
+    if len(set(required)) != len(required):
+        raise ValueError(
+            'Identifier, timestamp and measurement columns must be distinct; '
+            'choose different columns in Coverage analysis.'
+        )
     absent = [name for name in required if name not in data.columns]
     if absent:
         raise KeyError(f'Missing completeness columns: {absent}')
+    # Avoid silently choosing one of several identically named source columns.
+    duplicates = [name for name in required if list(data.columns).count(name) > 1]
+    if duplicates:
+        raise ValueError(
+            f'Duplicate source column names {list(dict.fromkeys(duplicates))!r}; '
+            'rename them before calculating completeness.'
+        )
     frame = pd.DataFrame(data)[required].copy()
     frame[time_col] = pd.to_datetime(frame[time_col], errors='coerce')
     frame = frame.dropna(subset=[id_col, time_col])

apmtools-0.2.60/src/apmtools/shiny/bar_axis_autoscale.py

@@ -0,0 +1,37 @@
+"""Distinguish auto-populated bar-axis input text from explicit bounds.
+
+The Shiny UI historically writes data-derived limits into the same controls
+used for manual overrides.  A browser update can lag one render behind a
+change in stacking.  Recognising both previous and current generated values
+prevents that stale text being interpreted as an explicit clipping limit.
+"""
+from __future__ import annotations
+
+
+def remember_auto_limits(history, limits):
+    """Record the displayed default bounds for comparison across redraws."""
+    for field in ('y_min', 'y_max'):
+        text = str(limits.get(field, '') or '').strip()
+        if text:
+            seen = history.setdefault(field, [])
+            if text not in seen:
+                seen.append(text)
+                # Avoid retaining every value ever produced by past datasets.
+                if len(seen) > 8:
+                    del seen[:-8]
+
+
+def release_automatic_bar_limits(options, history, *, protected=()):
+    """Let Matplotlib autoscale limits that the UI filled automatically.
+
+    Bounds different from the generated values are user edits and remain
+    explicit.  Restored explicit saved limits are also protected.
+    """
+    resolved = dict(options)
+    for field in ('y_min', 'y_max'):
+        if field in protected:
+            continue
+        text = str(options.get(field, '') or '').strip()
+        if text in history.get(field, ()):
+            resolved[field] = ''
+    return resolved

apmtools-0.2.60/src/apmtools/shiny/bar_stacking.py

@@ -0,0 +1,58 @@
+"""Stacked-bar grouping, with series identity independent of panel facets."""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def selected_stack_columns(groups, stacking, panels=()):
+    """Retain requested stack dimensions that are grouped and not faceted."""
+    requested = [stacking] if isinstance(stacking, str) else (stacking or ())
+    panels = [panels] if isinstance(panels, str) else (panels or ())
+    return [name for name in dict.fromkeys(requested)
+            if name in groups and name not in panels]
+
+
+def stacked_bar_legend_key(series_key, stack_key):
+    """Legend identity for one combination of adjacent and stacked groups.
+
+    Keep the existing stack-only name when no adjacent grouping remains.  Y
+    variables distinguish adjacent bar positions, not grouping combinations.
+    """
+    adjacent_group = series_key[0]
+    return f"{adjacent_group} | {stack_key}" if adjacent_group else stack_key
+
+
+def stacked_bar_segments(spec, stacking):
+    """Yield (x category, adjacent series, stack key, value), in data order.
+
+    Aggregate duplicate source rows by summation, matching ordinary barplots.
+    Adjacent series are combinations of non-stacking grouping columns and Y
+    variables; selected stack dimensions identify the segments within a bar.
+    """
+    frame = spec['data']
+    selected = [c for c in selected_stack_columns(spec.get('groups', ()), stacking)
+                if c in frame.columns]
+    if not selected or spec.get('kind') != 'bar' or frame.empty:
+        return []
+    remaining = [c for c in spec['groups'] if c not in selected and c in frame.columns]
+    cols = [spec['x'], *remaining, *selected]
+    ys = [y for y in spec['ys'] if y in frame.columns]
+    if not ys:
+        return []
+    result = []
+    for keys, group in frame.groupby(cols[0] if len(cols) == 1 else cols,
+                                     sort=False, dropna=False, observed=True):
+        vals = keys if isinstance(keys, tuple) else (keys,)
+        category = str(vals[0])
+        sides = tuple('None' if pd.isna(v) else str(v) for v in vals[1:1+len(remaining)])
+        stacks = tuple('None' if pd.isna(v) else str(v) for v in vals[1+len(remaining):])
+        side_label = ' | '.join(sides)
+        stack_label = ' | '.join(stacks)
+        for y in ys:
+            numeric = pd.to_numeric(group[y], errors='coerce').to_numpy(dtype=float, na_value=np.nan)
+            valid = numeric[np.isfinite(numeric)]
+            if valid.size:
+                series = (side_label, str(y) if len(ys) > 1 else '')
+                result.append((category, series, stack_label, float(valid.sum())))
+    return result

{apmtools-0.2.58 → apmtools-0.2.60}/src/apmtools/shiny/color_editor.py

@@ -9,7 +9,7 @@ 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=()):
+def active_color_keys(spec, *, mode="group", panel_by=(), bar_stacking=()):
     """Return colour dimensions with nonempty plotted observations.
 
     Faceting removes its grouping columns. For multi-Y plots, 'both' uses
@@ -21,6 +21,12 @@ def active_color_keys(spec, *, mode="group", panel_by=()):
     if spec.get("hist_variables"):
         return tuple(dict.fromkeys(spec["data"].loc[
             spec["data"][spec["x"]].notna(), "__hist_series"].astype(str)))
+    if spec.get("kind") == "bar" and bar_stacking:
+        from .bar_stacking import stacked_bar_segments, stacked_bar_legend_key
+        panel_vars = [panel_by] if isinstance(panel_by, str) else list(panel_by or ())
+        active_spec = {**spec, "groups": [g for g in spec["groups"] if g not in panel_vars]}
+        return tuple(dict.fromkeys(stacked_bar_legend_key(segment[1], segment[2])
+                                   for segment in stacked_bar_segments(active_spec, bar_stacking)))
     from .matplotlib_renderer import _panel_partitions
     from .multi_axis import records
     parts = (_panel_partitions(spec, panel_by) if panel_by

{apmtools-0.2.58 → apmtools-0.2.60}/src/apmtools/shiny/data.py

@@ -11,6 +11,21 @@ from ..units import upas_units, lascar_units, purple_units
 from .config import VARIABLE_UNITS, PLOT_TYPES, FREQUENCIES, AGGREGATES, _MPL_PALETTES
 
 
+def bar_box_category_choices(categorical_columns, selected_frequency, selected_statistics=None):
+    """Add the selected frequency category only with active statistical aggregation.
+
+    Original categorical columns are always available. A generated temporal
+    category is available only when both frequency and statistic are selected.
+    """
+    frequency = FREQUENCIES.get(selected_frequency, selected_frequency)
+    choices = list(categorical_columns)
+    from .view_aggregation import normalize_statistics
+    if (normalize_statistics(selected_statistics) and frequency is not None
+            and frequency in FREQUENCIES.values() and frequency not in choices):
+        choices.append(frequency)
+    return choices
+
+
 def _composite_labels(data: pd.DataFrame, columns: list[str]) -> pd.Series:
     """Build readable composite labels without dropping or coercing missing groups.
 

{apmtools-0.2.58 → apmtools-0.2.60}/src/apmtools/shiny/export.py

@@ -34,7 +34,11 @@ def _standalone_matplotlib_script(spec, options):
     import inspect
     import pprint
 
+    from .bar_stacking import selected_stack_columns, stacked_bar_segments, stacked_bar_legend_key
+    from .legend_identity import canonical_legend_key, canonical_legend_map, legend_label
     dependencies = (
+        selected_stack_columns, stacked_bar_segments, stacked_bar_legend_key,
+        canonical_legend_key, canonical_legend_map, legend_label,
         _axis_label, _parse_label_map, _series_style_maps, _bounded_float,
         _line_style, _scatter_marker, _composite_labels,
         _frequency_timedelta, _add_gap_sections, _matplotlib_defaults,
@@ -43,6 +47,17 @@ def _standalone_matplotlib_script(spec, options):
         _fit_inside_legends, _place_outside_legend, _matplotlib_direct_figure,
     )
     source = "\n\n".join(inspect.getsource(fn) for fn in dependencies)
+    # Stacking helpers are embedded above, not imported from a package in the
+    # standalone script. Other legacy renderer imports are unchanged.
+    source = source.replace("from .bar_stacking import stacked_bar_segments, stacked_bar_legend_key", "")
+    source = source.replace("from .bar_stacking import stacked_bar_segments", "")
+    source = source.replace("from .bar_stacking import selected_stack_columns", "")
+    source = source.replace("from .bar_stacking import stacked_bar_legend_key", "")
+    source = source.replace("from .legend_identity import canonical_legend_map, legend_label", "")
+    # Profiling decorators belong to the package and are not available in the
+    # standalone script; strip them from embedded source.
+    source = "\n".join(line for line in source.split("\n")
+                       if not line.lstrip().startswith("@traced("))
     metadata = {key: spec.get(key) for key in
                 ("kind", "x", "ys", "groups", "categories", "frequency")}
     date_columns = [str(c) for c in spec["data"].columns
@@ -52,7 +67,7 @@ def _standalone_matplotlib_script(spec, options):
         '# Run: python plot_script.py\n'
         '# Dependencies: pip install pandas numpy matplotlib\n'
         'from pathlib import Path\n'
-        'import pandas as pd\nimport numpy as np\n'
+        'import pandas as pd\nimport numpy as np\nimport re\n'
         'from datetime import datetime, date, timedelta\n\n'
         'VARIABLE_UNITS = ' + pprint.pformat(VARIABLE_UNITS, sort_dicts=True) + '\n'
         '_MPL_PALETTES = ' + pprint.pformat(_MPL_PALETTES, sort_dicts=True) + '\n\n'

{apmtools-0.2.58 → apmtools-0.2.60}/src/apmtools/shiny/matplotlib_renderer.py

@@ -39,7 +39,7 @@ def _matplotlib_defaults(spec, *, palette="Default"):
 
 
 
-def _axis_bounds_from_spec(spec, *, bins=30, density=False, stacked=False, cumulative=0):
+def _axis_bounds_from_spec(spec, *, bins=30, density=False, stacked=False, cumulative=0, bar_stacking=()):
     """Compute editable axis bounds from the prepared data, without rendering.
 
     Datetime X bounds are ISO timestamps; categorical X bounds are intentionally
@@ -97,6 +97,16 @@ def _axis_bounds_from_spec(spec, *, bins=30, density=False, stacked=False, cumul
             ymax = (histograms.sum(axis=0).max() if stacked and histograms.size
                     else histograms.max() if histograms.size else 0)
             bounds["y_min"], bounds["y_max"] = "0", format(float(ymax), ".12g")
+    elif kind == "bar" and bar_stacking:
+        from .bar_stacking import stacked_bar_segments
+        segments = stacked_bar_segments(spec, bar_stacking)
+        if segments:
+            from collections import defaultdict
+            totals = defaultdict(float)
+            for category, series, stack, value in segments:
+                totals[(category, series, value >= 0)] += value
+            bounds["y_min"] = format(float(min(0, *totals.values())), ".12g")
+            bounds["y_max"] = format(float(max(0, *totals.values())), ".12g")
     elif kind == "bar":
         values = pd.to_numeric(df[ys[0]], errors="coerce")
         cols = [x, "__plot_group"] if spec["groups"] else [x]
@@ -302,10 +312,14 @@ def _place_outside_legend(fig, axes, position="right", font_size=12, ncol=1,
         old = ax.get_legend()
         if old is None:
             continue
+        identities = getattr(old, "_apmtools_stack_keys", None)
         for index, (handle, label) in enumerate(zip(old.legend_handles,
                                  [t.get_text() for t in old.get_texts()])):
-            if label and index not in seen:
-                seen[index] = (handle, label)
+            # Stacked bar series may differ in number and order across facets.
+            # Use their unedited group-combination identity rather than position.
+            key = ("stack", identities[index]) if identities is not None else ("position", index)
+            if label and key not in seen:
+                seen[key] = (handle, label)
         old.set_visible(False)
         old.set_in_layout(False)
     if not seen:
@@ -356,9 +370,10 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
                               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", bar_box_width=1.0,
+                              box_showfliers=True, box_orientation="vertical", bar_box_width=1.0, bar_stacking=None,
                               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,
+                              legend_font_size=12, panel_font_size=14, plot_dpi=100,
+                              plot_height_pct=100, bins=30, density=False,
                               stacked=False, histtype="bar", cumulative=0,
                               panel_by=None, independent_panel_limits=True, panel_titles="",
                               panel_hspace=0.90, panel_wspace=0.38, _axes=None,
@@ -371,7 +386,7 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
     from matplotlib.patches import Patch
 
     if _axes is None:
-        fig, ax = plt.subplots(figsize=(10, 5), dpi=plot_dpi)
+        fig, ax = plt.subplots(figsize=(10, 5 * float(plot_height_pct) / 100), dpi=plot_dpi)
     else:
         ax = _axes
         fig = ax.figure
@@ -389,8 +404,22 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
 
     # Facet only the native Matplotlib renderer.  Each panel receives the
     # same filtered/aggregated data subset and the same appearance settings.
+    if panel_by and _axes is None:
+        # A dimension cannot simultaneously define facets and stack segments.
+        from .bar_stacking import selected_stack_columns
+        blocked = selected_stack_columns(spec.get("groups", ()), bar_stacking) if kind == "bar" else []
+        panel_by = [name for name in ([panel_by] if isinstance(panel_by, str) else panel_by)
+                    if name not in blocked]
     if panel_by and _axes is None:
         import math
+        from .bar_stacking import stacked_bar_segments
+        panel_groups = [panel_by] if isinstance(panel_by, str) else list(panel_by)
+        palette_spec = {**spec, "groups": [g for g in spec["groups"] if g not in panel_groups]}
+        from .bar_stacking import stacked_bar_legend_key
+        full_stack_palette = (list(dict.fromkeys(
+            stacked_bar_legend_key(item[1], item[2])
+            for item in stacked_bar_segments(palette_spec, bar_stacking)))
+                              if kind == "bar" and bar_stacking else [])
         partitions = list(_panel_partitions(spec, panel_by))
         panel_title_map = _parse_label_map(panel_titles)
         if partitions:
@@ -402,11 +431,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.4*ncols, 4.7*nrows), dpi=plot_dpi,
+            fig, axes = plt.subplots(nrows, ncols, figsize=(5.4*ncols, 4.7*nrows * float(plot_height_pct) / 100), 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,
                               "_original_groups": spec["groups"],
+                              "_stack_palette": full_stack_palette,
                               "_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,
@@ -419,10 +449,11 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
                     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,
+                    bar_box_width=bar_box_width, bar_stacking=bar_stacking,
                     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,
+                    plot_height_pct=plot_height_pct,
                     bins=bins, density=density,
                     stacked=stacked, histtype=histtype, cumulative=cumulative, _axes=panel_ax,
                     x_major_ticks=x_major_ticks, y_major_ticks=y_major_ticks,
@@ -433,6 +464,21 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
             active_axes = [flat_axes[i] for i in range(len(partitions))]
             for i in range(len(partitions), axes.size):
                 flat_axes[i].set_visible(False)
+            if kind == "bar" and bar_stacking and not independent_panel_limits:
+                # Matplotlib independently autoscales each facet because their
+                # axes are intentionally created with sharey=False.  Apply the
+                # common stacked range *after* drawing all facets, so the
+                # checkbox actually determines whether scales are shared.
+                # Individual manual panel bounds still take precedence.
+                lows, highs = zip(*(panel_ax.get_ylim() for panel_ax in active_axes))
+                common_low, common_high = min(lows), max(highs)
+                for (panel_title, _, _), panel_ax in zip(partitions, active_axes):
+                    lower = _parse_axis_limit(_panel_limit_value(y_min, panel_title))
+                    upper = _parse_axis_limit(_panel_limit_value(y_max, panel_title))
+                    panel_ax.set_ylim(
+                        common_low if lower is None else lower,
+                        common_high if upper is None else upper,
+                    )
             if legend_inside:
                 for panel_ax in active_axes:
                     if panel_ax.get_legend() is not None:
@@ -478,7 +524,45 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
         else:
             yield "All observations", df
 
-    if spec.get("multi_axis"):
+    if kind == "bar" and bar_stacking and any(
+            col in df.columns and col in spec["groups"] for col in bar_stacking):
+        from .bar_stacking import stacked_bar_segments, stacked_bar_legend_key
+        segments = stacked_bar_segments(spec, bar_stacking)
+        cats = list(dict.fromkeys(str(v) for v in df[x]))
+        series_keys = list(dict.fromkeys(item[1] for item in segments))
+        # Colour and legend identities must include non-stacking grouping
+        # dimensions too; they determine adjacent bars within each category.
+        legend_keys = list(dict.fromkeys(
+            stacked_bar_legend_key(item[1], item[2]) for item in segments))
+        cat_idx = {cat: i for i, cat in enumerate(cats)}
+        series_idx = {item: i for i, item in enumerate(series_keys)}
+        bar_width = .82 / max(len(series_keys), 1)
+        stacks_positive, stacks_negative = {}, {}
+        palette_keys = spec.get("_stack_palette") or legend_keys
+        stack_colors = {name: overrides.get(name,
+                           palette_values[palette_keys.index(name) % len(palette_values)]
+                           if name in palette_keys else palette_values[0])
+                        for name in legend_keys}
+        for (category, series_key, stack_key, amount) in segments:
+            legend_key = stacked_bar_legend_key(series_key, stack_key)
+            slot = (category, series_key)
+            base_map = stacks_positive if amount >= 0 else stacks_negative
+            base = base_map.get(slot, 0.0)
+            pos = cat_idx[category] + (series_idx[series_key] - (len(series_keys) - 1) / 2) * bar_width
+            ax.bar(pos, amount, bottom=base, width=bar_width * .92 * bar_box_width,
+                   color=stack_colors[legend_key],
+                   label=legend_label(rename, legend_key, aliases))
+            base_map[slot] = base + amount
+        ax.set_xticks(range(len(cats)), cats)
+        ax.set_xlim(-.5, max(.5, len(cats) - .5))
+        # Preserve a separate handle for every actual group combination,
+        # even if its user-edited display label equals another entry's.
+        if legend_keys and not spec.get("_hide_ungrouped_legend", False):
+            stack_legend = ax.legend(handles=[Patch(facecolor=stack_colors[name],
+                                     label=legend_label(rename, name, aliases))
+                               for name in legend_keys], title="Legend")
+            stack_legend._apmtools_stack_keys = tuple(legend_keys)
+    elif spec.get("multi_axis"):
         from .multi_axis import records, style_maps
         from matplotlib.lines import Line2D
         from matplotlib.patches import Patch
@@ -637,6 +721,11 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
         # avoiding repeated full-column masks for multi-Y plots.
         grouped_line_rows = ([(n, line_df.loc[line_df[group_col] == n]) for n in labels]
                              if group_col else None)
+        # A group can contain many independent traces (e.g. one per identifier
+        # or per missing-data section).  Their visual identity is the GROUP,
+        # not the individual trace.  Collect only groups actually drawn so the
+        # legend and the editable label keys have one entry per group value.
+        plotted_line_groups = set()
         for y in ys:
             sets = (grouped_line_rows if grouped_line_rows is not None else
                     [(str(y) if len(ys) > 1 else "All observations", line_df)])
@@ -644,6 +733,7 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
                 rows = rows.loc[rows[y].notna()]
                 if rows.empty:
                     continue
+                plotted_line_groups.add(str(name))
                 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:
@@ -655,7 +745,21 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
                                        _line_style(styles, name) if name in styles and len(ys) == 1 else
                                        multi_dashes[key]),
                             alpha=_bounded_float(alphas, name, 1, 0, 1),
-                            label=("_nolegend_" if multi_y else legend_label(rename, name, aliases)))
+                            # Repeated identifier/section traces must not
+                            # create repeated legend entries for one group.
+                            label="_nolegend_")
+        if group_col and not multi_y and not spec.get("_hide_ungrouped_legend", False):
+            from matplotlib.lines import Line2D
+            visible_groups = [name for name in labels if name in plotted_line_groups]
+            if visible_groups:
+                handles = [Line2D([], [], color=colors[name],
+                                  linewidth=float(line_width),
+                                  linestyle=_line_style(styles, name),
+                                  alpha=_bounded_float(alphas, name, 1, 0, 1))
+                           for name in visible_groups]
+                ax.legend(handles,
+                          [legend_label(rename, name, aliases) for name in visible_groups],
+                          title="Legend")
     elif kind in ("box", "bar"):
         # Build categorical groups in a single pass. The former implementation
         # repeatedly scanned the full DataFrame for every category × group,

apmtools-0.2.60/src/apmtools/shiny/panel_activation.py

@@ -0,0 +1,11 @@
+"""Explicit panel selection and stacking eligibility for Shiny plot views."""
+
+
+def selected_panel_groups(groups, requested, excluded=()):
+    """Return eligible, explicitly selected panel dimensions in user order.
+
+    An empty selection never implies all available grouping columns.  The
+    enabled/disabled state of the panel controls is handled separately by UI.
+    """
+    eligible = set(groups or ()) - set(excluded or ())
+    return list(dict.fromkeys(name for name in (requested or ()) if name in eligible))

{apmtools-0.2.58 → apmtools-0.2.60}/src/apmtools/shiny/profiling.py

@@ -7,6 +7,7 @@ row values or input contents. Each record is one JSON object.
 from __future__ import annotations
 
 import contextvars
+from collections import deque
 import functools
 import json
 import os
@@ -18,6 +19,28 @@ import uuid
 _current_span = contextvars.ContextVar('apmtools_trace_span', default=None)
 _lock = threading.RLock()
 _session = uuid.uuid4().hex[:12]
+# Diagnostics are populated only when tracing is explicitly enabled.
+_reactive_recent = {}
+_reactive_alert_at = {}
+
+
+def _reactive_loop_warning(name, now=None, *, threshold=50, window=3.0):
+    """Flag unusually repeated effect executions; never diagnose with certainty.
+
+    Called only on the opt-in tracing path. Keep bounded per-name history, and
+    emit at most one warning per window to avoid a runaway diagnostic log.
+    """
+    now = time.monotonic() if now is None else now
+    with _lock:
+        recent = _reactive_recent.setdefault(name, deque(maxlen=threshold))
+        while recent and now - recent[0] > window:
+            recent.popleft()
+        recent.append(now)
+        if len(recent) < threshold or now - _reactive_alert_at.get(name, -float('inf')) < window:
+            return False
+        _reactive_alert_at[name] = now
+        return True
+
 
 
 def enabled():
@@ -71,6 +94,9 @@ def traced(label=None, *, kind='function', trigger=None):
                     _emit({'event': 'execution', 'kind': kind, 'name': name,
                            'trigger': trigger, 'span': span, 'parent': parent,
                            'duration_ms': round(duration / 1e6, 3), 'error': error})
+                    if kind == 'reactive_effect' and _reactive_loop_warning(name):
+                        _emit({'event': 'suspected_reactive_loop', 'kind': kind,
+                               'name': name, 'executions': 50, 'window_seconds': 3})
         wrapped.__wrapped_by_apmtools_trace__ = True
         return wrapped
     return decorate
@@ -95,6 +121,9 @@ async def _run_async(func, name, kind, trigger, args, kwargs):
         _emit({'event': 'execution', 'kind': kind, 'name': name,
                'trigger': trigger, 'span': span, 'parent': parent,
                'duration_ms': round(duration / 1e6, 3), 'error': error})
+        if kind == 'reactive_effect' and _reactive_loop_warning(name):
+            _emit({'event': 'suspected_reactive_loop', 'kind': kind,
+                   'name': name, 'executions': 50, 'window_seconds': 3})
 
 
 def marker(name, **metadata):

apmtools-0.2.60/src/apmtools/shiny/quality_filters.py

@@ -0,0 +1,76 @@
+"""Reusable, Shiny-independent subset filtering for quality dashboards."""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from datetime import datetime, time, timedelta
+from .data import _parse_datetime_filter, _subset_choices
+
+
+def filter_quality_data(frame, settings):
+    """Apply the same staged categorical, numeric and date filters as tables.
+
+    The configured selected values are Shiny selector *keys*, resolved against
+    the source dataframe. Missing numeric values remain unchanged, consistent
+    with the existing table filtering policy.
+    """
+    current = frame.copy()
+    for step in settings.get('subset_chain', []):
+        column = step.get('column')
+        if column not in current.columns:
+            continue
+        _, value_map = _subset_choices(frame, column)
+        values = [value_map[key] for key in step.get('values', []) if key in value_map]
+        if not values:
+            continue
+        style = step.get('style', 'all')
+        if hasattr(current, 'subset'):
+            current = current.subset({column: values}, filter_style=style)
+        else:
+            matches = current[column].isin([v for v in values if v is not None])
+            if any(v is None for v in values):
+                matches |= current[column].isna()
+            if style in ('negative all', 'negative any'):
+                matches = ~matches
+            current = current.loc[matches].copy()
+    # Derived plot/table frames are often ordinary pandas DataFrames (without
+    # Summary.dtfilter). Filter their actual datetime column without assuming
+    # that the source column is literally named "datetime".
+    time_col = settings.get('time_col')
+    if time_col not in current.columns or not pd.api.types.is_datetime64_any_dtype(current[time_col]):
+        time_col = next((col for col in current.columns
+                         if pd.api.types.is_datetime64_any_dtype(current[col])), None)
+    if time_col is not None:
+        timestamps = pd.to_datetime(current[time_col], errors='coerce')
+        mask = pd.Series(True, index=current.index)
+        for field, lower in (('datetime_start', True), ('datetime_end', False)):
+            kind, value = _parse_datetime_filter(settings.get(field))
+            if kind == 'date':
+                bound = datetime.combine(value, time.min)
+                if lower:
+                    mask &= timestamps.ge(bound)
+                else:
+                    mask &= timestamps.lt(bound + timedelta(days=1))
+            elif kind == 'datetime':
+                mask &= timestamps.ge(value) if lower else timestamps.lt(value)
+            elif kind == 'time':
+                times = timestamps.dt.time
+                mask &= times.ge(value) if lower else times.lt(value)
+        current = current.loc[mask.fillna(False)].copy()
+    for column in settings.get('numeric_subset_columns', []):
+        if column not in current.columns or not pd.api.types.is_numeric_dtype(current[column]):
+            continue
+        values = pd.to_numeric(current[column], errors='coerce')
+        for comparison in ('gt', 'lt'):
+            raw = settings.get('numeric_subset_bounds', {}).get(column, {}).get(comparison, '')
+            try:
+                bound = float(str(raw).strip())
+            except (ValueError, TypeError):
+                continue
+            if not np.isfinite(bound):
+                continue
+            mask = values.gt(bound) if comparison == 'gt' else values.lt(bound)
+            current = current.loc[mask.fillna(False) | values.isna()].copy()
+            values = values.loc[current.index]
+    return current

apmtools-0.2.60/src/apmtools/shiny/quality_source.py

@@ -0,0 +1,52 @@
+"""Construct quality sources from raw observations and inherited filters only.
+
+Unlike a derived table, a quality view must never inherit aggregation,
+column projection or plot-specific row selection: it needs the original
+identifier, timestamp and measurement columns to assess data coverage.
+"""
+from __future__ import annotations
+
+import copy
+
+from .inherited_source import source_frame
+
+
+_FILTER_FIELDS = ('subset_chain', 'datetime_start', 'datetime_end',
+                  'numeric_subset_columns', 'numeric_subset_bounds')
+
+
+def quality_filter_settings(settings, columns):
+    """Copy only filters valid against raw columns, excluding derived columns."""
+    settings = settings or {}
+    available = set(columns)
+    result = {key: copy.deepcopy(settings[key]) for key in _FILTER_FIELDS if key in settings}
+    result['subset_chain'] = [item for item in result.get('subset_chain', [])
+                              if item.get('column') in available]
+    result['numeric_subset_columns'] = [name for name in result.get('numeric_subset_columns', [])
+                                         if name in available]
+    result['numeric_subset_bounds'] = {
+        name: bounds for name, bounds in result.get('numeric_subset_bounds', {}).items()
+        if name in result['numeric_subset_columns']
+    }
+    return result
+
+
+def quality_filter_lineage(steps, columns):
+    """Convert saved plot/table lineage into filter-only steps on raw data."""
+    return [quality_filter_settings(step, columns) for step in (steps or [])]
+
+
+def prepare_quality_source(summary, *, parent_steps=None, restored_settings=None):
+    """Return raw-column dataframe with only inherited filters replayed.
+
+    Quality's own editable filters live in its tab settings, and are applied
+    separately. The source lineage contains only earlier table steps.
+    Legacy saved quality views are accepted; all aggregation/projection stages
+    are removed when loading them.
+    """
+    steps = quality_filter_lineage(
+        (restored_settings or {}).get('source_steps', []) if restored_settings is not None
+        else parent_steps, summary.columns)
+    frame = source_frame(summary, steps).reset_index(drop=True)
+    frame.columns = [str(column) for column in frame.columns]
+    return frame, steps