goad-toolkit 0.2.2__tar.gz → 0.2.4__tar.gz

{goad_toolkit-0.2.2 → goad_toolkit-0.2.4}/MCP_SERVER.md

@@ -103,13 +103,13 @@ You pin a version with `GOAD_REF` — a git ref (branch, tag, or commit). That o
 selects both the script (in the URL) and the docs it fetches (inside the script), so a whole
 cohort runs exactly the same thing and the two cannot drift apart.
 
-> **Note:** the docs and this server land in **v0.2.0**. Until that tag exists, point
-> `GOAD_REF` at the branch (`feat/docs-and-mcp`) or work from a local clone (see below).
+> **Note:** the docs and this server land in **v0.2.2**. 
+> You can also point `GOAD_REF` to a branch or work from a local clone (see below).
 
 ### Claude Code
 
 ```bash
-claude mcp add goad -e GOAD_REF=v0.2.0 -- \
+claude mcp add goad -e GOAD_REF=v0.2.2 -- \
   sh -c 'uv run --no-project https://raw.githubusercontent.com/raoulg/goad_toolkit/$GOAD_REF/goad_mcp.py'
 ```
 
@@ -123,7 +123,7 @@ Add to `.cursor/mcp.json` (per-project) or `~/.cursor/mcp.json` (global):
     "goad": {
       "command": "sh",
       "args": ["-c", "uv run --no-project https://raw.githubusercontent.com/raoulg/goad_toolkit/$GOAD_REF/goad_mcp.py"],
-      "env": { "GOAD_REF": "v0.2.0" }
+      "env": { "GOAD_REF": "v0.2.2" }
     }
   }
 }
@@ -137,7 +137,7 @@ Add to `~/.codex/config.toml`:
 [mcp_servers.goad]
 command = "sh"
 args = ["-c", "uv run --no-project https://raw.githubusercontent.com/raoulg/goad_toolkit/$GOAD_REF/goad_mcp.py"]
-env = { GOAD_REF = "v0.2.0" }
+env = { GOAD_REF = "v0.2.2" }
 ```
 
 ### Claude Desktop
@@ -151,7 +151,7 @@ app:
     "goad": {
       "command": "sh",
       "args": ["-c", "uv run --no-project https://raw.githubusercontent.com/raoulg/goad_toolkit/$GOAD_REF/goad_mcp.py"],
-      "env": { "GOAD_REF": "v0.2.0" }
+      "env": { "GOAD_REF": "v0.2.2" }
     }
   }
 }
@@ -187,7 +187,7 @@ add with the new tag:
 
 ```bash
 claude mcp remove goad -s user
-claude mcp add goad -s user -e GOAD_REF=v0.2.0 -- \
+claude mcp add goad -s user -e GOAD_REF=v0.2.2 -- \
   sh -c 'uv run --no-project https://raw.githubusercontent.com/raoulg/goad_toolkit/$GOAD_REF/goad_mcp.py'
 ```
 

{goad_toolkit-0.2.2 → goad_toolkit-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: goad-toolkit
-Version: 0.2.2
+Version: 0.2.4
 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>
@@ -13,6 +13,7 @@ Requires-Dist: pydantic>=2.10.6
 Requires-Dist: requests>=2.32.3
 Requires-Dist: scipy>=1.15.2
 Requires-Dist: seaborn>=0.13.2
+Requires-Dist: statsmodels>=0.14.4
 Requires-Dist: tqdm>=4.67.1
 Provides-Extra: parquet
 Requires-Dist: pyarrow>=19.0.0; extra == 'parquet'

{goad_toolkit-0.2.2 → goad_toolkit-0.2.4}/docs/02-pipelines.md

@@ -58,6 +58,7 @@ input frame is safe, and the steps stay cheap.
 | `SelectDataRange` | keep rows in a date range | `start_date`, `end_date` |
 | `RollingAvg` | rolling mean, drops the leading NaNs | `column`, `window`, `rename` |
 | `ZScaler` | standardise to mean 0, std 1 | `column`, `rename` |
+| `TimeFeatures` | derive calendar columns from a timestamp | `column`, `features` |
 
 `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
