goad-toolkit 0.2.13__tar.gz → 0.2.15__tar.gz

{goad_toolkit-0.2.13 → goad_toolkit-0.2.15}/.remember/logs/memory-2026-08-31.log

@@ -342,3 +342,36 @@ RuntimeError: claude exited 1: Failed to authenticate: OAuth session expired and
 18:49:15 [haiku] call exited 1; tokens already spent are unknown — the failure carried no usage block, so this run's reported cost is lower than what it actually cost
 18:49:15 [haiku] ERROR: call-haiku error: claude exited 1: Failed to authenticate: OAuth session expired and could not be refreshed
 18:49:15 [haiku] failure 1/3 on this span — will retry next run
+21:09:54 [hook] session-start: PROJECT_DIR=/Users/rgrouls/code/courses/goad_toolkit PIPELINE_DIR=/Users/rgrouls/.claude/plugins/cache/claude-plugins-official/remember/0.20.0 REMEMBER_DIR=/Users/rgrouls/code/courses/goad_toolkit/.remember
+21:09:54 [hook] save-session: PROJECT_DIR=/Users/rgrouls/code/courses/goad_toolkit PIPELINE_DIR=/Users/rgrouls/.claude/plugins/cache/claude-plugins-official/remember/0.20.0 PYTHON=python3 REMEMBER_DIR=/Users/rgrouls/code/courses/goad_toolkit/.remember
+21:09:54 [force] bypassing cooldown + min msgs
+21:09:54 [hook] run-consolidation: PROJECT_DIR=/Users/rgrouls/code/courses/goad_toolkit PIPELINE_DIR=/Users/rgrouls/.claude/plugins/cache/claude-plugins-official/remember/0.20.0 PYTHON=python3 REMEMBER_DIR=/Users/rgrouls/code/courses/goad_toolkit/.remember
+21:09:54 [extract] session 309ee39a-6171-47ea-88cf-ee1ad9433f68
+21:09:54 [extract] 204 exchanges (10 human)
+21:09:54 [consolidation] start
+21:09:54 [haiku] calling (branch: main)
+21:09:54 [hook] session-start: PROJECT_DIR=/Users/rgrouls/code/courses/goad_toolkit PIPELINE_DIR=/Users/rgrouls/.claude/plugins/cache/claude-plugins-official/remember/0.20.0 REMEMBER_DIR=/Users/rgrouls/code/courses/goad_toolkit/.remember
+21:09:54 [hook] run-consolidation: PROJECT_DIR=/Users/rgrouls/code/courses/goad_toolkit PIPELINE_DIR=/Users/rgrouls/.claude/plugins/cache/claude-plugins-official/remember/0.20.0 PYTHON=python3 REMEMBER_DIR=/Users/rgrouls/code/courses/goad_toolkit/.remember
+21:09:54 [consolidation] another consolidation holds the lock, skip
+21:09:56 [haiku] WARNING: this CLI rejected --setting-sources (Failed to authenticate: OAuth session expired and could not be refreshed); retrying WITHOUT hook isolation so saves keep working. The nested call will run with your hooks registered — a hook that blocks it returns its block message as if it were the model's reply (#202).
+21:09:56 [haiku] WARNING: this CLI rejected --setting-sources (Failed to authenticate: OAuth session expired and could not be refreshed); retrying WITHOUT hook isolation so saves keep working. The nested call will run with your hooks registered — a hook that blocks it returns its block message as if it were the model's reply (#202).
+21:09:57 [haiku] call exited 1; tokens already spent are unknown — the failure carried no usage block, so this run's reported cost is lower than what it actually cost
+21:09:57 [haiku] call exited 1; tokens already spent are unknown — the failure carried no usage block, so this run's reported cost is lower than what it actually cost
+21:09:57 [haiku] ERROR: call-haiku error: claude exited 1: Failed to authenticate: OAuth session expired and could not be refreshed
+21:09:57 [haiku] failure 1/3 on this span — will retry next run
+21:09:57 [consolidation] ERROR: pipeline failed — Traceback (most recent call last):
+  File "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/lib/python3.9/runpy.py", line 197, in _run_module_as_main
+    return _run_code(code, main_globals, None,
+  File "/Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.9/lib/python3.9/runpy.py", line 87, in _run_code
+    exec(code, run_globals)
+  File "/Users/rgrouls/.claude/plugins/cache/claude-plugins-official/remember/0.20.0/pipeline/shell.py", line 683, in <module>
+    main()
+  File "/Users/rgrouls/.claude/plugins/cache/claude-plugins-official/remember/0.20.0/pipeline/shell.py", line 670, in main
+    cmd_consolidate(
+  File "/Users/rgrouls/.claude/plugins/cache/claude-plugins-official/remember/0.20.0/pipeline/shell.py", line 525, in cmd_consolidate
+    result = consolidate(staging_contents, recent, archive,
+  File "/Users/rgrouls/.claude/plugins/cache/claude-plugins-official/remember/0.20.0/pipeline/consolidate.py", line 324, in consolidate
+    result = call_haiku(prompt, timeout=180)
+  File "/Users/rgrouls/.claude/plugins/cache/claude-plugins-official/remember/0.20.0/pipeline/haiku.py", line 735, in call_haiku
+    raise RuntimeError(
+RuntimeError: claude exited 1: Failed to authenticate: OAuth session expired and could not be refreshed

goad_toolkit-0.2.15/.remember/tmp/last-save-ts

@@ -0,0 +1 @@
+1788203394

goad_toolkit-0.2.15/.remember/tmp/last-summary-failure

@@ -0,0 +1 @@
+309ee39a-6171-47ea-88cf-ee1ad9433f68:747 1

goad_toolkit-0.2.15/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+## 0.2.15
+
+### Added
+
+- **Per-call settings overrides.** Any keyword passed to `plot()` that names a
+  `PlotSettings` field (`title`, `xlabel`, `ylabel`, ...) overrides that field for that
+  call only, leaving the shared settings object untouched — the claim lives in the call,
+  the styling stays in the settings. On a layer whose figure already exists, the
+  axis-level fields (`title`, `xlabel`, `ylabel`, `xtick_rotation`) still apply.
+- `FacetPlot`: the same plot once per level of a column — small multiples in one call,
+  with panel titles defaulting to the level names.
+- `PlotSettings.sharex` / `sharey`: subplot grids share one scale, so panel shapes
+  compare honestly. `FacetPlot` is the main customer.
+- A pipeline vocabulary for the counting-and-shares work notebooks kept doing in loose
+  cells: `Filter`, `SortValues`, `Head`, `CountValues`, `GroupAgg`, `Share`, `FlagDates`,
+  `MapValues`, `SubtractBaseline`. Output-column parameters are spelled `feature`, the
+  `RegexFeature` convention, since `name` names the pipeline step.
+- `HistogramPlot.build` takes `stat` (default `"density"`), so count histograms no longer
+  need a raw seaborn call.
+
+### Fixed
+
+- `ACFPlot` draws each lag as a vertical line (`ax.vlines`) instead of a 0.3-wide bar.
+  With hundreds of lags the bars were narrower than a pixel and aliased against the
+  pixel grid — lags vanished into phantom gaps or doubled up into dark stripes. Line
+  width is in points, so every lag now stays visible at any `nlags`.
+
+### Changed
+
+- `BarPlot.build` no longer takes `xtick_rotation`; the per-call override
+  (`plot(..., xtick_rotation=45)`) and the `PlotSettings` field cover both paths.
+
+## 0.2.14
+
+### Added
+
+- `PlotSettings.subplot_xlabels` / `subplot_ylabels`: per-panel axis labels, the
+  `subplot_titles` idea extended to labels. On the panels they cover they win over the
+  figure-wide `xlabel`/`ylabel`, so a multi-panel figure with panels showing different
+  quantities needs no `ax.set_ylabel` calls.
+- `HorizontalLine`: a layer marking one value on the y-axis — the reference line a residual
+  plot is read against. Defaults to a quiet grey line rather than `VerticalLine`'s crimson
+  marker, because a baseline is context, not a finding.
+- `BarPlot.build` takes `xtick_rotation` for category labels too long to sit flat.
+- `PlotSettings.xtick_rotation`: the same rotation as a figure-wide setting, applied to
+  every axis — for date axes whose labels overlap when flat.
+
+### Changed
+
+- Multi-panel grids from `create_figure` use constrained layout, which spaces panels,
+  labels and the suptitle at draw time — after every layer has landed — so figures no
+  longer need a trailing `fig.tight_layout()`.
+
+## 0.2.1
+
+### Breaking
+
+- **`FileConfig` gained `date_column` and `date_index`.** `FileHandler.load` reads csv and
+  parquet (reader picked from the suffix), parses `date_column` as dates and, when
+  `date_index` is true, moves it into the index. The defaults (`"date"`, `True`) keep the
+  covid pipeline working unchanged, but a `FileConfig` subclass that overrode `load` to
+  support another shape can now express it as configuration instead. A file whose suffix has
+  no reader, or a `date_column` that is not in the frame, raises `ValueError`. Parquet needs
+  `pyarrow`, available as the `parquet` extra.
+- **`DistributionRegistry` is a normal class.** Constructing one no longer returns a shared
+  process-wide instance, so a registration affects only the registry it was made on. Code
+  that registered a family on one registry and relied on a separately constructed
+  `DistributionFitter()` picking it up must now pass it: `DistributionFitter(registry)`.
+
+### Added
+
+- `goad` console script: fits every family in the registry to one column of a csv or parquet
+  file and prints the fits ranked by log-likelihood (`goad data/residuals.csv residual`).
+- `DistributionFitter` accepts an optional `DistributionRegistry`.
+- `filehandler.reader_for`, `filehandler.write_frame` and `filehandler.parse_dates` as
+  reusable pieces; `FileHandler.save` writes parquet as well as csv.
+- A pytest suite under `tests/`.
+
+### Fixed
+
+- `BarWithDates.build` and `VerticalDate.build` return `(fig, ax)` like every other `build`.
+- Plots draw on `self.ax` / `self.fig` instead of module-level `plt` calls, so a layer placed
+  with `plot_on_axes` lands on the axis it was handed rather than on matplotlib's current one.
+- The `goad` console script points at a module that exists.
+
+### Changed
+
+- `__version__` is read from the installed package metadata.

{goad_toolkit-0.2.13 → goad_toolkit-0.2.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: goad-toolkit
-Version: 0.2.13
+Version: 0.2.15
 Summary: An extensible toolkit for Goal Oriented Analysis of Data
 Project-URL: Github, https://github.com/raoulg/goad_toolkit
 Author-email: raoul grouls <Raoul.Grouls@han.nl>

{goad_toolkit-0.2.13 → goad_toolkit-0.2.15}/docs/02-pipelines.md

@@ -60,6 +60,15 @@ input frame is safe, and the steps stay cheap.
 | `ZScaler` | standardise to mean 0, std 1 | `column`, `rename` |
 | `TimeFeatures` | derive calendar columns from a timestamp | `column`, `features` |
 | `RegexFeature` | count / flag / extract a pattern in a text column | `column`, `pattern`, `feature`, `mode` |
+| `Filter` | keep the rows a `query` expression selects | `expr` |
+| `SortValues` | sort rows by a column | `column`, `ascending` |
+| `Head` | keep the first n rows — after a sort, a top-n | `n` |
+| `CountValues` | one row per distinct value, with its count or share | `column`, `feature`, `normalize` |
+| `GroupAgg` | one row per group, one aggregated value | `by`, `column`, `agg`, `feature` |
+| `Share` | divide a column by its (per-group) total | `column`, `feature`, `by` |
+| `FlagDates` | boolean column marking the listed dates | `column`, `dates`, `feature` |
+| `MapValues` | map a column through a dict, with a default | `column`, `mapping`, `feature`, `default` |
+| `SubtractBaseline` | subtract a baseline frame's column, keyed on a column | `column`, `baseline`, `on`, `feature` |
 
 `rename=True` writes to a new column (`deaths_shifted`, `deaths_zscore`, …) instead of
 overwriting. Prefer it. An overwritten column is a step you cannot debug, and the whole

{goad_toolkit-0.2.13 → goad_toolkit-0.2.15}/docs/03-plot-composition.md

@@ -51,6 +51,11 @@ class PlotSettings:
     grid: bool = False
     grid_alpha: Optional[float] = None
     subplot_titles: List[str] = field(default_factory=list)
+    subplot_xlabels: List[str] = field(default_factory=list)
+    subplot_ylabels: List[str] = field(default_factory=list)
+    xtick_rotation: Optional[float] = None
+    sharex: bool = False
+    sharey: bool = False
 ```
 
 `xlabel`/`ylabel` left as `None` are not blank — `create_figure` skips setting them at all,
@@ -60,13 +65,30 @@ column name whenever the label is still empty). Only an explicit `xlabel=`/`ylab
 correct axis labels for free from the column names you passed to `x=`/`y=`; reach for
 `xlabel=`/`ylabel=` only when the column name is not what you want a reader to see.
 
-It is a dataclass, so `dataclasses.replace(settings, title="Something else")` gives you a
-variant without mutating the original. Useful when a figure set shares everything but the
-title.
+For a one-off change, override in the `plot` call itself: any keyword that names a
+`PlotSettings` field is applied to that call and that call only, leaving the shared
+settings object untouched.
+
+```python
+BarPlot(settings).plot(data=west, x="quarter", y="revenue",
+                       title="West region, on its own")
+```
+
+That division of labour is deliberate: styling lives in settings, and the claim — the
+title, the odd label — lives at the point of use. For a *lasting* variant, the dataclass
+answer still applies: `dataclasses.replace(settings, figsize=(12, 4))` returns a new
+settings object to keep and reuse.
 
 `subplot_titles` is what makes multi-panel figures work: when a plot creates more than one
 axis, each gets the corresponding entry. `PlotFits` uses this to label each fitted
-distribution with its own test statistics.
+distribution with its own test statistics. `subplot_xlabels` and `subplot_ylabels` are the
+same idea for axis labels — panels showing different quantities get their own labels from
+the settings, not from `ax.set_ylabel` calls after the fact. On the panels they cover, the
+lists win over the figure-wide `xlabel`/`ylabel`. `xtick_rotation` rotates the x tick
+labels on every axis, for the date axes and long category names that overlap when flat.
+`sharex`/`sharey` make a multi-panel grid share one scale — without them each panel
+autoscales to its own data, and two shapes that look alike may sit on very different
+axes.
 
 ## 3.3 `BasePlot`
 
@@ -89,6 +111,8 @@ The contract:
 
 `create_figure(n_plots=...)` handles the layout: one axis for a single plot, otherwise a grid
 wrapping at `settings.max_cols` columns — three by default — with the unused axes hidden.
+The grid uses constrained layout, which spaces panels, labels and the suptitle at draw
+time — after every layer has landed — so a figure never needs a `tight_layout()` call.
 Labels, grid and titles are applied to every visible axis. Set `max_cols=4` for a quartet or
 `max_cols=2` for a square grid; four panels at the default wrap to 3 + 1, which is rarely
 what a set of four wants.
@@ -132,7 +156,17 @@ changed is the difference between a chart and an argument. See
 [Visual critique](07-visual-critique.md) §"integrate text".
 
 `plot_on_axes(other_plot, ax, ...)` is the same thing targeting a specific axis, which is how
-multi-panel figures get built.
+multi-panel figures get built. `FacetPlot` packages the most common multi-panel figure —
+the same plot repeated once per level of a column — into a single call:
+
+```python
+FacetPlot(settings).plot(inner=HistogramPlot(settings), data=msgs,
+                         by="day_name", order=days, x="hour", bins=range(25))
+```
+
+One panel per level of `by`, every panel drawn by `inner` with the same kwargs, panel
+titles defaulting to the level names. Set `sharey=True` in the settings so the panels
+share a scale and the shapes compare honestly.
 
 ## 3.5 Building up a plot, one layer at a time
 
@@ -158,6 +192,7 @@ step 3.
 | `ComparePlot` | two lines with labels | `LinePlot` twice via `plot_on` |
 | `VerticalDate` | a labelled vertical line at a date | a layer, not a plot |
 | `VerticalLine` | the same at a number | a layer, not a plot |
+| `HorizontalLine` | a reference level on the y-axis, usually zero | a layer; the line a residual is read against |
 | `ComparePlotDate` | `ComparePlot` + `VerticalDate` | |
 | `BarPlot` | `sns.barplot`, one bar per category | see [Five families §4.1](04-five-families.md) |
 | `GroupedBarPlot` | bars split by `hue` | two categorical variables at once |
@@ -171,7 +206,8 @@ step 3.
 | `BarWithDates` | bars with a month locator on the x axis | |
 | `ResidualPlot` | `BarWithDates` + `VerticalDate` | the residual-over-time view |
 | `DecomposePlot` | `seasonal_decompose`, one panel each | observed/trend/seasonal/residual, overrides `plot` |
-| `ACFPlot` | `acf` as bars with a confidence band | see [Five families §4.2](04-five-families.md) |
+| `FacetPlot` | any plot, once per level of a column | small multiples in one call; overrides `plot` |
+| `ACFPlot` | `acf` as vertical lines with a confidence band | see [Five families §4.2](04-five-families.md) |
 | `HistogramPlot` | `sns.histplot`, `stat="density"` | density so a pdf can be overlaid |
 | `DistPlot` | a scipy distribution's pdf or pmf | estimates its own x-range from `ppf` |
 | `PlotFits` | histogram + fitted pdf, one panel per fit | see [Distributions](05-distributions.md) |

{goad_toolkit-0.2.13 → goad_toolkit-0.2.15}/docs/08-api-reference.md

@@ -85,6 +85,15 @@ class TransformBase(ABC):
 | `ZScaler` | `column: str, rename: bool = False` |
 | `TimeFeatures` | `column: str, features: Optional[List[str]] = None` |
 | `RegexFeature` | `column: str, pattern: str, feature: str, mode: str = "count"` |
+| `Filter` | `expr: str` — pandas `query` syntax |
+| `SortValues` | `column: str, ascending: bool = True` |
+| `Head` | `n: int` |
+| `CountValues` | `column: str, feature: str = "n", normalize: bool = False` |
+| `GroupAgg` | `by, column: Optional[str] = None, agg: str = "size", feature: Optional[str] = None` |
+| `Share` | `column: str, feature: Optional[str] = None, by=None` |
+| `FlagDates` | `column: str, dates, feature: str` |
+| `MapValues` | `column: str, mapping: Dict, feature: str, default=None` |
+| `SubtractBaseline` | `column: str, baseline: pd.DataFrame, on: str, feature: Optional[str] = None` |
 
 `rename=True` writes to `{column}_shifted` / `_diff` / `_rolling_avg` / `_zscore` instead of
 overwriting.
@@ -97,7 +106,14 @@ overwriting.
 capture group, NaN where nothing matched); anything else raises `ValueError`. `extract`
 requires exactly one capture group in `pattern` and logs its match rate through `loguru`.
 The output column is `feature`, not `name` — `Pipeline.add(name=...)` already claims `name`
-for the step.
+for the step. The same spelling holds for every transform that names an output column
+(`CountValues`, `GroupAgg`, `Share`, `FlagDates`, `MapValues`, `SubtractBaseline`).
+
+`Filter`, `SortValues`, `Head`, `CountValues` and `GroupAgg` reshape the frame rather than
+adding columns to it — like a bespoke parse step, they return a different frame, and the
+steps after them see the new shape. `Share(by=...)` normalises within groups, so every
+group sums to one separately. `SubtractBaseline` merges `baseline` on `on` and leaves the
+difference — the residual of a model-and-residual move — flowing down the pipeline.
 
 ```python
 class Pipeline:
@@ -300,7 +316,12 @@ class PlotSettings:
     grid: bool = False
     grid_alpha: Optional[float] = None
     subplot_titles: List[str] = field(default_factory=list)
+    subplot_xlabels: List[str] = field(default_factory=list)  # per-panel, wins over xlabel
+    subplot_ylabels: List[str] = field(default_factory=list)  # per-panel, wins over ylabel
+    xtick_rotation: Optional[float] = None               # rotate x tick labels, every axis
     max_cols: int = 3                                    # columns before wrapping
+    sharex: bool = False                                 # subplot grids share one x-scale
+    sharey: bool = False                                 # subplot grids share one y-scale
     highlight: List[str] = field(default_factory=list)   # defaults for HighlightCategory
     base_color: str = "lightgrey"
     highlight_color: str = "crimson"
@@ -321,6 +342,10 @@ class BasePlot(ABC):
     def __init__(self, settings: PlotSettings, n_plots: Optional[int] = None)
     def plot(self, n_plots: Optional[int] = None, *args, **kwargs)
     def create_figure(self, n_plots: Optional[int] = None)      # -> (fig, axes)
+    # plot() treats any kwarg naming a PlotSettings field (title, xlabel, ...) as a
+    # per-call override: applied to this instance before the figure is configured,
+    # the shared settings object untouched. On an existing figure (a layer), only
+    # the axis-level fields — title, xlabel, ylabel, xtick_rotation — still apply.
     def plot_on(self, other_plot: "BasePlot", *args, **kwargs)
     def plot_on_axes(self, other_plot: "BasePlot", ax: Axes, *args, **kwargs)
     def build(self, *args, **kwargs)                            # you implement
@@ -332,6 +357,7 @@ class BasePlot(ABC):
 | `ComparePlot` | `data, x, y1, y2, **kwargs` |
 | `VerticalDate` | `date: str, label: str` |
 | `VerticalLine` | `x: float, label=None, color="crimson", linestyle="--", linewidth=2, **kwargs` |
+| `HorizontalLine` | `y: float, label=None, color="grey", linestyle="-", linewidth=1, **kwargs` |
 | `ComparePlotDate` | `data, x, y1, y2, date, datelabel, **kwargs` |
 | `BarPlot` | `data, x, y, order=None, **kwargs` → `sns.barplot` |
 | `GroupedBarPlot` | `data, x, y, hue, order=None, hue_order=None, **kwargs` |
@@ -346,9 +372,9 @@ class BasePlot(ABC):
 | `ScatterPlot` | `data, x, y, alpha=0.6, **kwargs` → `sns.scatterplot` (`hue`, `size`, `style`) |
 | `RegPlot` | `data, x, y, fit_reg=True, lowess=False, order=1, scatter=True, color="crimson", **kwargs` → `sns.regplot` |
 | `CorrelationHeatmap` | `data, columns=None, method="pearson", cmap="vlag", annot=True, fmt=".2f", **kwargs` |
-| `HistogramPlot` | `data: np.ndarray, bins=None, kde=False, color="skyblue", alpha=0.7, **kwargs` |
+| `HistogramPlot` | `data, bins=None, kde=False, color="skyblue", alpha=0.7, stat="density", **kwargs` |
 | `DistPlot` | `distribution, x_range=None, samples=1000, color="crimson", linewidth=2, label=None, **kwargs` |
-| `ACFPlot` | `data, nlags=40, alpha=0.05, color="steelblue", band_color="gray", **kwargs` |
+| `ACFPlot` | `data, nlags=40, alpha=0.05, color="steelblue", band_color="gray", linewidth=1.5, **kwargs` |
 | `QQPlot` | `data, distribution, color="steelblue", line_color="black", alpha=0.6, **kwargs` |
 | `ECDFPlot` | `data, compare=None, label="data", compare_label="compare", color="steelblue", compare_color="crimson", **kwargs` |
 | `NullPlot` | `result: NullResult, bins=None, alternative="two-sided", color="lightgrey", line_color="crimson", label=None, **kwargs` |
@@ -362,6 +388,10 @@ class PlotFits(BasePlot):
 class DecomposePlot(BasePlot):
     def plot(self, data: pd.DataFrame, column: str, period: int,
              model: str = "additive", **kwargs) -> Figure
+
+class FacetPlot(BasePlot):
+    def plot(self, inner: BasePlot, data: pd.DataFrame, by: str,
+             order: Optional[List[str]] = None, **kwargs)      # -> (fig, axes)
 ```
 
 Every `build` returns `(self.fig, self.ax)`, and every plot draws on `self.ax` / `self.fig`
@@ -369,8 +399,12 @@ rather than on matplotlib's current axes, so a layer placed with `plot_on_axes`
 axis it was handed.
 
 `PlotFits` overrides `plot` rather than `build`, because the panel count depends on the fit
-results. `HistogramPlot` uses `stat="density"` so a pdf overlays correctly; `DistPlot` takes a
-**frozen** distribution and falls back to `pmf` when there is no `pdf`.
+results — and so does `FacetPlot`, whose panel count comes from the data: one panel per
+level of `by`, each drawn by `inner` with the same kwargs, titles defaulting to the level
+names. `HistogramPlot` defaults to `stat="density"` so a pdf overlays correctly (pass
+`stat="count"` for plain counts); `DistPlot` takes a **frozen** distribution and falls back
+to `pmf` when there is no `pdf`. `ACFPlot` draws each lag as a vertical line rather than a
+bar — line width is in points, so hundreds of lags cannot alias into sub-pixel stripes.
 
 `NullPlot` composes `HistogramPlot` and `VerticalLine`: grey cloud, coloured line. It writes
 the observed value and its p-value into the legend, using `≤` when the p-value is at the

{goad_toolkit-0.2.13 → goad_toolkit-0.2.15}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "goad-toolkit"
-version = "0.2.13"
+version = "0.2.15"
 description = "An extensible toolkit for Goal Oriented Analysis of Data"
 readme = "README.md"
 authors = [

{goad_toolkit-0.2.13 → goad_toolkit-0.2.15}/src/goad_toolkit/datatransforms.py

@@ -208,6 +208,178 @@ class RegexFeature(TransformBase):
         return data
 
 
+class Filter(TransformBase):
+    """Keep the rows a query expression selects.
+
+    The expression is pandas' `DataFrame.query` syntax: column names bare,
+    `and`/`or`/`not` spelled out — e.g.
+    `"day_name == 'Thursday' and not is_release"`. A data decision written
+    as one readable line, which is what a pipeline step should be.
+    """
+
+    def transform(self, data: pd.DataFrame, expr: str) -> pd.DataFrame:
+        return data.query(expr)
+
+
+class SortValues(TransformBase):
+    """Sort rows by a column. Order is a data decision, so it lives here."""
+
+    def transform(
+        self, data: pd.DataFrame, column: str, ascending: bool = True
+    ) -> pd.DataFrame:
+        return data.sort_values(column, ascending=ascending).reset_index(drop=True)
+
+
+class Head(TransformBase):
+    """Keep the first `n` rows. After a sort, that is a top-n."""
+
+    def transform(self, data: pd.DataFrame, n: int) -> pd.DataFrame:
+        return data.head(n)
+
+
+class CountValues(TransformBase):
+    """One row per distinct value of a column, with how often it occurs.
+
+    Sorted most-frequent first, the way `value_counts` sorts.
+    `normalize=True` turns the counts into shares of the total.
+    """
+
+    def transform(
+        self,
+        data: pd.DataFrame,
+        column: str,
+        feature: str = "n",
+        normalize: bool = False,
+    ) -> pd.DataFrame:
+        counts = data[column].value_counts(normalize=normalize)
+        return counts.rename(feature).rename_axis(column).reset_index()
+
+
+class GroupAgg(TransformBase):
+    """Aggregate a column per group: one row per group, one value each.
+
+    `agg="size"` counts rows and needs no `column`; the count lands in
+    `feature` (default `"n"`). Any other `agg` is a pandas aggregation name
+    (`"sum"`, `"mean"`, `"nunique"`, ...) applied to `column`, landing in
+    `feature` (default: the column's own name). The output column is
+    `feature`, not `name` — `name` already names the pipeline step.
+    """
+
+    def transform(
+        self,
+        data: pd.DataFrame,
+        by,
+        column: Optional[str] = None,
+        agg: str = "size",
+        feature: Optional[str] = None,
+    ) -> pd.DataFrame:
+        if agg == "size":
+            result = data.groupby(by).size()
+            feature = feature or "n"
+        else:
+            if column is None:
+                raise ValueError(f"agg={agg!r} needs a column to aggregate")
+            result = data.groupby(by)[column].agg(agg)
+            feature = feature or column
+        return result.rename(feature).reset_index()
+
+
+class Share(TransformBase):
+    """Divide a column by its total, so the values become shares summing to one.
+
+    With `by`, totals are per group instead: each row becomes its share of
+    its own group's total, and every group sums to one separately — the move
+    that makes a small group and a large one comparable by shape.
+    `feature` writes the shares to a new column; by default the column is
+    replaced in place.
+    """
+
+    def transform(
+        self,
+        data: pd.DataFrame,
+        column: str,
+        feature: Optional[str] = None,
+        by=None,
+    ) -> pd.DataFrame:
+        if by is None:
+            total = data[column].sum()
+        else:
+            total = data.groupby(by)[column].transform("sum")
+        data[feature or column] = data[column] / total
+        return data
+
+
+class FlagDates(TransformBase):
+    """Mark the rows that fall on the given calendar days, as a boolean column.
+
+    The workhorse of event studies: flag release days, holidays, birthdays,
+    then filter or group on the flag. Matching is by calendar day — the
+    column's values are normalized to midnight, and timezone information is
+    dropped, before comparing — so a timestamp column works as-is. `dates`
+    is anything `pd.to_datetime` accepts.
+    """
+
+    def transform(
+        self, data: pd.DataFrame, column: str, dates, feature: str
+    ) -> pd.DataFrame:
+        values = pd.to_datetime(data[column])
+        if values.dt.tz is not None:
+            values = values.dt.tz_localize(None)
+        wanted = pd.to_datetime(list(dates))
+        if wanted.tz is not None:
+            wanted = wanted.tz_localize(None)
+        data[feature] = values.dt.normalize().isin(wanted.normalize())
+        return data
+
+
+class MapValues(TransformBase):
+    """Write a new column by mapping an existing one through a dict.
+
+    Values missing from the mapping become `default`, so a two-entry
+    mapping plus a default covers "weekend, everything else weekday".
+    """
+
+    def transform(
+        self,
+        data: pd.DataFrame,
+        column: str,
+        mapping: Dict[Any, Any],
+        feature: str,
+        default: Optional[Any] = None,
+    ) -> pd.DataFrame:
+        data[feature] = data[column].map(mapping)
+        if default is not None:
+            data[feature] = data[feature].fillna(default)
+        return data
+
+
+class SubtractBaseline(TransformBase):
+    """Subtract a baseline frame's column from the same column here, keyed on `on`.
+
+    The closing move of model-and-residual: the pipeline's frame carries the
+    measured values, `baseline` carries what the model says is normal, and
+    what flows on down the pipeline is the difference — the residual.
+    `feature` writes the difference to a new column; by default `column` is
+    replaced in place.
+    """
+
+    def transform(
+        self,
+        data: pd.DataFrame,
+        column: str,
+        baseline: pd.DataFrame,
+        on: str,
+        feature: Optional[str] = None,
+    ) -> pd.DataFrame:
+        colname = feature or column
+        merged = data.merge(
+            baseline[[on, column]], on=on, how="left", suffixes=("", "_baseline")
+        )
+        merged[colname] = merged[column] - merged[f"{column}_baseline"]
+        drop = [f"{column}_baseline"] + ([column] if colname != column else [])
+        return merged.drop(columns=drop)
+
+
 class Pipeline:
     """Pipeline for chaining data transformations."""