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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: goad-toolkit
-Version: 0.2.4
+Version: 0.2.7
 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>
@@ -204,6 +204,36 @@ For the [kstest](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stat
 The plots are sorted by log-likelihood, which means there is no good fit with a distribution in this case.
 ![residuals](img/distribution_fit.png)
 
+### 🎲 Is it real? The shuffle test
+
+Shuffle the labels, measure again, and see where the real number lands. No test, no
+assumptions, no table of critical values — just a picture of what your measurement does when
+the label means nothing:
+
+```python
+from goad_toolkit.analytics import NullDistribution
+from goad_toolkit.visualizer import NullPlot, PlotSettings
+
+def gap(frame):
+    means = frame.groupby("is_bot")["length"].mean()
+    return means[True] - means[False]
+
+result = NullDistribution(gap, n_iter=2000, seed=1).run(data, label="is_bot")
+settings = PlotSettings(
+    title="Mean message length: bots minus humans",
+    xlabel="difference in mean length (characters)",
+    ylabel="density under shuffled labels",
+)
+NullPlot(settings).plot(result=result)
+```
+
+![null distribution](img/null-distribution.png)
+
+The grey cloud is the statistic under shuffled labels; the line is what the real data did.
+Writing the statistic is your job — that is the claim. See
+[Models and residuals](docs/06-models-and-residuals.md) §6.7 for what the p-value can and
+cannot carry.
+
 ### 🧩 Extending with Custom Distributions
 
 You can easily register new distributions:

{goad_toolkit-0.2.4 → goad_toolkit-0.2.7}/README.md

@@ -183,6 +183,36 @@ For the [kstest](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stat
 The plots are sorted by log-likelihood, which means there is no good fit with a distribution in this case.
 ![residuals](img/distribution_fit.png)
 
+### 🎲 Is it real? The shuffle test
+
+Shuffle the labels, measure again, and see where the real number lands. No test, no
+assumptions, no table of critical values — just a picture of what your measurement does when
+the label means nothing:
+
+```python
+from goad_toolkit.analytics import NullDistribution
+from goad_toolkit.visualizer import NullPlot, PlotSettings
+
+def gap(frame):
+    means = frame.groupby("is_bot")["length"].mean()
+    return means[True] - means[False]
+
+result = NullDistribution(gap, n_iter=2000, seed=1).run(data, label="is_bot")
+settings = PlotSettings(
+    title="Mean message length: bots minus humans",
+    xlabel="difference in mean length (characters)",
+    ylabel="density under shuffled labels",
+)
+NullPlot(settings).plot(result=result)
+```
+
+![null distribution](img/null-distribution.png)
+
+The grey cloud is the statistic under shuffled labels; the line is what the real data did.
+Writing the statistic is your job — that is the claim. See
+[Models and residuals](docs/06-models-and-residuals.md) §6.7 for what the p-value can and
+cannot carry.
+
 ### 🧩 Extending with Custom Distributions
 
 You can easily register new distributions:

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

@@ -59,6 +59,7 @@ input frame is safe, and the steps stay cheap.
 | `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` |
+| `RegexFeature` | count / flag / extract a pattern in a text column | `column`, `pattern`, `feature`, `mode` |
 
 `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
@@ -104,39 +105,39 @@ Two rules for your `transform`:
 - **Name your parameters explicitly** in the signature. `def transform(self, data, column,
   window)` documents itself; `**kwargs` does not, and the validation cannot help you.
 
-## 2.5 A transform for feature enrichment
+## 2.5 `RegexFeature`: feature enrichment from text
 
-The single most useful custom transform for text data, and a good template:
+The single most useful transform for text data, and the reason `TransformBase` is worth
+subclassing at all. It ships:
 
 ```python
-class RegexFeature(TransformBase):
-    """Add a feature extracted from a text column with a regular expression."""
-
-    def transform(
-        self,
-        data: pd.DataFrame,
-        column: str,
-        pattern: str,
-        feature: str,
-        mode: str = "count",
-    ) -> pd.DataFrame:
-        text = data[column].fillna("")
-        if mode == "count":
-            data[feature] = text.str.count(pattern)
-        elif mode == "has":
-            data[feature] = text.str.contains(pattern, regex=True)
-        elif mode == "extract":
-            data[feature] = text.str.extract(pattern, expand=False)
-        else:
-            raise ValueError(f"mode must be count/has/extract, got {mode!r}")
-        return data
-```
+from goad_toolkit.datatransforms import RegexFeature
 
-```python
 pipeline.add(RegexFeature, name="url_flag",
              column="message", pattern=r"https?://\S+", feature="has_url", mode="has")
 ```
 
+Three modes, each writing one new column named by `feature`:
+
+| `mode` | writes | use for |
+|---|---|---|
+| `"count"` | how many times the pattern occurs (int) | how many URLs, how many question marks |
+| `"has"` | whether it occurs at all (bool) | flags you will group or filter on |
+| `"extract"` | the first capture group, NaN where nothing matched | pulling a value *out* of the text |
+
+`"extract"` needs exactly one capture group in `pattern`, and it is the mode worth being
+careful with. `count` and `has` fail visibly when a pattern is wrong — a column of all zeros
+or all `False` is hard to miss. Extraction fails *silently*, filling with NaN, so it reports
+its own coverage through `loguru`:
+
+```
+mentions: extracted 'addressed_to' from 92,415/627,172 rows (14.7%); 534,757 rows had no match
+```
+
+That number is the point. A pattern that matches 15% of rows may be exactly right — on IRC,
+most messages do not address anyone — or it may be silently broken. The log line makes you
+decide which, instead of finding out four notebooks later.
+
 Note the two different `name`s: `Pipeline.add(name=...)` names the *step*, and
 `TransformBase.__init__` consumes it. So the new-column parameter has to be called something
 else — `feature` here. Any transform that wants to name an output column hits this.

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

@@ -149,9 +149,22 @@ to look.
   are not independent evidence. This is exactly why regularisation is the better tool for
   "which variables matter" — see [Models and residuals](06-models-and-residuals.md).
 
-**In GOAD:** the scatter and the fit are `BasePlot` subclasses; the interesting work is in
-[Models and residuals](06-models-and-residuals.md), because a relation you can state as a
-model is a relation whose failures you can inspect.
+**In GOAD:** `ScatterPlot`, `RegPlot` and `CorrelationHeatmap`, in that order of use.
+
+```python
+scatter = ScatterPlot(settings)
+scatter.plot(data=data, x="messages", y="length", hue="is_bot")
+scatter.plot_on(RegPlot(settings), data=data, x="messages", y="length", scatter=False)
+```
+
+The layering is the point: the scatter is drawn first and the fit goes on top of it, so the
+choice of `fit_reg`, `order` or `lowess` is made after you have seen the shape rather than
+before. `CorrelationHeatmap` is the entry point when there are too many pairs to plot — it
+tells you which scatter to make next, and nothing more than that.
+
+The interesting work is still in [Models and residuals](06-models-and-residuals.md), because
+a relation you can state as a model is a relation whose failures you can inspect — and
+§6.7 is how you check that the relation is not something a shuffle would have produced.
 
 ---
 

{goad_toolkit-0.2.4 → goad_toolkit-0.2.7}/docs/06-models-and-residuals.md

@@ -158,6 +158,50 @@ They compose: the residual of a functional model is what you fit a distribution
 composition is the loop from [Goal oriented analysis](01-goal-oriented-analysis.md) §1.3, and
 it is where the two halves of this library meet.
 
+## 6.7 The shuffle test
+
+§6.1 said a model is a statement about what is boring. The most boring statement available is
+*this label explains nothing*, and you can build that model without writing one down: shuffle
+the label column and measure again. Everything else stays as it was — the labels keep their
+proportions, the values keep their shape — and only the pairing between them is destroyed.
+Do it a thousand times and you have a picture of what your measurement does in a world where
+there is nothing to find.
+
+```python
+from goad_toolkit.analytics import NullDistribution
+from goad_toolkit.visualizer import NullPlot, PlotSettings
+
+def gap(frame):
+    means = frame.groupby("is_bot")["length"].mean()
+    return means[True] - means[False]
+
+result = NullDistribution(gap, n_iter=2000, seed=1).run(data, label="is_bot")
+NullPlot(PlotSettings(xlabel="difference in mean length")).plot(result=result)
+```
+
+The statistic is yours. `NullDistribution` runs the loop; deciding *what* to measure and
+*which* column to shuffle is the part that cannot be delegated, because it is the claim.
+
+Read the picture, not the number. Either the line stands clear of the grey cloud or it sits
+inside it, and that judgement needs no test, no distributional assumption, and no table of
+critical values. A finding sitting in the middle of its own null is not a weak finding; it is
+the null, and the honest write-up says so.
+
+Three things worth knowing before you quote a number from it:
+
+- **`p_value()` counts, it does not test.** It is the fraction of shuffles that matched or
+  beat what you saw, defaulting to two-sided. The observed arrangement is itself one of the
+  arrangements, so the count starts at one and the smallest reportable value is
+  `1 / (n_iter + 1)`. With 2000 shuffles, "p ≤ 0.001" is the strongest sentence available —
+  which is why `NullPlot` writes `≤` on the plot when you are at that floor.
+- **It answers one question.** Run it on the fifteenth thing you measured and it will happily
+  report the fifteenth thing as striking. The shuffle test defends against noise, not against
+  the garden of forking paths ([Analysis method](09-analysis-method.md) §9.6) — only writing
+  the question down first, or confirming on a slice you did not hunt on, does that.
+- **Shuffling the label tests the label.** If a confounder drives both the label and the
+  value, shuffling breaks the confounding too, and the test will confirm an association that
+  is real but not the mechanism you have in mind.
+
 ---
 
 Next: [Visual critique](07-visual-critique.md) — judging the picture you just made.

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

@@ -84,6 +84,7 @@ class TransformBase(ABC):
 | `RollingAvg` | `column: str, window: int, rename: bool = False` |
 | `ZScaler` | `column: str, rename: bool = False` |
 | `TimeFeatures` | `column: str, features: Optional[List[str]] = None` |
+| `RegexFeature` | `column: str, pattern: str, feature: str, mode: str = "count"` |
 
 `rename=True` writes to `{column}_shifted` / `_diff` / `_rolling_avg` / `_zscore` instead of
 overwriting.
@@ -92,6 +93,12 @@ overwriting.
 `TimeFeatures.DEFAULT` — used when `features` is omitted — is `("day_name", "isoweek",
 "year_week")`. A feature named the same as `column` overwrites it.
 
+`RegexFeature.mode` is one of `"count"` (int), `"has"` (bool) or `"extract"` (the first
+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.
+
 ```python
 class Pipeline:
     def add(self, transform_class: Type[T], name: Optional[str] = None, **kwargs) -> "Pipeline"
@@ -211,6 +218,33 @@ winner — it just has no `best_ks` winner.
 `log_likelihood` descending, with `FailedFit` rows (their `message` kept, metrics `NaN`)
 sorted last.
 
+The shuffle test — see [Models and residuals](06-models-and-residuals.md) §6.7:
+
+```python
+@dataclass
+class NullResult:
+    observed: float
+    null: np.ndarray                     # the statistic under n_iter shuffles
+    n_iter: int
+    seed: Optional[int] = None
+
+    def p_value(self, alternative: str = "two-sided") -> float
+    quantile: float                      # property, where observed sits in the null
+
+class NullDistribution:
+    def __init__(self, statistic: Callable[[pd.DataFrame], float],
+                 n_iter: int = 1000, seed: Optional[int] = None)
+
+    def run(self, data: pd.DataFrame, label: str) -> NullResult
+```
+
+`statistic` takes a frame and returns one number; `run` calls it once on the data as given,
+then once per shuffle of the `label` column. The caller's frame is never modified.
+`alternative` is one of `"two-sided"`, `"greater"`, `"less"`. Both one-sided counts include
+the observed arrangement, so `p_value` bottoms out at `1 / (n_iter + 1)` rather than 0. A
+`label` that is not a column raises `ValueError`, as does a statistic that is not finite on
+the unshuffled data; non-finite values among the shuffles are logged, not raised.
+
 ---
 
 ## 8.7 `goad_toolkit.models`
@@ -281,14 +315,19 @@ class BasePlot(ABC):
 | `LinePlot` | `data, **kwargs` → `sns.lineplot` |
 | `ComparePlot` | `data, x, y1, y2, **kwargs` |
 | `VerticalDate` | `date: str, label: str` |
+| `VerticalLine` | `x: float, label=None, color="crimson", linestyle="--", linewidth=2, **kwargs` |
 | `ComparePlotDate` | `data, x, y1, y2, date, datelabel, **kwargs` |
 | `BarWithDates` | `data, x, y, interval: int = 1, **kwargs` |
 | `ResidualPlot` | `data, x, y, date, datelabel, interval: int = 1` |
+| `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` |
 | `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` |
+| `NullPlot` | `result: NullResult, bins=None, alternative="two-sided", color="lightgrey", line_color="crimson", label=None, **kwargs` |
 
 ```python
 class PlotFits(BasePlot):
@@ -309,6 +348,17 @@ axis it was handed.
 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`.
 
+`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
+floor set by `n_iter`. Pass `label` to write your own.
+
+`RegPlot` wraps `sns.regplot`, the axes-level counterpart to `sns.lmplot` — `lmplot` builds
+its own figure and cannot draw onto a `BasePlot` axis. `lowess=True` with `order != 1` raises:
+both are answers to "what shape", and only one can apply. Pass `scatter=False` to layer a fit
+over an existing `ScatterPlot`. `CorrelationHeatmap` drops non-numeric columns, raises when
+nothing numeric is left, and pins the colour scale to [-1, 1] centred on 0 — override with
+`vmin` / `vmax` / `center` in `**kwargs` if you must.
+
 ---
 
 ## 8.9 `goad_toolkit.cli`
@@ -345,6 +395,10 @@ of `likelihood`, `ks`, `combined`; `--method` is passed to `scipy.stats.fit`.
 - `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`.
+- A seaborn function called with `x=` and `y=` as column names writes those names onto the
+  axes, overwriting the `xlabel` / `ylabel` from `PlotSettings`. `create_figure` runs first,
+  seaborn runs second, and second wins. Set the labels on the axis after plotting when the
+  column name is not the label you want a reader to see.
 - `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

{goad_toolkit-0.2.4 → goad_toolkit-0.2.7}/docs/09-analysis-method.md

@@ -141,7 +141,9 @@ See [Visual critique](07-visual-critique.md).
 | Does it survive changing the parameter from stage 4? | If it does not, the finding is about the parameter | the sweep you ran |
 | If you modelled it, what does the residual look like? | Structure in the residual is an unmodelled mechanism, not noise | the residual's shape over time and its distribution |
 
-See [Models and residuals](06-models-and-residuals.md) §6.3.
+See [Models and residuals](06-models-and-residuals.md) §6.3 for the residual loop, and §6.7
+for the shuffle test — `NullDistribution` runs the resampling once you have said what to
+shuffle.
 
 ### The garden of forking paths
 

{goad_toolkit-0.2.4 → goad_toolkit-0.2.7}/goad_mcp.py

@@ -697,8 +697,8 @@ STAGE_ROWS: dict[AnalysisStage, list[StageRow]] = {
             "did not suggest it",
         ),
         (
-            "If you shuffled the labels and re-measured, how often would you see something "
-            "this strong?",
+            f"If you shuffled the labels and re-measured, how often would you see something "
+            f"this strong? ({_models()} §6.7)",
             "The cheapest honest check available, and it needs no distributional theory at "
             "all.",
             "what gets shuffled, and a rough frequency",

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

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

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

@@ -1,5 +1,5 @@
 from dataclasses import dataclass
-from typing import Any, List, Optional, Tuple, Union
+from typing import Any, Callable, List, Optional, Tuple, Union
 
 import numpy as np
 import pandas as pd
@@ -148,7 +148,9 @@ class DistributionFitter:
         We will prefer distributions with higher log-likelihood values.
         """
         try:
-            log_density = dist_obj.dist.logpmf if dist_obj.is_discrete else dist_obj.dist.logpdf
+            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)}")
@@ -327,6 +329,155 @@ class DistributionFitter:
             raise ValueError(f"Unknown criterion '{criterion}'")
 
 
+@dataclass
+class NullResult:
+    """A statistic, and the same statistic measured under shuffled labels.
+
+    `observed` is the number you found. `null` holds the same measurement taken
+    `n_iter` times on data where the labels were shuffled — data in which, by
+    construction, the label explains nothing. If `observed` sits inside that
+    cloud, a world where nothing is happening produces your finding routinely.
+    """
+
+    observed: float
+    null: np.ndarray
+    n_iter: int
+    seed: Optional[int] = None
+
+    def p_value(self, alternative: str = "two-sided") -> float:
+        """How often a shuffle matched or beat the observed value.
+
+        Args:
+            alternative: `"greater"` counts shuffles at or above `observed`,
+                `"less"` counts shuffles at or below it, and `"two-sided"`
+                (the default) is twice the smaller of the two, capped at 1.
+
+        Both one-sided counts include the observed arrangement itself — it is
+        one of the arrangements the labels could take — so the smallest value
+        this can return is `1 / (n_iter + 1)` rather than zero. With 1000
+        shuffles, "p < 0.001" is the strongest statement available; report it
+        that way rather than as an exact number.
+        """
+        greater = (int(np.sum(self.null >= self.observed)) + 1) / (self.n_iter + 1)
+        less = (int(np.sum(self.null <= self.observed)) + 1) / (self.n_iter + 1)
+
+        if alternative == "greater":
+            return greater
+        if alternative == "less":
+            return less
+        if alternative == "two-sided":
+            return min(1.0, 2 * min(greater, less))
+        raise ValueError(
+            f"Unknown alternative '{alternative}', "
+            "expected 'two-sided', 'greater' or 'less'"
+        )
+
+    @property
+    def quantile(self) -> float:
+        """Where `observed` sits in the null, as a fraction between 0 and 1."""
+        return float(np.mean(self.null < self.observed))
+
+    def __repr__(self) -> str:
+        return (
+            f"NullResult(observed={self.observed:.4g}, "
+            f"null_mean={float(np.mean(self.null)):.4g}, "
+            f"quantile={self.quantile:.3f}, "
+            f"p={self.p_value():.4f}, n_iter={self.n_iter})"
+        )
+
+
+class NullDistribution:
+    """Shuffle the labels, measure again, and see where the real number lands.
+
+    The cheapest honest check in the method (§9.6): it assumes nothing about the
+    shape of the data, needs no table of critical values, and answers in a
+    picture rather than a test. Pair it with `NullPlot` — a student who has seen
+    their finding sitting in the middle of the null does not need a p-value
+    explained.
+
+    The statistic is yours to write. Naming what you are measuring is the
+    thinking part; running it a thousand times is the part worth delegating.
+
+    ```python
+    def gap(frame):
+        means = frame.groupby("is_bot")["length"].mean()
+        return means[True] - means[False]
+
+    result = NullDistribution(gap, n_iter=1000, seed=42).run(data, label="is_bot")
+    ```
+    """
+
+    def __init__(
+        self,
+        statistic: Callable[[pd.DataFrame], float],
+        n_iter: int = 1000,
+        seed: Optional[int] = None,
+    ) -> None:
+        """
+        Args:
+            statistic: Takes a dataframe, returns one number. Called once on the
+                data as given, then once per shuffle.
+            n_iter: Number of shuffles. 1000 is enough to see the shape; go to
+                10_000 when the observed value sits far out in the tail.
+            seed: Passed to `numpy.random.default_rng`. Set it, or the picture
+                changes every time the cell is run.
+        """
+        if n_iter < 1:
+            raise ValueError(f"n_iter must be at least 1, got {n_iter}")
+        self.statistic = statistic
+        self.n_iter = n_iter
+        self.seed = seed
+
+    def run(self, data: pd.DataFrame, label: str) -> NullResult:
+        """Measure `statistic` on `data`, then on `n_iter` shuffles of `label`.
+
+        Shuffling one column breaks the link between it and every other column
+        while leaving both distributions exactly as they were: the labels keep
+        their proportions, the values keep their shape, and only the pairing is
+        destroyed. That is the "nothing is happening" world to compare against.
+
+        Args:
+            data: The frame to measure. It is never modified.
+            label: Column to shuffle — the one whose association with the rest
+                of the frame is in question.
+
+        Returns:
+            A `NullResult` holding the observed value and the shuffled cloud.
+        """
+        if label not in data.columns:
+            raise ValueError(
+                f"Column '{label}' is not in the data; got {list(data.columns)}"
+            )
+
+        observed = float(self.statistic(data))
+        if not np.isfinite(observed):
+            raise ValueError(
+                f"The statistic returned {observed} on the unshuffled data; "
+                "there is nothing to compare a null against."
+            )
+
+        rng = np.random.default_rng(self.seed)
+        values = data[label].to_numpy()
+        shuffled = data.copy()
+
+        null = np.empty(self.n_iter)
+        for i in range(self.n_iter):
+            # A plain array, not a Series: assigning a permuted Series realigns
+            # on the index and puts every label straight back where it started.
+            shuffled[label] = rng.permutation(values)
+            null[i] = float(self.statistic(shuffled))
+
+        if not np.all(np.isfinite(null)):
+            logger.warning(
+                f"{int(np.sum(~np.isfinite(null)))} of {self.n_iter} shuffles gave a "
+                "non-finite statistic; a small group may be emptying under shuffling."
+            )
+
+        return NullResult(
+            observed=observed, null=null, n_iter=self.n_iter, seed=self.seed
+        )
+
+
 def fit_table(results: List[Result]) -> pd.DataFrame:
     """Turn a list of fit results into a ranked dataframe: what a student hands in.
 
@@ -343,8 +494,12 @@ def fit_table(results: List[Result]) -> pd.DataFrame:
                     "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"),
+                    "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,

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

@@ -2,6 +2,7 @@ from abc import ABC, abstractmethod
 from typing import Any, Dict, List, Optional, Type, TypeVar
 
 import pandas as pd
+from loguru import logger
 from tqdm import tqdm
 
 T = TypeVar("T", bound="TransformBase")
@@ -161,6 +162,52 @@ class TimeFeatures(TransformBase):
         return data
 
 
+class RegexFeature(TransformBase):
+    """Add a feature extracted from a text column with a regular expression.
+
+    Three modes, all writing a single new column named by `feature`:
+
+    - `"count"` — how many times the pattern occurs per row (int);
+    - `"has"` — whether it occurs at all (bool);
+    - `"extract"` — the first capture group's text, or NaN where nothing matched.
+      `pattern` must contain exactly one capture group in this mode.
+
+    The new column is `feature`, not `name`: `Pipeline.add(name=...)` already claims
+    `name` for the step, and `TransformBase.__init__` consumes it. Any transform that
+    names an output column has to spell that parameter something else.
+
+    `mode="extract"` reports its own coverage through `loguru`. `count` and `has` fail
+    visibly when a pattern is wrong — a column of all zeros or all False. Extraction
+    fails silently, filling with NaN, so it says out loud how much it matched.
+    """
+
+    def transform(
+        self,
+        data: pd.DataFrame,
+        column: str,
+        pattern: str,
+        feature: str,
+        mode: str = "count",
+    ) -> pd.DataFrame:
+        text = data[column].fillna("")
+        if mode == "count":
+            data[feature] = text.str.count(pattern)
+        elif mode == "has":
+            data[feature] = text.str.contains(pattern, regex=True)
+        elif mode == "extract":
+            data[feature] = text.str.extract(pattern, expand=False)
+            matched = data[feature].notna().sum()
+            total = len(data)
+            share = f"{matched / total:.1%}" if total else "n/a"
+            logger.info(
+                f"{self.name}: extracted '{feature}' from {matched:,}/{total:,} rows "
+                f"({share}); {total - matched:,} rows had no match"
+            )
+        else:
+            raise ValueError(f"mode must be count/has/extract, got {mode!r}")
+        return data
+
+
 class Pipeline:
     """Pipeline for chaining data transformations."""