goad-toolkit 0.2.3__tar.gz → 0.2.5__tar.gz

{goad_toolkit-0.2.3 → goad_toolkit-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: goad-toolkit
-Version: 0.2.3
+Version: 0.2.5
 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.3 → goad_toolkit-0.2.5}/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.3 → goad_toolkit-0.2.5}/docs/03-plot-composition.md

@@ -156,6 +156,8 @@ step 3.
 | `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
@@ -166,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:

{goad_toolkit-0.2.3 → goad_toolkit-0.2.5}/docs/04-five-families.md

@@ -116,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.3 → goad_toolkit-0.2.5}/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.3 → goad_toolkit-0.2.5}/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"
@@ -139,8 +146,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.
 
 ---
 
@@ -192,10 +202,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.
 
 ---
 
@@ -273,6 +294,8 @@ class BasePlot(ABC):
 | `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):
@@ -329,6 +352,12 @@ 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`.
+- `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.3 → goad_toolkit-0.2.5}/pyproject.toml

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

{goad_toolkit-0.2.3 → goad_toolkit-0.2.5}/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.3 → goad_toolkit-0.2.5}/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."""
 

{goad_toolkit-0.2.3 → goad_toolkit-0.2.5}/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."""

{goad_toolkit-0.2.3 → goad_toolkit-0.2.5}/src/goad_toolkit/visualizer.py

@@ -505,6 +505,130 @@ class DistPlot(BasePlot):
             return x
 
 
+class QQPlot(BasePlot):
+    """Quantile-quantile plot: is this fit believable, not just which one wins.
+
+    A histogram with a pdf overlaid (PlotFits, DistPlot) is dominated by the bulk
+    of the data, which is exactly where distributions look most alike. A qq-plot
+    puts sorted data against the fitted distribution's theoretical quantiles, so a
+    systematic deviation in a tail — where families actually differ — shows up as
+    points bending away from the reference line instead of as a few stray bars.
+    """
+
+    def build(
+        self,
+        data: np.ndarray,
+        distribution: Any,
+        color: str = "steelblue",
+        line_color: str = "black",
+        alpha: float = 0.6,
+        **kwargs,
+    ) -> Tuple[Any, Any]:
+        """
+        Plot sample quantiles against a distribution's theoretical quantiles.
+
+        Parameters:
+        -----------
+        data : np.ndarray
+            Sample to plot
+        distribution : scipy.stats distribution
+            Fitted (frozen) distribution to compare against; must have a ppf method
+        color : str
+            Colour of the quantile points
+        line_color : str
+            Colour of the y=x reference line
+        alpha : float
+            Transparency of the quantile points
+        **kwargs : Additional keyword arguments passed to ax.scatter
+
+        Returns:
+        --------
+        fig, ax : The created figure and axes
+        """
+        if self.ax is None:
+            raise ValueError("No axes available for plotting")
+
+        sample = np.sort(np.asarray(data))
+        n = len(sample)
+        if n == 0:
+            raise ValueError("QQPlot got no data to plot")
+
+        # Filliben-style plotting positions: (i - 0.5) / n avoids ppf(0) / ppf(1),
+        # which are -inf/inf for most families.
+        probabilities = (np.arange(1, n + 1) - 0.5) / n
+        theoretical = distribution.ppf(probabilities)
+
+        self.ax.scatter(theoretical, sample, color=color, alpha=alpha, **kwargs)
+
+        lo = min(np.min(theoretical), np.min(sample))
+        hi = max(np.max(theoretical), np.max(sample))
+        self.ax.plot([lo, hi], [lo, hi], color=line_color, linewidth=1, linestyle="--")
+
+        return self.fig, self.ax
+
+
+class ECDFPlot(BasePlot):
+    """Empirical CDF: bin-free, and the right tool for comparing two samples.
+
+    A histogram's shape depends on its bin width; an ECDF has no such knob, uses
+    every point, and puts two samples on directly comparable axes without either
+    one's binning choice hiding or manufacturing a difference.
+    """
+
+    def build(
+        self,
+        data: np.ndarray,
+        compare: Optional[np.ndarray] = None,
+        label: str = "data",
+        compare_label: str = "compare",
+        color: str = "steelblue",
+        compare_color: str = "crimson",
+        **kwargs,
+    ) -> Tuple[Any, Any]:
+        """
+        Plot the empirical CDF of `data`, and optionally a second sample over it.
+
+        Parameters:
+        -----------
+        data : np.ndarray
+            Sample to plot
+        compare : Optional[np.ndarray]
+            A second sample to overlay, for a direct two-sample comparison
+        label : str
+            Legend label for `data`
+        compare_label : str
+            Legend label for `compare`
+        color : str
+            Colour of the `data` step curve
+        compare_color : str
+            Colour of the `compare` step curve
+        **kwargs : Additional keyword arguments passed to ax.step
+
+        Returns:
+        --------
+        fig, ax : The created figure and axes
+        """
+        if self.ax is None:
+            raise ValueError("No axes available for plotting")
+        ax = self.ax
+
+        self._draw(ax, np.asarray(data), color=color, label=label, **kwargs)
+        if compare is not None:
+            self._draw(ax, np.asarray(compare), color=compare_color, label=compare_label, **kwargs)
+
+        if compare is not None or label:
+            ax.legend()
+
+        return self.fig, self.ax
+
+    def _draw(self, ax: Axes, values: np.ndarray, color: str, label: Optional[str], **kwargs) -> None:
+        if len(values) == 0:
+            raise ValueError("ECDFPlot got no data to plot")
+        sorted_values = np.sort(values)
+        y = np.arange(1, len(sorted_values) + 1) / len(sorted_values)
+        ax.step(sorted_values, y, where="post", color=color, label=label, **kwargs)
+
+
 @dataclass
 class FitPlotSettings:
     """Settings for distribution fit plots."""