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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: goad-toolkit
-Version: 0.2.3
+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>

{goad_toolkit-0.2.3 → goad_toolkit-0.2.4}/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.4}/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.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.3 → goad_toolkit-0.2.4}/docs/08-api-reference.md

@@ -139,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.
 
 ---
 
@@ -192,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.
 
 ---
 
@@ -273,6 +287,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 +345,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.4}/pyproject.toml

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

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

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

goad_toolkit-0.2.4/tests/test_distributions.py

@@ -0,0 +1,195 @@
+import numpy as np
+import pytest
+from scipy import stats
+
+from goad_toolkit.analytics import (
+    DistributionFitter,
+    FailedFit,
+    FitResult,
+    KSTestResult,
+    fit_table,
+)
+from goad_toolkit.distributions import DistributionRegistry
+
+
+def test_registries_are_independent():
+    first = DistributionRegistry()
+    second = DistributionRegistry()
+
+    first.register_distribution("pareto", stats.pareto, is_discrete=False, num_params=3)
+
+    assert "pareto" in first.get_names()
+    assert "pareto" not in second.get_names()
+    assert "pareto" not in DistributionRegistry().get_names()
+
+
+def test_registry_ships_the_default_families():
+    names = DistributionRegistry().get_names()
+
+    assert names == [
+        "norm",
+        "uniform",
+        "lognorm",
+        "poisson",
+        "exponential",
+        "skewnorm",
+        "gamma",
+        "weibull",
+        "bernoulli",
+        "binomial",
+        "nbinom",
+        "beta",
+    ]
+
+
+def test_pareto_is_not_a_default_family():
+    # Lesson 4 has the student register pareto themselves as the extensibility
+    # exercise; shipping it by default would remove the point of that exercise.
+    assert "pareto" not in DistributionRegistry().get_names()
+
+
+def test_unknown_distribution_raises():
+    with pytest.raises(ValueError, match="not found in registry"):
+        DistributionRegistry().get_distribution("pareto")
+
+
+def test_fitter_uses_a_private_registry_by_default():
+    fitter = DistributionFitter()
+    DistributionRegistry().register_distribution(
+        "pareto", stats.pareto, is_discrete=False, num_params=3
+    )
+
+    assert "pareto" not in fitter.registry
+
+
+def test_fitter_accepts_a_registry():
+    registry = DistributionRegistry()
+    registry.distributions = {}
+    registry.register_distribution("norm", stats.norm, is_discrete=False, num_params=2)
+
+    fitter = DistributionFitter(registry)
+
+    assert fitter.registry == ["norm"]
+
+
+def test_fit_with_a_single_family_registry():
+    registry = DistributionRegistry()
+    registry.distributions = {}
+    registry.register_distribution("norm", stats.norm, is_discrete=False, num_params=2)
+    rng = np.random.default_rng(42)
+    data = rng.normal(loc=3.0, scale=2.0, size=500)
+
+    results = DistributionFitter(registry).fit(data, discrete=False)
+
+    assert len(results) == 1
+    fit = results[0]
+    assert isinstance(fit, FitResult)
+    assert fit.best_likelihood
+    assert fit.params[0] == pytest.approx(3.0, abs=0.5)
+
+
+def test_bernoulli_fits_a_small_p():
+    # A single-parameter discrete bound used to floor at 0.1, which is a sane
+    # floor for a count-scale rate (poisson's lambda) but clips a genuinely
+    # small probability (bernoulli's p) to the floor instead of the true value.
+    registry = DistributionRegistry()
+    registry.distributions = {}
+    registry.register_distribution(
+        "bernoulli", stats.bernoulli, is_discrete=True, num_params=1
+    )
+    rng = np.random.default_rng(7)
+    data = stats.bernoulli(p=0.05).rvs(3000, random_state=rng)
+
+    results = DistributionFitter(registry).fit(data, discrete=True)
+
+    fit = results[0]
+    assert isinstance(fit, FitResult)
+    assert fit.params[0] == pytest.approx(0.05, abs=0.02)
+
+
+def test_loglikelihood_is_finite_for_discrete_families():
+    # dist_obj.dist.logpdf does not exist on discrete scipy distributions
+    # (they have logpmf instead), so every discrete fit's log_likelihood used
+    # to fall back to -inf regardless of fit quality.
+    registry = DistributionRegistry()
+    rng = np.random.default_rng(3)
+    data = stats.poisson(mu=4.0).rvs(500, random_state=rng)
+
+    results = DistributionFitter(registry).fit(data, discrete=True)
+
+    successes = [r for r in results if isinstance(r, FitResult)]
+    assert successes, "expected at least one discrete fit to succeed"
+    for fit in successes:
+        assert fit.log_likelihood is not None
+        assert fit.log_likelihood > float("-inf")
+
+
+def test_best_likelihood_marked_even_when_no_fit_clears_the_ks_threshold():
+    # _mark_best_fits used to require both a likelihood winner AND a ks winner
+    # before marking either — so a best_likelihood candidate went unmarked
+    # whenever every fit's ks p-value was exactly 0 (routine for discrete
+    # families on a large, tied sample).
+    fitter = DistributionFitter()
+    worse = FitResult(
+        distribution="a",
+        dist_object=None,
+        params=(1.0,),
+        frozen_dist=None,
+        log_likelihood=-100.0,
+        kstest=KSTestResult(statistic=0.5, p_value=0.0),
+    )
+    better = FitResult(
+        distribution="b",
+        dist_object=None,
+        params=(1.0,),
+        frozen_dist=None,
+        log_likelihood=-50.0,
+        kstest=KSTestResult(statistic=0.5, p_value=0.0),
+    )
+
+    fitter._mark_best_fits([worse, better], criterion="combined")
+
+    assert better.best_likelihood is True
+    assert worse.best_likelihood is False
+    assert better.best_ks is None or better.best_ks is False
+    assert worse.best_ks is None or worse.best_ks is False
+
+
+def test_mark_best_fits_rejects_unknown_criterion():
+    fitter = DistributionFitter()
+    with pytest.raises(ValueError, match="Unknown criterion"):
+        fitter._mark_best_fits([], criterion="nonsense")
+
+
+def test_fit_table_ranks_by_loglikelihood_and_sorts_failures_last():
+    results = [
+        FitResult(
+            distribution="worse",
+            dist_object=None,
+            params=(1.0, 2.0),
+            frozen_dist=None,
+            log_likelihood=-50.0,
+            kstest=KSTestResult(statistic=0.2, p_value=0.3),
+            best_likelihood=False,
+            best_ks=False,
+        ),
+        FailedFit(distribution="broken", message="optimizer did not converge"),
+        FitResult(
+            distribution="best",
+            dist_object=None,
+            params=(3.0,),
+            frozen_dist=None,
+            log_likelihood=-10.0,
+            kstest=KSTestResult(statistic=0.05, p_value=0.9),
+            best_likelihood=True,
+            best_ks=True,
+        ),
+    ]
+
+    table = fit_table(results)
+
+    assert list(table["distribution"]) == ["best", "worse", "broken"]
+    assert table.loc[0, "best_likelihood"]
+    assert table.loc[0, "best_ks"]
+    assert table.loc[2, "message"] == "optimizer did not converge"
+    assert np.isnan(table.loc[2, "log_likelihood"])