@@ -75,20 +76,17 @@ Subclass `TransformBase` and implement `transform`. That is the entire contract.
 from goad_toolkit.datatransforms import TransformBase
 import pandas as pd
 
-class TimeFeatures(TransformBase):
-    """Derive calendar features from a timestamp column."""
+class IsWeekend(TransformBase):
+    """Flag Saturday/Sunday from a timestamp column."""
 
     def transform(self, data: pd.DataFrame, column: str) -> pd.DataFrame:
         ts = pd.to_datetime(data[column])
-        data["date"] = ts.dt.date
-        data["hour"] = ts.dt.hour
-        data["day_name"] = ts.dt.day_name()
-        data["isoweek"] = ts.dt.isocalendar().week
+        data["is_weekend"] = ts.dt.dayofweek >= 5
         return data
 ```
 
 ```python
-pipeline.add(TimeFeatures, column="timestamp")
+pipeline.add(IsWeekend, column="timestamp")
 ```
 
 What the base class does for you:

{goad_toolkit-0.2.2 → goad_toolkit-0.2.4}/docs/03-plot-composition.md

@@ -151,9 +151,13 @@ step 3.
 | `ComparePlotDate` | `ComparePlot` + `VerticalDate` | |
 | `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) |
 | `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) |
+| `QQPlot` | sample quantiles vs. a distribution's theoretical quantiles | the tails, not the bulk — see [Distributions §5.5](05-distributions.md) |
+| `ECDFPlot` | one or two empirical CDFs, bin-free | the right tool for comparing two samples |
 
 `HistogramPlot` defaults to `sqrt(n)` bins capped at 50. That default is a starting point,
 not an answer — bin count changes what a histogram appears to say, and choosing it is part of
@@ -164,6 +168,14 @@ falling back to `pmf` for discrete families. Left to itself it picks an x-range
 0.1st to the 99.9th percentile, which is right for most things and wrong for anything with a
 very heavy tail — pass `x_range` explicitly there.
 
+`QQPlot` takes a sample and a *frozen* distribution and plots sorted data against the
+distribution's quantiles at matching plotting positions, with a y=x reference line —
+where `PlotFits`' histogram is dominated by the bulk of the data, this is where a tail
+mismatch actually shows up.
+
+`ECDFPlot` plots one sample, or two with `compare=`, as step functions of the empirical CDF —
+no bin width to choose, so nothing about the shape is a plotting decision.
+
 ## 3.7 Writing your own plot
 
 Two questions decide the shape:
@@ -216,9 +228,11 @@ lines of code.
   `self.ax.axvline(...)`, `self.fig.suptitle(...)`. Keeping to them is what makes
   `plot_on_axes` reliable.
 
-`PlotFits` overrides `plot` rather than `build`, because it needs to know how many panels to
-create before the figure exists. Its `build` is a no-op. It is the exception, not a pattern to
-copy.
+`PlotFits` and `DecomposePlot` override `plot` rather than `build`, because both need to know
+how many panels to create before the figure exists — variable for `PlotFits` (one per fit),
+fixed at four for `DecomposePlot`. Either way, `build` alone cannot decide the panel count
+before `create_figure` runs, so both leave it as a no-op. This is the exception, not a pattern
+to copy for a plot that only ever needs one axis.
 
 ---
 

{goad_toolkit-0.2.2 → goad_toolkit-0.2.4}/docs/04-five-families.md

@@ -76,10 +76,12 @@ the period is long relative to your intuition.
   the same data support different stories. Choose the window from the mechanism you are
   studying, before you look.
 
-**In GOAD:** `ShiftValues`, `DiffValues`, `RollingAvg`, `SelectDataRange` are all pipeline
-steps, so the smoothing window is a named parameter you can change in one line and rerun.
-`ComparePlot` puts raw and smoothed on the same axes; `VerticalDate` marks the moment you
-claim something changed, with a label, on the plot.
+**In GOAD:** `ShiftValues`, `DiffValues`, `RollingAvg`, `SelectDataRange`, `TimeFeatures` are
+all pipeline steps, so the smoothing window is a named parameter you can change in one line
+and rerun. `ComparePlot` puts raw and smoothed on the same axes; `VerticalDate` marks the
+moment you claim something changed, with a label, on the plot. `DecomposePlot` wraps
+`seasonal_decompose` into the four-panel observed/trend/seasonal/residual view; `ACFPlot`
+wraps `acf` with its confidence band, for finding a period you did not already suspect.
 
 ---
 
@@ -114,7 +116,8 @@ fitted pdf drawn over the histogram to see where it agrees and where it does not
   sample sizes are near-unreadable. Normalise, or use ECDFs, or do a two-sample test.
 
 **In GOAD:** `HistogramPlot` (density-scaled, so a pdf overlays correctly), `DistPlot` for a
-parametric curve, and `DistributionFitter` + `PlotFits` for the full ranked comparison. See
+parametric curve, `DistributionFitter` + `PlotFits` for the full ranked comparison, and
+`QQPlot` / `ECDFPlot` for the tail diagnostics a histogram cannot show. See
 [Distributions](05-distributions.md).
 
 ---

{goad_toolkit-0.2.2 → goad_toolkit-0.2.4}/docs/05-distributions.md

@@ -25,7 +25,7 @@ kind of process you are looking at.
 needs: the scipy object, whether it is discrete, and how many parameters it takes.
 
 Shipped: `norm`, `uniform`, `lognorm`, `poisson`, `exponential`, `skewnorm`, `gamma`,
-`weibull`.
+`weibull`, `bernoulli`, `binomial`, `nbinom`, `beta`.
 
 ```python
 from goad_toolkit.distributions import DistributionRegistry
