apmtools 0.2.17__tar.gz → 0.2.19__tar.gz

{apmtools-0.2.17 → apmtools-0.2.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: apmtools
-Version: 0.2.017
+Version: 0.2.019
 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.17 → apmtools-0.2.19}/pyproject.toml

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

{apmtools-0.2.17 → apmtools-0.2.19}/src/apmtools/shiny/summary.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import threading
 from collections.abc import Sequence
-
+import numpy as np
 import pandas as pd
 
 
@@ -16,7 +16,6 @@ PLOT_TYPES = {
     "scatter": "Scatter",
 }
 
-
 # ``None`` means row-level plotting.  The other values are passed directly to
 # Summary.group_stat(frequency=...).
 FREQUENCIES = {
@@ -100,7 +99,8 @@ def _timedelta_columns(data: pd.DataFrame) -> list[str]:
         key=str.casefold,
     )
 
-def _default_y(data: pd.DataFrame, x: str, y: str | Sequence[str] | None) -> list[str]:
+
+def _normalise_y(data: pd.DataFrame, x: str, y: str | Sequence[str] | None) -> list[str]:
     """Validate and normalise an initial Y selection."""
     numeric = _numeric_columns(data)
     if y is None:
@@ -179,15 +179,120 @@ def _aggregate(data, value_columns, frequency, grouping_by, aggregate):
     return result
 
 
-def _aggregated_value_columns(data, value_columns, aggregate):
-    """Return the columns produced by Summary.group_stat()."""
-    columns = []
-    for column in value_columns:
-        aggregated = f"{column}_{aggregate}"
-        if aggregated in data.columns:
-            columns.append(aggregated)
-    return columns
+def _histogram_figure(
+    data: pd.DataFrame,
+    x_column: str,
+    *,
+    group_column: str | None = None,
+    bins: int = 30,
+    density: bool = False,
+    stacked: bool = False,
+    histtype: str = "bar",
+    cumulative: int = 0,
+):
+    """Build a Matplotlib-compatible histogram using shared bin boundaries.
 
+    ``cumulative`` is 0 (off), 1 (forward), or -1 (reverse).
+    Density for stacked data is normalized across all groups; otherwise each
+    group's histogram is normalized independently.
+    """
+    import plotly.graph_objects as go
+
+    if histtype not in {"bar", "barstacked", "step", "stepfilled"}:
+        raise ValueError(f"Unknown histtype: {histtype}")
+    if cumulative not in {-1, 0, 1}:
+        raise ValueError("cumulative must be -1, 0 or 1")
+    if bins < 1:
+        raise ValueError("bins must be positive")
+
+    stacked = bool(stacked or histtype == "barstacked")
+    labels = (
+        list(pd.unique(data[group_column].dropna()))
+        if group_column is not None
+        else ["All observations"]
+    )
+    arrays = []
+    for label in labels:
+        rows = data.loc[data[group_column] == label] if group_column else data
+        values = pd.to_numeric(
+            rows[x_column], errors="coerce").to_numpy(dtype=float)
+        arrays.append(values[np.isfinite(values)])
+
+    all_values = np.concatenate(arrays) if arrays else np.array([])
+    fig = go.Figure()
+    if not len(all_values):
+        fig.update_layout(title="No numerical observations")
+        return fig
+
+    edges = np.histogram_bin_edges(all_values, bins=bins)
+    widths = np.diff(edges)
+    counts = np.array([np.histogram(v, bins=edges)[0]
+                      for v in arrays], dtype=float)
+    totals = counts.sum(axis=1)
+    grand_total = totals.sum()
+
+    if density:
+        if stacked:
+            heights = counts / (grand_total * widths)
+        else:
+            heights = np.divide(
+                counts, totals[:, None] * widths[None, :],
+                out=np.zeros_like(counts),
+                where=(totals[:, None] > 0),
+            )
+    else:
+        heights = counts.copy()
+
+    if cumulative:
+        # Cumulative density is a CDF/survival curve, not the sum of
+        # bin-wise probability densities. It must integrate bin mass.
+        mass = counts / grand_total if (density and stacked) else counts.copy()
+        if density and not stacked:
+            mass = np.divide(
+                counts, totals[:, None],
+                out=np.zeros_like(counts),
+                where=(totals[:, None] > 0),
+            )
+        heights = (
+            np.cumsum(mass, axis=1)
+            if cumulative == 1
+            else np.flip(np.cumsum(np.flip(mass, axis=1), axis=1), axis=1)
+        )
+
+    for index, label in enumerate(labels):
+        values = heights[index]
+        if histtype in ("bar", "barstacked"):
+            fig.add_trace(go.Bar(
+                name=str(label),
+                x=(edges[:-1] + edges[1:]) / 2,
+                y=values,
+                width=widths,
+                marker_line_width=0,
+            ))
+        else:
+            # Horizontal steps start/end at the shared bin boundaries.
+            xx = np.repeat(edges, 2)[1:-1]
+            yy = np.repeat(values, 2)
+            fig.add_trace(go.Scatter(
+                name=str(label),
+                x=xx,
+                y=yy,
+                mode="lines",
+                fill="tozeroy" if histtype == "stepfilled" else None,
+                stackgroup="histogram" if stacked and histtype == "stepfilled" else None,
+            ))
+
+    fig.update_layout(
+        barmode="stack" if stacked else "group",
+        xaxis_title=x_column,
+        yaxis_title=(
+            "Cumulative probability" if cumulative and density
+            else "Cumulative count" if cumulative
+            else "Probability density" if density
+            else "Count"
+        ),
+    )
+    return fig
 
 def _frequency_timedelta(frequency: str) -> pd.Timedelta | None:
     """Convert a timestamp aggregation frequency to its expected spacing."""