{goad_toolkit-0.2.3 → goad_toolkit-0.2.4}/tests/test_visualizer.py

@@ -2,9 +2,11 @@ import matplotlib
 
 matplotlib.use("Agg")
 
+import numpy as np  # noqa: E402
 import matplotlib.pyplot as plt  # noqa: E402
 import pandas as pd  # noqa: E402
 import pytest  # noqa: E402
+from scipy import stats  # noqa: E402
 
 from goad_toolkit.visualizer import (  # noqa: E402
     ACFPlot,
@@ -12,8 +14,10 @@ from goad_toolkit.visualizer import (  # noqa: E402
     ComparePlot,
     ComparePlotDate,
     DecomposePlot,
+    ECDFPlot,
     LinePlot,
     PlotSettings,
+    QQPlot,
     ResidualPlot,
     VerticalDate,
 )
@@ -147,3 +151,50 @@ def test_acf_plot_rejects_missing_values():
 
     with pytest.raises(ValueError, match="missing values"):
         ACFPlot(PlotSettings()).plot(data=series, nlags=2)
+
+
+def test_qq_plot_points_fall_near_the_reference_line_for_a_correct_fit():
+    rng = np.random.default_rng(11)
+    data = rng.normal(loc=5.0, scale=2.0, size=500)
+
+    fig, ax = QQPlot(PlotSettings()).plot(data=data, distribution=stats.norm(loc=5.0, scale=2.0))
+
+    assert fig is not None
+    offsets = ax.collections[0].get_offsets()
+    theoretical, sample = offsets[:, 0], offsets[:, 1]
+    assert np.corrcoef(theoretical, sample)[0, 1] > 0.99
+    # A y=x reference line is drawn alongside the scatter.
+    assert len(ax.lines) == 1
+
+
+def test_qq_plot_rejects_empty_data():
+    with pytest.raises(ValueError, match="no data"):
+        QQPlot(PlotSettings()).plot(data=np.array([]), distribution=stats.norm())
+
+
+def test_ecdf_plot_single_sample_is_a_valid_step_curve():
+    data = np.array([1, 2, 2, 3, 5])
+
+    fig, ax = ECDFPlot(PlotSettings()).plot(data=data)
+
+    assert fig is not None
+    line = ax.lines[0]
+    y = line.get_ydata()
+    assert y[-1] == pytest.approx(1.0)
+    assert np.all(np.diff(y) >= 0)  # monotonically non-decreasing
+
+
+def test_ecdf_plot_compares_two_samples():
+    lower = np.array([1, 2, 3, 4, 5])
+    higher = lower + 10
+
+    fig, ax = ECDFPlot(PlotSettings()).plot(data=lower, compare=higher, label="a", compare_label="b")
+
+    assert len(ax.lines) == 2
+    legend_labels = [t.get_text() for t in ax.get_legend().get_texts()]
+    assert legend_labels == ["a", "b"]
+
+
+def test_ecdf_plot_rejects_empty_data():
+    with pytest.raises(ValueError, match="no data"):
+        ECDFPlot(PlotSettings()).plot(data=np.array([]))

{goad_toolkit-0.2.3 → goad_toolkit-0.2.4}/uv.lock

@@ -383,7 +383,7 @@ wheels = [
 
 [[package]]
 name = "goad-toolkit"
-version = "0.2.2"
+version = "0.2.4"
 source = { editable = "." }
 dependencies = [
     { name = "loguru" },

goad_toolkit-0.2.3/tests/test_distributions.py

@@ -1,72 +0,0 @@
-import numpy as np
-import pytest
-from scipy import stats
-
-from goad_toolkit.analytics import DistributionFitter, FitResult
-from goad_toolkit.distributions import DistributionRegistry
-
-
-def test_registries_are_independent():
-    first = DistributionRegistry()
-    second = DistributionRegistry()
-
-    first.register_distribution("pareto", stats.pareto, is_discrete=False, num_params=3)
-
-    assert "pareto" in first.get_names()
-    assert "pareto" not in second.get_names()
-    assert "pareto" not in DistributionRegistry().get_names()
-
-
-def test_registry_ships_the_default_families():
-    names = DistributionRegistry().get_names()
-
-    assert names == [
-        "norm",
-        "uniform",
-        "lognorm",
-        "poisson",
-        "exponential",
-        "skewnorm",
-        "gamma",
-        "weibull",
-    ]
-
-
-def test_unknown_distribution_raises():
-    with pytest.raises(ValueError, match="not found in registry"):
-        DistributionRegistry().get_distribution("pareto")
-
-
-def test_fitter_uses_a_private_registry_by_default():
-    fitter = DistributionFitter()
-    DistributionRegistry().register_distribution(
-        "pareto", stats.pareto, is_discrete=False, num_params=3
-    )
-
-    assert "pareto" not in fitter.registry
-
-
-def test_fitter_accepts_a_registry():
-    registry = DistributionRegistry()
-    registry.distributions = {}
-    registry.register_distribution("norm", stats.norm, is_discrete=False, num_params=2)
-
-    fitter = DistributionFitter(registry)
-
-    assert fitter.registry == ["norm"]
-
-
-def test_fit_with_a_single_family_registry():
-    registry = DistributionRegistry()
-    registry.distributions = {}
-    registry.register_distribution("norm", stats.norm, is_discrete=False, num_params=2)
-    rng = np.random.default_rng(42)
-    data = rng.normal(loc=3.0, scale=2.0, size=500)
-
-    results = DistributionFitter(registry).fit(data, discrete=False)
-
-    assert len(results) == 1
-    fit = results[0]
-    assert isinstance(fit, FitResult)
-    assert fit.best_likelihood
-    assert fit.params[0] == pytest.approx(3.0, abs=0.5)