@@ -36,10 +36,16 @@ registry.get_names()
 registry.register_distribution("pareto", stats.pareto, is_discrete=False, num_params=3)
 ```
 
-Registering a family is the extension point that matters most in practice, because the
-shipped set is missing things real data needs — `pareto` and `zipf` for rank-frequency data,
-`bernoulli` and `binom` for yes/no outcomes, `nbinom` for over-dispersed counts, `beta` for a
-distribution over a probability.
+`pareto` is deliberately not in the shipped set, even though the chat corpus is exactly the
+kind of data it fits — word frequency and burst lengths are rank-frequency data, the
+textbook case for a power law. Registering it yourself, as above, is the extensibility
+exercise: a fit run without it will call the same data "lognormal" and look convincing, and
+registering `pareto` is what exposes that the winner depends on what you thought to try.
+`zipf` is the same story for discrete rank data and ships the same way.
+
+Registering a family is the extension point that matters whenever the shipped set is still
+missing something real data needs — a power-law family among them, `zipf` for discrete
+rank data, or anything scipy has that GOAD has not wrapped.
 
 Two things to know before you rely on it:
 
@@ -154,8 +160,7 @@ What to look at, in order:
 
 1. **The tails.** This is where families differ and where the fit matters, and it is also
    where a histogram has the fewest observations and is least readable. If your question is
-   about extreme values, a histogram will not settle it — use a qq-plot or an ECDF on a log
-   scale.
+   about extreme values, a histogram will not settle it — use `QQPlot` or `ECDFPlot`, below.
 2. **Systematic deviation, not point-by-point wobble.** A curve that is above the histogram
    on the left and below it on the right is a wrong-shape signal. Individual bars being off
    is sampling noise.
@@ -163,6 +168,43 @@ What to look at, in order:
    log-likelihoods have not been distinguished by your data, and picking one is a choice you
    should make on mechanism, not on the fourth decimal place.
 
+### `QQPlot`, `ECDFPlot`, and `fit_table`
+
+```python
+from goad_toolkit.visualizer import QQPlot, ECDFPlot, PlotSettings
+
+QQPlot(PlotSettings(title="Residuals vs. normal")).plot(
+    data=data["residual"], distribution=best.frozen_dist,
+)
+```
+
+`QQPlot` sorts the sample and plots it against the fitted (frozen) distribution's quantiles
+at matching plotting positions, with a y=x reference line. A fit that looked fine in
+`PlotFits`' histogram can still bend away from that line in the tails — which is the point:
+the histogram is dominated by the bulk, the qq-plot is not.
+
+```python
+ECDFPlot(PlotSettings()).plot(
+    data=group_a["value"], compare=group_b["value"],
+    label="group a", compare_label="group b",
+)
+```
+
+`ECDFPlot` draws one empirical CDF, or two with `compare=` for a direct two-sample
+comparison — no bin width to choose, so the shape on screen is entirely the data's, not a
+plotting decision.
+
+```python
+from goad_toolkit.analytics import fit_table
+
+fit_table(results)
+```
+
+`fit_table` turns a list of `fit()` results into the dataframe a student should hand in
+instead of a screenshot of a picture: distribution, fitted params, log-likelihood, KS
+statistic and p-value, and which criteria (if any) it won — ranked by log-likelihood, with
+`FailedFit` rows sorted last and their message kept instead of a blank row.
+
 ## 5.6 Outliers, properly
 
 The sequence that avoids the usual mistake:
@@ -195,6 +237,9 @@ data is.
 | lognormal | *products* of many factors | message length, income, response time, file size |
 | exponential | waiting time between independent events | time between messages, within a burst |
 | Poisson | counts of independent rare events in a fixed window | messages per hour, arrivals per day |
+| negative binomial | over-dispersed counts — a Poisson whose rate itself varies | messages per day across people, not within a steady process |
+| Bernoulli | a single yes/no trial | did this message get a reply, is this author still active |
+| binomial | a fixed number of independent yes/no trials | replies within N messages, conversions per N views |
 | power law / Pareto | preferential attachment, "rich get richer" | word frequency by rank, followers, city size |
 | gamma / Weibull | sums of exponentials; time-to-failure with changing hazard | durations, lifetimes |
 | beta | a distribution *over a probability* | uncertainty about a rate, A/B test posteriors |

{goad_toolkit-0.2.2 → goad_toolkit-0.2.4}/docs/08-api-reference.md

@@ -83,10 +83,15 @@ class TransformBase(ABC):
 | `SelectDataRange` | `start_date: str, end_date: str` |
 | `RollingAvg` | `column: str, window: int, rename: bool = False` |
 | `ZScaler` | `column: str, rename: bool = False` |
+| `TimeFeatures` | `column: str, features: Optional[List[str]] = None` |
 
 `rename=True` writes to `{column}_shifted` / `_diff` / `_rolling_avg` / `_zscore` instead of
 overwriting.
 
+`TimeFeatures.AVAILABLE` is `("date", "hour", "day_name", "isoweek", "year_week")`;
+`TimeFeatures.DEFAULT` — used when `features` is omitted — is `("day_name", "isoweek",
+"year_week")`. A feature named the same as `column` overwrites it.
+
 ```python
 class Pipeline:
     def add(self, transform_class: Type[T], name: Optional[str] = None, **kwargs) -> "Pipeline"