@@ -300,16 +405,17 @@ def create_summary_app(
     columns = _alphabetical(summary.columns)
     column_map = {str(c): c for c in summary.columns}
     numeric_columns = _alphabetical(_numeric_columns(summary))
-    categorical_columns = _alphabetical(_categorical_columns(summary))
-    datetime_columns = _alphabetical(_datetime_columns(summary))
-    timedelta_columns = _alphabetical(_timedelta_columns(summary))
-
+    categorical_columns = _categorical_columns(summary)
+    datetime_columns = _datetime_columns(summary)
+    group_columns = _alphabetical(
+        c for c in columns if not pd.api.types.is_numeric_dtype(summary[column_map[c]])
+    )
 
     x = _default_x(summary) if x is None else str(x)
     if x not in column_map:
         raise ValueError(f"Unknown x column: {x!r}")
 
-    initial_y = _default_y(summary, x, y)
+    initial_y = _normalise_y(summary, x, y)
     if group_by is None:
         initial_groups = [_default_group(summary)] if _default_group(
             summary) is not None else []
@@ -320,6 +426,8 @@ def create_summary_app(
     unknown_groups = [c for c in initial_groups if c not in column_map]
     if unknown_groups:
         raise ValueError(f"Unknown group_by column(s): {unknown_groups!r}")
+    # Numeric columns are not offered by the Group by selector.
+    initial_groups = [c for c in initial_groups if c in group_columns]
 
     if plot_type not in PLOT_TYPES:
         raise ValueError(
@@ -336,7 +444,7 @@ def create_summary_app(
             ui.output_ui("y_control"),
             ui.input_selectize(
                 "group_by", "Group by",
-                choices={c: c for c in columns},
+                choices={c: c for c in group_columns},
                 selected=initial_groups,
                 multiple=True,
                 options={"placeholder": "Select one or more grouping columns"},
@@ -373,6 +481,17 @@ def create_summary_app(
                 "input.plot_type === 'histogram'",
                 ui.input_numeric("bins", "Histogram bins",
                                  value=30, min=1, max=200, step=1),
+                ui.input_select("hist_density", "Density", choices={
+                                "False": "False", "True": "True"}, selected="False"),
+                ui.input_select("hist_stacked", "Stacked", choices={
+                                "False": "False", "True": "True"}, selected="False"),
+                ui.input_select("hist_type", "Histogram type", choices={
+                    "bar": "bar", "barstacked": "barstacked",
+                    "step": "step", "stepfilled": "stepfilled",
+                }, selected="bar"),
+                ui.input_select("hist_cumulative", "Cumulative", choices={
+                    "0": "False", "1": "True (ascending)", "-1": "-1 (descending)",
+                }, selected="0"),
             ),
             ui.input_text("title", "Plot title", value=title),
             ui.help_text(
@@ -595,13 +714,15 @@ def create_summary_app(
                 )
 
             if selected_plot == "histogram":
-                fig = px.histogram(
+                fig = _histogram_figure(
                     plot_df,
-                    x=x_column,
-                    color="__plot_group" if group_columns else None,
-                    nbins=int(input.bins()),
-                    barmode="overlay",
-                    opacity=0.45 if group_columns else 1.0,
+                    x_column,
+                    group_column="__plot_group" if group_columns else None,
+                    bins=int(input.bins()),
+                    density=input.hist_density() == "True",
+                    stacked=input.hist_stacked() == "True",
+                    histtype=input.hist_type(),
+                    cumulative=int(input.hist_cumulative()),
                 )
             elif selected_plot == "box":
                 fig = px.box(