apmtools 0.2.44__tar.gz → 0.2.46__tar.gz

{apmtools-0.2.44 → apmtools-0.2.46}/PKG-INFO

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

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

{apmtools-0.2.44 → apmtools-0.2.46}/src/apmtools/classes.py

@@ -861,7 +861,9 @@ class Dataset(DictionaryPlus):
                     z[1].to_csv(output, index=False)
             out[z[0]] = z[1]
         if merged:
-            return pd.concat([out[k] for k in out.keys()]).reset_index()
+            out_merged = pd.concat([out[k] for k in out.keys()]).reset_index()
+            out_merged.description = self.description
+            return out_merged
         return out
 
     def save_data(self, directory="./saved/", levels=[]):

{apmtools-0.2.44 → apmtools-0.2.46}/src/apmtools/shiny/appearance.py

@@ -41,9 +41,7 @@ def _label_plot_axes(fig, plot_type, x_column, y_columns, *,
         fig.update_yaxes(title_text=_axis_label(y_columns[0]))
     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="):
@@ -125,7 +123,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.44 → apmtools-0.2.46}/src/apmtools/shiny/data.py

@@ -131,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,
@@ -143,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.44 → apmtools-0.2.46}/src/apmtools/shiny/matplotlib_renderer.py

@@ -27,7 +27,7 @@ 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 kind == "line" and len(ys) > 1 else
                _axis_label(ys[0]) if ys else "Count")
     x_label = spec.get("x_label_override") or x_label
     return dict(x_label=x_label, y_label=y_label, names=names, colors=colors)
@@ -322,12 +322,12 @@ 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",
                               title_font_size=14, axis_font_size=12, tick_font_size=10,
-                              legend_font_size=12, panel_font_size=14, bins=30, density=False,
+                              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,
                               x_major_ticks=6, y_major_ticks=6, x_minor_ticks=False, y_minor_ticks=False):
@@ -339,7 +339,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=100)
+        fig, ax = plt.subplots(figsize=(10, 5), dpi=plot_dpi)
     else:
         ax = _axes
         fig = ax.figure
@@ -364,7 +364,7 @@ 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=100,
+            fig, axes = plt.subplots(nrows, ncols, figsize=(5*ncols, 3.8*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,
@@ -376,13 +376,13 @@ 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,
                     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,
+                    panel_font_size=panel_font_size, plot_dpi=plot_dpi,
                     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,
@@ -413,6 +413,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])
@@ -480,11 +485,12 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
                 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,