@@ -134,8 +139,11 @@ class DistributionRegistry:
 ```
 
 Registered by default: `norm`, `uniform`, `lognorm`, `poisson`, `exponential`, `skewnorm`,
-`gamma`, `weibull`. Every instance starts from that set, so a registration is scoped to the
-registry you made it on — hand that registry to `DistributionFitter(registry)` to use it.
+`gamma`, `weibull`, `bernoulli`, `binomial`, `nbinom`, `beta`. Every instance starts from that
+set, so a registration is scoped to the registry you made it on — hand that registry to
+`DistributionFitter(registry)` to use it. `pareto` is not in the default set — lesson 4 has
+the student register it, since a default fit missing the one family the data actually needs
+is the point of that exercise.
 
 ---
 
@@ -187,10 +195,21 @@ class DistributionFitter:
 
     @staticmethod
     def best(results: list[Result], criterion: str = "combined") -> list[Result]
+
+def fit_table(results: list[Result]) -> pd.DataFrame
 ```
 
 `criterion` is one of `"likelihood"`, `"ks"`, `"combined"`. Failures are returned as
-`FailedFit` values rather than raised.
+`FailedFit` values rather than raised. `log_likelihood` is computed with `logpdf` for
+continuous families and `logpmf` for discrete ones. The two criteria are marked
+independently: a `criterion="combined"` fit where every KS p-value comes back exactly 0
+(routine for discrete families on a large, tied sample) still gets a `best_likelihood`
+winner — it just has no `best_ks` winner.
+
+`fit_table` turns a list of results into one row per distribution — `distribution`, `params`,
+`log_likelihood`, `ks_stat`, `ks_pvalue`, `best_likelihood`, `best_ks`, `message` — ranked by
+`log_likelihood` descending, with `FailedFit` rows (their `message` kept, metrics `NaN`)
+sorted last.
 
 ---
 
@@ -267,12 +286,19 @@ class BasePlot(ABC):
 | `ResidualPlot` | `data, x, y, date, datelabel, interval: int = 1` |
 | `HistogramPlot` | `data: np.ndarray, bins=None, kde=False, color="skyblue", alpha=0.7, **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` |
+| `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` |
 
 ```python
 class PlotFits(BasePlot):
     def plot(self, data: np.ndarray,
              fit_results: List[Result],
              fitplotsettings: FitPlotSettings) -> Figure
+
+class DecomposePlot(BasePlot):
+    def plot(self, data: pd.DataFrame, column: str, period: int,
+             model: str = "additive", **kwargs) -> Figure
 ```
 
 Every `build` returns `(self.fig, self.ax)`, and every plot draws on `self.ax` / `self.fig`
@@ -309,12 +335,22 @@ of `likelihood`, `ks`, `combined`; `--method` is passed to `scipy.stats.fit`.
 
 ## 8.10 Rough edges worth knowing
 
-- `PlotFits` overrides `plot` rather than `build`; its `build` is a no-op. It is the one
-  exception to the `build` contract.
+- `PlotFits` and `DecomposePlot` override `plot` rather than `build`; their `build` is a
+  no-op. Both need the panel count decided before `create_figure` runs — from the fit results
+  for `PlotFits`, always four for `DecomposePlot` — which `build` alone cannot do.
 - Fits that fail come back as `FailedFit` values in the result list rather than raising, so
   a list of results can contain both kinds and needs an `isinstance` check.
 - `Pipeline.apply` copies the frame once and then mutates that copy in place, so transforms
   see each other's columns — the order you add steps in matters.
+- `ACFPlot` raises `ValueError` if the data contains NaNs, rather than passing them through.
+  `statsmodels.tsa.stattools.acf` does not raise on missing values — it silently returns an
+  all-NaN result — so a decomposition's residual needs `.dropna()` before it reaches `ACFPlot`.
+- `binomial` and `nbinom` fit two shape parameters (`n`, `p`) from the sample mean and
+  variance alone. If `n` is not known independently, it is not identifiable from the data —
+  many `(n, p)` pairs with the same `n·p` fit about as well, so a fitted `n` should be treated
+  as "consistent with the mean", not as a recovered count of trials. When you know `n` from
+  the process (a fixed number of messages, a fixed number of views), trust that `n`, not the
+  fitted one.
 
 ---
 