@@ -593,6 +599,39 @@ def _matplotlib_direct_figure(spec, *, title="", x_label="", y_label="",
         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 = []
+        if multi_y_color_by == "none":
+            for group in group_names if group_col else []:
+                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:
+                key = (value, group_names[0] if group_col else None) if by_var else (variable_names[0], value)
+                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"}
@@ -671,7 +710,7 @@ def _matplotlib_figure(plotly_figure):
     import matplotlib.colors as mcolors
     from matplotlib.patches import Patch
 
-    fig, ax = plt.subplots(figsize=(10, 5), dpi=100)
+    fig, ax = plt.subplots(figsize=(10, 5), dpi=plot_dpi)
     source = plotly_figure
     category_labels = list(getattr(source.layout.xaxis, "categoryarray", None) or [])
     categorical = (getattr(source.layout.xaxis, "type", None) == "category")

apmtools-0.2.46/src/apmtools/shiny/multi_y.py

@@ -0,0 +1,56 @@
+"""Independent categorical colour and line-style encodings for multi-Y lines."""
+
+
+def multi_y_styles(variables, groups, palette, mode="group", colors=None, styles=None):
+    variables = [str(v) for v in variables]
+    groups = [str(g) for g in groups] if groups else []
+    colors = colors or {}
+    styles = styles or {}
+    palette = list(palette) or ["#636EFA", "#EF553B", "#00CC96"]
+    combinations = [(var, group) for group in (groups or [None]) for var in variables]
+    if mode == "none":
+        # Restore original single-Y group encoding across all Y variables.
+        color_map = {}
+        dash_map = {}
+        for var in variables:
+            for group in (groups or [None]):
+                idx = groups.index(group) if group is not None else 0
+                color_map[(var, group)] = colors.get(group, palette[idx % len(palette)]) if group is not None else palette[0]
+                style = styles.get(group, "-") if group is not None else "-"
+                dash_map[(var, group)] = {"solid":"-", "dashed":"--", "dotted":":", "dashdot":"-."}.get(style, style)
+        return color_map, dash_map, variables, groups
+    primary = groups if mode == "group" and groups else variables
+    secondary = variables if mode == "group" and groups else groups
+    dash_values = ["-", "--", ":", "-."]
+    color_map, dash_map = {}, {}
+    for var in variables:
+        for group in (groups or [None]):
+            p = group if mode == "group" and groups else var
+            q = var if mode == "group" and groups else group
+            if mode == "both":
+                index = combinations.index((var, group))
+                if index < len(palette):
+                    default_color = palette[index]
+                else:
+                    import colorsys
+                    hue = (index * 0.618033988749895) % 1.0
+                    rgb = colorsys.hsv_to_rgb(hue, 0.72, 0.88)
+                    default_color = "#{:02x}{:02x}{:02x}".format(*(round(255 * c) for c in rgb))
+                combined = f"{group}, {var}" if group is not None else var
+                color_map[(var, group)] = colors.get(combined, default_color)
+                dash_map[(var, group)] = styles.get(combined, "-")
+                continue
+            color_map[(var, group)] = colors.get(p, colors.get(f"{group}, {var}", palette[primary.index(p) % len(palette)]))
+            # For colour-by-variable, the grouping dimension must control dashes.
+            # Do not let a variable-level style override erase that distinction.
+            default_dash = dash_values[secondary.index(q) % len(dash_values)] if q in secondary else "-"
+            # The Shiny appearance panel automatically populates each group with
+            # "solid".  Those generated defaults must not collapse the
+            # group-specific dash cycle in colour-by-variable mode.
+            override = styles.get(q)
+            if mode == "variable" and groups and override in ("solid", "-"):
+                override = None
+            dash_map[(var, group)] = override if override is not None else default_dash
+            if dash_map[(var, group)] in ("solid", "dashed", "dotted", "dashdot"):
+                dash_map[(var, group)] = {"solid":"-", "dashed":"--", "dotted":":", "dashdot":"-."}[dash_map[(var, group)]]
+    return color_map, dash_map, variables, groups

{apmtools-0.2.44 → apmtools-0.2.46}/src/apmtools/shiny/plotly_renderer.py

@@ -228,7 +228,7 @@ def _lineplot_figure(plot_df, x_column, y_columns, *, group_columns, frequency,
             y="value",
             color=group_column,
             line_group=line_group_column,
-            facet_row="variable" if len(y_columns) > 1 else None,
+            line_dash="variable" if len(y_columns) > 1 else None,
         )
     elif section_column is not None:
         # Preserve filtered-out gaps even when no colour grouping is selected.
@@ -238,7 +238,7 @@ def _lineplot_figure(plot_df, x_column, y_columns, *, group_columns, frequency,
             long_df = plot_df[[x_column, section_column, *y_columns]].melt(
                 id_vars=[x_column, section_column], var_name="variable", value_name="value")
             fig = px.line(long_df, x=x_column, y="value", color="variable",
-                          line_group=section_column, facet_row="variable")
+                          line_group=section_column)
     elif identifier_column is not None:
         # With no explicit grouping, retain the normal Y-variable
         # colouring while using identifier to keep each monitor's
@@ -263,7 +263,7 @@ def _lineplot_figure(plot_df, x_column, y_columns, *, group_columns, frequency,
                 y="value",
                 color="variable",
                 line_group=identifier_column,
-                facet_row="variable",
+                line_dash="variable",
             )
     elif section_column is not None:
         if len(y_columns) == 1:
@@ -286,9 +286,88 @@ def _lineplot_figure(plot_df, x_column, y_columns, *, group_columns, frequency,
                 y="value",
                 color="variable",
                 line_group=section_column,
-                facet_row="variable",
+                line_dash="variable",
             )
     else:
         fig = px.line(plot_df, x=x_column, y=y_columns)
     return fig
 
+
+
+def _style_multi_y_legend(fig, spec, mode, palette, trace_colors, line_style, legend_labels):
+    """Give multi-Y line plots separate variable/group legend keys."""
+    from .appearance import _parse_label_map
+    from .multi_y import multi_y_styles
+    from plotly.colors import qualitative
+    import plotly.graph_objects as go
+
+    variables = [str(v) for v in spec["ys"]]
+    groups = [str(v) for v in spec["data"]["__plot_group"].dropna().unique()] if spec["groups"] else []
+    palettes = getattr(qualitative, palette, None) if palette != "Default" else None
+    colors, dashes, variables, groups = multi_y_styles(variables, groups, palettes or qualitative.Plotly,
+                                                        mode, _parse_label_map(trace_colors), _parse_label_map(line_style))
+    rename = _parse_label_map(legend_labels)
+    for trace in fig.data:
+        if trace.type not in ("scatter", "scattergl"):
+            continue
+        name = str(trace.name or "")
+        # Plotly Express names traces "group, variable" when both encodings are present.
+        group = None
+        variable = None
+        if groups:
+            for g in groups:
+                for v in variables:
+                    if name == f"{g}, {v}" or name == f"{v}, {g}":
+                        group, variable = g, v
+                        break
+                if variable is not None:
+                    break
+        else:
+            variable = name if name in variables else next((v for v in variables if name.endswith(v)), None)
+        if variable is None:
+            continue
+        key = (variable, group)
+        trace.line.color = colors[key]
+        trace.line.dash = {"-":"solid", "--":"dash", ":":"dot", "-.":"dashdot"}.get(dashes[key], dashes[key])
+        trace.showlegend = False
+        trace.legendgroup = f"series:{group}:{variable}"
+    if mode == "none":
+        for group in groups:
+            key = (variables[0], group)
+            fig.add_trace(go.Scatter(
+                x=[None], y=[None], mode="lines", name=rename.get(group, group),
+                line=dict(color=colors[key], dash={"-":"solid", "--":"dash", ":":"dot", "-.":"dashdot"}.get(dashes[key], "solid")),
+                legendgroup=f"group:{group}", showlegend=True, hoverinfo="skip",
+            ))
+        fig.update_layout(showlegend=bool(groups))
+        return
+    if mode == "both":
+        for group in (groups or [None]):
+            for variable in variables:
+                key = (variable, group)
+                label = f"{group}, {variable}" if group is not None else variable
+                fig.add_trace(go.Scatter(
+                    x=[None], y=[None], mode="lines", name=rename.get(label, label),
+                    line=dict(color=colors[key], dash="solid"),
+                    legendgroup=f"series:{group}:{variable}", showlegend=True, hoverinfo="skip",
+                ))
+        fig.update_layout(showlegend=True)
+        return
+    # Legend-only proxy traces avoid duplicating real observations and preserve hover data.
+    added_section = False
+    for heading, items, by_variable in (("Y variable", variables, True), ("Grouping", groups, False)):
+        if not items:
+            continue
+        if added_section:
+            # A blank legend row separating the variable and grouping keys.
+            fig.add_trace(go.Scatter(x=[None], y=[None], mode="lines", name=" ",
+                                     line=dict(color="rgba(0,0,0,0)", width=0),
+                                     showlegend=True, hoverinfo="skip", legendgroup="separator"))
+        added_section = True
+        for index, item in enumerate(items):
+            key = (item, groups[0] if groups else None) if by_variable else (variables[0], item)
+            fig.add_trace(go.Scatter(x=[None], y=[None], mode="lines", name=rename.get(item, item),
+                                     line=dict(color=colors[key], dash={"-":"solid", "--":"dash", ":":"dot", "-.":"dashdot"}.get(dashes[key], "solid")),
+                                     legendgroup=heading, legendgrouptitle_text=heading if index == 0 else None,
+                                     showlegend=True, hoverinfo="skip"))
+    fig.update_layout(showlegend=True)