{goad_toolkit-0.2.2 → goad_toolkit-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "goad-toolkit"
-version = "0.2.2"
+version = "0.2.4"
 description = "An extensible toolkit for Goal Oriented Analysis of Data"
 readme = "README.md"
 authors = [
@@ -16,6 +16,7 @@ dependencies = [
     "requests>=2.32.3",
     "scipy>=1.15.2",
     "seaborn>=0.13.2",
+    "statsmodels>=0.14.4",
     "tqdm>=4.67.1",
 ]
 urls = {Github = "https://github.com/raoulg/goad_toolkit"}

{goad_toolkit-0.2.2 → goad_toolkit-0.2.4}/src/goad_toolkit/analytics.py

@@ -2,6 +2,7 @@ from dataclasses import dataclass
 from typing import Any, List, Optional, Tuple, Union
 
 import numpy as np
+import pandas as pd
 from loguru import logger
 from scipy import stats
 
@@ -105,7 +106,11 @@ class DistributionFitter:
         # Create bounds based on parameter count
         if dist_obj.num_params == 1:
             if dist_obj.is_discrete:
-                mean_lower_bound = max(0.1, float(data_mean / 10))
+                # A single-parameter discrete family's shape parameter is not always
+                # a count-scale rate (poisson's lambda) — it can be a probability
+                # (bernoulli's p), which is routinely well under 0.1, so the floor
+                # here stays near zero rather than at 0.1.
+                mean_lower_bound = max(1e-3, float(data_mean / 10))
                 mean_upper_bound = float(data_mean * 10)
                 return [(mean_lower_bound, mean_upper_bound)]
             else:
@@ -134,15 +139,17 @@ class DistributionFitter:
 
     def _calculate_loglikelihood(self, data: np.ndarray, dist_obj, params) -> float:
         """Calculate log-likelihood of data given distribution and parameters.
-        For every datapoint, calculate the log probability density function (PDF)
-        We sum all the log PDFs to get the log-likelihood of the data.
-        If there are a lot of datapoints with very low probability, the log-likelihood
-        will be very negative (or -inf if probability is 0).
+        For every datapoint, calculate the log density (continuous families, via
+        logpdf) or the log mass (discrete families, via logpmf). We sum them to get
+        the log-likelihood of the data. If there are a lot of datapoints with very
+        low probability, the log-likelihood will be very negative (or -inf if
+        probability is 0).
 
         We will prefer distributions with higher log-likelihood values.
         """
         try:
-            return np.sum(dist_obj.dist.logpdf(data, *params))
+            log_density = dist_obj.dist.logpmf if dist_obj.is_discrete else dist_obj.dist.logpdf
+            return np.sum(log_density(data, *params))
         except Exception as e:
             logger.warning(f"Log-likelihood calculation failed: {str(e)}")
             return -np.inf
@@ -239,33 +246,24 @@ class DistributionFitter:
                     best_ks_value = fit_ks
                     best_ks_fit = fit
 
-        # Only mark if we found best fits
-        if best_likelihood_fit is not None and best_ks_fit is not None:
-            # Mark based on criterion
-            if criterion == "likelihood":
-                # Mark only likelihood best
-                for fit in fits:
-                    if isinstance(fit, FitResult):
-                        fit.best_likelihood = (
-                            fit.distribution == best_likelihood_fit.distribution
-                        )
-
-            elif criterion == "ks":
-                # Mark only KS best
-                for fit in fits:
-                    if isinstance(fit, FitResult):
-                        fit.best_ks = fit.distribution == best_ks_fit.distribution
-
-            elif criterion == "combined":
-                # Mark both
-                for fit in fits:
-                    if isinstance(fit, FitResult):
-                        fit.best_likelihood = (
-                            fit.distribution == best_likelihood_fit.distribution
-                        )
-                        fit.best_ks = fit.distribution == best_ks_fit.distribution
-            else:
-                raise ValueError(f"Unknown criterion '{criterion}'")
+        if criterion not in ("likelihood", "ks", "combined"):
+            raise ValueError(f"Unknown criterion '{criterion}'")
+
+        # Each criterion is marked independently: a KS test that never clears the
+        # p > 0 threshold (routine for discrete families on a large sample, where
+        # ties push the p-value to numerical zero) must not suppress a perfectly
+        # good best_likelihood winner, and vice versa.
+        if criterion in ("likelihood", "combined") and best_likelihood_fit is not None:
+            for fit in fits:
+                if isinstance(fit, FitResult):
+                    fit.best_likelihood = (
+                        fit.distribution == best_likelihood_fit.distribution
+                    )
+
+        if criterion in ("ks", "combined") and best_ks_fit is not None:
+            for fit in fits:
+                if isinstance(fit, FitResult):
+                    fit.best_ks = fit.distribution == best_ks_fit.distribution
 
         # Return the original list
         return fits
@@ -327,3 +325,46 @@ class DistributionFitter:
             ]
         else:
             raise ValueError(f"Unknown criterion '{criterion}'")
+
+
+def fit_table(results: List[Result]) -> pd.DataFrame:
+    """Turn a list of fit results into a ranked dataframe: what a student hands in.
+
+    One row per distribution: name, fitted params, log-likelihood, KS statistic and
+    KS p-value, plus which criteria (if any) it won. Ranked by log-likelihood,
+    descending; `FailedFit` entries carry their failure message in `message` and
+    sort last, since a missing likelihood is not a small likelihood.
+    """
+    rows = []
+    for result in results:
+        if isinstance(result, FitResult):
+            rows.append(
+                {
+                    "distribution": result.distribution,
+                    "params": result.params,
+                    "log_likelihood": result.log_likelihood,
+                    "ks_stat": result.kstest.statistic if result.kstest else float("nan"),
+                    "ks_pvalue": result.kstest.p_value if result.kstest else float("nan"),
+                    "best_likelihood": bool(result.best_likelihood),
+                    "best_ks": bool(result.best_ks),
+                    "message": result.message,
+                }
+            )
+        else:
+            rows.append(
+                {
+                    "distribution": result.distribution,
+                    "params": None,
+                    "log_likelihood": float("nan"),
+                    "ks_stat": float("nan"),
+                    "ks_pvalue": float("nan"),
+                    "best_likelihood": False,
+                    "best_ks": False,
+                    "message": result.message,
+                }
+            )
+
+    table = pd.DataFrame(rows)
+    return table.sort_values(
+        "log_likelihood", ascending=False, na_position="last"
+    ).reset_index(drop=True)

{goad_toolkit-0.2.2 → goad_toolkit-0.2.4}/src/goad_toolkit/datatransforms.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import Any, Dict, Optional, Type, TypeVar
+from typing import Any, Dict, List, Optional, Type, TypeVar
 
 import pandas as pd
 from tqdm import tqdm
@@ -122,6 +122,45 @@ class ZScaler(TransformBase):
         return data
 
 
+class TimeFeatures(TransformBase):
+    """Derive calendar features from a timestamp column.
+
+    `features` picks which columns to write, from `"date"`, `"hour"`,
+    `"day_name"`, `"isoweek"`, `"year_week"`. Defaults to `"day_name"`,
+    `"isoweek"`, `"year_week"` — the three lesson 1 already relies on.
+    A feature named the same as `column` overwrites it.
+    """
+
+    AVAILABLE = ("date", "hour", "day_name", "isoweek", "year_week")
+    DEFAULT = ("day_name", "isoweek", "year_week")
+
+    def transform(
+        self,
+        data: pd.DataFrame,
+        column: str,
+        features: Optional[List[str]] = None,
+    ) -> pd.DataFrame:
+        selected = list(features) if features is not None else list(self.DEFAULT)
+        unknown = set(selected) - set(self.AVAILABLE)
+        if unknown:
+            raise ValueError(
+                f"Unknown feature(s) {sorted(unknown)}; choose from {self.AVAILABLE}"
+            )
+
+        ts = pd.to_datetime(data[column])
+        if "date" in selected:
+            data["date"] = ts.dt.date
+        if "hour" in selected:
+            data["hour"] = ts.dt.hour
+        if "day_name" in selected:
+            data["day_name"] = ts.dt.day_name()
+        if "isoweek" in selected:
+            data["isoweek"] = ts.dt.isocalendar().week
+        if "year_week" in selected:
+            data["year_week"] = ts.dt.strftime("%Y-%W")
+        return data
+
+
 class Pipeline:
     """Pipeline for chaining data transformations."""
 

{goad_toolkit-0.2.2 → goad_toolkit-0.2.4}/src/goad_toolkit/distributions.py

@@ -54,6 +54,22 @@ class DistributionRegistry:
         self.register_distribution(
             "weibull", stats.weibull_min, is_discrete=False, num_params=3
         )
+        self.register_distribution(
+            "bernoulli", stats.bernoulli, is_discrete=True, num_params=1
+        )
+        self.register_distribution(
+            "binomial", stats.binom, is_discrete=True, num_params=2
+        )
+        self.register_distribution(
+            "nbinom", stats.nbinom, is_discrete=True, num_params=2
+        )
+        self.register_distribution("beta", stats.beta, is_discrete=False, num_params=4)
+        # pareto is deliberately not shipped here: lesson 4 has the student
+        # register it themselves as the extensibility exercise, and a fit that
+        # silently has pareto available from the start would remove the point
+        # of that exercise. Register it yourself when you need it:
+        #   registry.register_distribution("pareto", stats.pareto,
+        #                                   is_discrete=False, num_params=3)
 
     def __repr__(self) -> str:
         """Detailed representation of the registry."""