pycorpdiff 0.1.0a0__py3-none-any.whl

pycorpdiff/temporal/bocpd.py

@@ -0,0 +1,233 @@
+"""Bayesian online changepoint detection (Adams & MacKay 2007).
+
+Where :func:`detect_changepoints` runs PELT *offline* — needing the full
+series and returning MAP locations after the fact — BOCPD runs *online*:
+at each new observation it returns the posterior distribution over *run
+length*, where the run length is the number of periods since the last
+changepoint. The two most actionable summaries:
+
+- **MAP run length** at time *t*: the most-probable number of periods
+  since the last changepoint. Drops sharply at changepoints, grows
+  steadily during stable regimes.
+- **Changepoint probability** P(*r* < ``threshold`` | data through *t*):
+  posterior probability that a changepoint occurred within the last
+  ``threshold`` steps. Useful for live monitoring.
+
+Observation model: Gaussian with a Normal-Inverse-Gamma conjugate
+prior over (mean, variance). The predictive distribution is Student's
+*t*, computed analytically.
+
+Reference
+---------
+Adams, R. P., & MacKay, D. J. C. (2007). Bayesian online changepoint
+detection. arXiv:0710.3742.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+import pandas as pd
+from scipy.stats import t as student_t
+
+from ..results import _table_to_html, _table_to_json
+
+if TYPE_CHECKING:
+    import altair as alt
+
+
+@dataclass(frozen=True)
+class BocpdResult:
+    """Output of :func:`bocpd`.
+
+    The full ``run_length_posterior`` matrix is retained for plotting
+    (the canonical BOCPD diagnostic is a heatmap of this matrix). The
+    derived summaries — ``map_run_length`` and ``cp_probability`` — are
+    the actionable per-step signals.
+    """
+
+    series: pd.Series
+    run_length_posterior: np.ndarray  # shape (T, max_r+1)
+    map_run_length: pd.Series  # length T, indexed like series
+    cp_probability: pd.Series  # length T, indexed like series
+    hazard: float
+    params: dict[str, Any] = field(default_factory=dict)
+
+    def to_df(self) -> pd.DataFrame:
+        """Return a flat per-step table (period, value, map_run_length, cp_probability)."""
+        return pd.DataFrame(
+            {
+                "period": self.series.index,
+                "value": self.series.to_numpy(dtype=float),
+                "map_run_length": self.map_run_length.to_numpy(dtype=int),
+                "cp_probability": self.cp_probability.to_numpy(dtype=float),
+            }
+        )
+
+    def to_html(self, path: str | Path | None = None, **kw: Any) -> str:
+        return _table_to_html(self.to_df(), path, **kw)
+
+    def to_json(self, path: str | Path | None = None, **kw: Any) -> str:
+        return _table_to_json(self.to_df(), path, **kw)
+
+    def detected_changepoints(self, *, threshold: int = 3) -> pd.DataFrame:
+        """Periods where the MAP run length dropped below ``threshold``.
+
+        Returns
+        -------
+        pandas.DataFrame
+            Columns: ``period``, ``map_run_length``, ``cp_probability``.
+        """
+        df = self.to_df()
+        flagged = df[df["map_run_length"] <= threshold].copy()
+        return flagged.reset_index(drop=True)
+
+    def plot(self, **kw: Any) -> alt.Chart:
+        from ..viz.bocpd import bocpd_plot
+
+        return bocpd_plot(self, **kw)
+
+    def summary(self) -> str:
+        detected = self.detected_changepoints(threshold=3)
+        return (
+            f"BocpdResult(hazard={self.hazard}, T={len(self.series)}, "
+            f"detected={len(detected)})"
+        )
+
+
+def bocpd(
+    series: pd.Series,
+    *,
+    hazard: float = 0.01,
+    mu_0: float | None = None,
+    kappa_0: float = 1.0,
+    alpha_0: float = 1.0,
+    beta_0: float | None = None,
+    max_run_length: int | None = None,
+) -> BocpdResult:
+    """Bayesian Online Changepoint Detection.
+
+    Parameters
+    ----------
+    series
+        Time-indexed series of scalar observations.
+    hazard
+        Constant hazard rate — probability of a changepoint at any
+        given step. Equivalent to an expected mean run length of
+        ``1/hazard``. ``0.01`` (default) → expect a regime change every
+        ~100 periods. For monthly data, ``hazard=1/24`` → "every 2
+        years".
+    mu_0
+        Prior mean. Defaults to the series mean, but for serious work
+        pass a sensible scale-anchored prior (e.g. zero for centered
+        rates).
+    kappa_0
+        Prior pseudo-count on the mean. ``1.0`` is weakly informative.
+    alpha_0, beta_0
+        Inverse-Gamma hyperparameters on the variance. ``beta_0``
+        defaults to a small data-derived value; override if you have
+        scale information from outside the data window.
+    max_run_length
+        Truncate the run-length state at this many steps. Defaults to
+        the full series length. Setting it (e.g. ``200``) bounds the
+        per-step cost at O(T·max_run_length) for very long series.
+
+    Returns
+    -------
+    :class:`BocpdResult`
+    """
+    if hazard <= 0 or hazard >= 1:
+        raise ValueError(f"hazard must be in (0, 1); got {hazard}")
+    if kappa_0 <= 0 or alpha_0 <= 0:
+        raise ValueError(
+            f"kappa_0 and alpha_0 must be positive; got {kappa_0}, {alpha_0}"
+        )
+
+    y = series.to_numpy(dtype=float)
+    n = len(y)
+    if n < 2:
+        raise ValueError(f"need at least 2 observations; got {n}")
+
+    if mu_0 is None:
+        mu_0 = float(np.mean(y))
+    if beta_0 is None:
+        # Weakly informative: encode the data's order-of-magnitude
+        # variance so the t-distribution scale is sensible.
+        beta_0 = max(float(np.var(y, ddof=1)) * (alpha_0 - 0.5) if alpha_0 > 0.5 else 0.01, 1e-6)
+    if beta_0 <= 0:
+        raise ValueError(f"beta_0 must be positive; got {beta_0}")
+
+    max_r = n if max_run_length is None else min(n, int(max_run_length))
+
+    # Posterior matrix and per-run-length sufficient stats.
+    posterior = np.zeros((n + 1, max_r + 1))
+    posterior[0, 0] = 1.0
+    mu_vec = np.array([mu_0], dtype=float)
+    kappa_vec = np.array([kappa_0], dtype=float)
+    alpha_vec = np.array([alpha_0], dtype=float)
+    beta_vec = np.array([beta_0], dtype=float)
+
+    for t in range(n):
+        x = y[t]
+
+        # Truncate state at max_r entries.
+        if len(mu_vec) > max_r:
+            mu_vec = mu_vec[:max_r]
+            kappa_vec = kappa_vec[:max_r]
+            alpha_vec = alpha_vec[:max_r]
+            beta_vec = beta_vec[:max_r]
+        n_r = len(mu_vec)
+
+        # 1. Predictive probability for x under each run length.
+        scale_vec = np.sqrt(beta_vec * (kappa_vec + 1.0) / (alpha_vec * kappa_vec))
+        df_vec = 2.0 * alpha_vec
+        pi_vec = student_t.pdf(x, df=df_vec, loc=mu_vec, scale=scale_vec)
+
+        # 2. Growth mass (no changepoint) — shifts up by one r.
+        growth = posterior[t, :n_r] * pi_vec * (1.0 - hazard)
+        # 3. Changepoint mass (everything collapses to r=0).
+        cp_mass = float((posterior[t, :n_r] * pi_vec * hazard).sum())
+
+        next_len = min(n_r + 1, max_r + 1)
+        posterior[t + 1, 0] = cp_mass
+        if next_len > 1:
+            posterior[t + 1, 1:next_len] = growth[: next_len - 1]
+        total = posterior[t + 1, :].sum()
+        if total > 0:
+            posterior[t + 1, :] /= total
+
+        # 4. Update sufficient statistics — shift up with prior in slot 0.
+        new_mu = (kappa_vec * mu_vec + x) / (kappa_vec + 1.0)
+        new_kappa = kappa_vec + 1.0
+        new_alpha = alpha_vec + 0.5
+        new_beta = beta_vec + (kappa_vec * (x - mu_vec) ** 2) / (
+            2.0 * (kappa_vec + 1.0)
+        )
+        mu_vec = np.concatenate([[mu_0], new_mu])
+        kappa_vec = np.concatenate([[kappa_0], new_kappa])
+        alpha_vec = np.concatenate([[alpha_0], new_alpha])
+        beta_vec = np.concatenate([[beta_0], new_beta])
+
+    posterior_obs = posterior[1:, : max_r + 1]
+    map_r = posterior_obs.argmax(axis=1).astype(int)
+    cp_prob = posterior_obs[:, 0]
+
+    return BocpdResult(
+        series=series,
+        run_length_posterior=posterior_obs,
+        map_run_length=pd.Series(map_r, index=series.index, name="map_run_length"),
+        cp_probability=pd.Series(
+            cp_prob, index=series.index, name="cp_probability"
+        ),
+        hazard=hazard,
+        params={
+            "mu_0": mu_0,
+            "kappa_0": kappa_0,
+            "alpha_0": alpha_0,
+            "beta_0": beta_0,
+            "max_run_length": max_r,
+        },
+    )

pycorpdiff/temporal/causal_impact.py

@@ -0,0 +1,293 @@
+"""Bayesian counterfactual causal impact (Brodersen et al. 2015).
+
+The :func:`interrupted_time_series` module answers "is there a step
+discontinuity at this known event?" via segmented OLS. The harder —
+and more interesting — question is "what *would* the trajectory have
+looked like *without* the event?" That's the counterfactual, and the
+gap between observed reality and counterfactual prediction is the
+causal effect of the event.
+
+Method: Bayesian structural time series (BSTS) — a state-space model
+with a local linear trend fit on the pre-event window, then projected
+forward as the counterfactual for the post-event window. Implemented
+via :class:`statsmodels.tsa.UnobservedComponents`. The credible
+intervals on the pointwise and cumulative effects come from Monte
+Carlo simulation against the joint posterior of the state-space
+filter — anchored at the end of the pre-event training data and rolled
+forward through the post-event horizon.
+
+Reference
+---------
+Brodersen, K. H., Gallusser, F., Koehler, J., Remy, N., & Scott, S. L.
+(2015). Inferring causal impact using Bayesian structural time-series
+models. *Annals of Applied Statistics*, 9(1), 247-274.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+import pandas as pd
+
+from ..results import _table_to_html, _table_to_json
+
+if TYPE_CHECKING:
+    import altair as alt
+
+
+@dataclass(frozen=True)
+class CausalImpactResult:
+    """Counterfactual causal-impact analysis around a known event.
+
+    Tables (all period-indexed, columns ``period``, ``observed``,
+    ``counterfactual``, ``counterfactual_lower``, ``counterfactual_upper``,
+    plus the same for the pointwise and cumulative effects).
+
+    Summary scalars live in :attr:`metrics` as a dict keyed by the
+    standard CausalImpact reporting set: avg effect, absolute effect,
+    relative effect, posterior probability of no effect.
+    """
+
+    target: str
+    event_date: pd.Timestamp
+    table: pd.DataFrame
+    metrics: dict[str, float] = field(default_factory=dict)
+    level: float = 0.95
+    n_pre: int = 0
+    n_post: int = 0
+    params: dict[str, Any] = field(default_factory=dict)
+
+    def to_df(self) -> pd.DataFrame:
+        return self.table.copy()
+
+    def to_html(self, path: str | Path | None = None, **kw: Any) -> str:
+        return _table_to_html(self.table, path, **kw)
+
+    def to_json(self, path: str | Path | None = None, **kw: Any) -> str:
+        return _table_to_json(self.table, path, **kw)
+
+    def plot(self, **kw: Any) -> alt.Chart:
+        from ..viz.causal_impact import causal_impact_plot
+
+        return causal_impact_plot(self, **kw)
+
+    def summary(self) -> str:
+        import math
+
+        m = self.metrics
+        avg = m.get("avg_effect", float("nan"))
+        cum = m.get("cumulative_effect", float("nan"))
+        rel = m.get("relative_effect", float("nan"))
+        ci_lo = m.get("avg_effect_lower", float("nan"))
+        ci_hi = m.get("avg_effect_upper", float("nan"))
+        p = m.get("posterior_prob_no_effect", float("nan"))
+        rel_str = (
+            "n/a (counterfactual ≈ 0)" if math.isnan(rel) else f"{rel * 100:+.1f}%"
+        )
+        return (
+            f"CausalImpactResult(target={self.target!r}, "
+            f"event={self.event_date.date()}, pre={self.n_pre}, post={self.n_post})\n"
+            f"  avg effect:        {avg:+.4f} per period  "
+            f"({int(self.level * 100)}% CrI [{ci_lo:+.4f}, {ci_hi:+.4f}])\n"
+            f"  cumulative effect: {cum:+.4f}\n"
+            f"  relative effect:   {rel_str} vs counterfactual mean\n"
+            f"  P(no effect):      {p:.3f}"
+        )
+
+
+def causal_impact(
+    series: pd.Series,
+    event_date: str | pd.Period | pd.Timestamp,
+    *,
+    level: float = 0.95,
+    n_samples: int = 1000,
+    seed: int | None = 0,
+    model: str = "local linear trend",
+) -> CausalImpactResult:
+    """Counterfactual causal impact of an event on a time series.
+
+    Fits a Bayesian structural time-series model on the pre-event
+    portion of ``series`` and projects it forward through the
+    post-event window as the counterfactual "what would have happened
+    without the event". Observed minus counterfactual is the causal
+    effect, with credible intervals from Monte Carlo simulation
+    against the joint state-space posterior.
+
+    Parameters
+    ----------
+    series
+        Period-indexed time series of values (e.g. relative
+        frequencies from :meth:`TemporalTrajectory.over_time`).
+    event_date
+        Where to place the intervention. Anything pandas can compare
+        to the series index.
+    level
+        Credible-interval level. ``0.95`` → 95% CrI on every band.
+    n_samples
+        Number of Monte Carlo paths to sample for the pointwise +
+        cumulative CIs. 1000 is the conventional default and runs in
+        well under a second on typical CL series.
+    seed
+        RNG seed for reproducibility.
+    model
+        Trend specification passed to
+        :class:`statsmodels.tsa.UnobservedComponents` — usually
+        ``"local linear trend"`` (level + slope) or ``"local level"``.
+
+    Returns
+    -------
+    :class:`CausalImpactResult`
+    """
+    try:
+        import statsmodels.api as sm
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "causal_impact requires statsmodels. "
+            "Install with: pip install 'pycorpdiff[temporal]'"
+        ) from exc
+
+    if not 0 < level < 1:
+        raise ValueError(f"level must be in (0, 1); got {level}")
+    if n_samples < 100:
+        raise ValueError(f"n_samples must be >= 100; got {n_samples}")
+
+    # Period → Timestamp index so the state-space model can use the
+    # inferred frequency for forward extension.
+    work = series.copy()
+    if isinstance(work.index, pd.PeriodIndex):
+        work.index = work.index.to_timestamp()
+    inferred = getattr(work.index, "inferred_freq", None)
+    if inferred is not None and isinstance(work.index, pd.DatetimeIndex):
+        # Rebuild a frequency-tagged DatetimeIndex without trying to mutate
+        # the read-only ``.freq`` attribute. statsmodels picks up the freq
+        # from this for the forecast horizon.
+        work.index = pd.DatetimeIndex(work.index, freq=inferred)
+
+    event_ts = _coerce_event(event_date, work)
+
+    pre_mask = np.asarray(work.index < event_ts)
+    post_mask = ~pre_mask
+    if int(pre_mask.sum()) < 4:
+        raise ValueError(
+            f"need at least 4 pre-event observations; got {int(pre_mask.sum())} "
+            f"(event_date={event_date!r})"
+        )
+    if int(post_mask.sum()) < 1:
+        raise ValueError(
+            f"need at least 1 post-event observation; event_date={event_date!r} "
+            "is at or after the last period"
+        )
+
+    pre = work[pre_mask]
+    post = work[post_mask]
+
+    # Fit BSTS on the pre-event window.
+    uc = sm.tsa.UnobservedComponents(pre, level=model)
+    fit = uc.fit(disp=False)
+
+    # Counterfactual point forecast + marginal CI from get_forecast.
+    h = len(post)
+    fc = fit.get_forecast(steps=h)
+    cf_mean = np.asarray(fc.predicted_mean, dtype=float)
+    cf_ci = np.asarray(fc.conf_int(alpha=1.0 - level), dtype=float)
+    cf_lower = cf_ci[:, 0]
+    cf_upper = cf_ci[:, 1]
+
+    # Monte Carlo against the joint posterior for the cumulative + pointwise
+    # effect bands — anchored at the end of the pre-event filter state.
+    sim = fit.simulate(
+        nsimulations=h,
+        repetitions=int(n_samples),
+        anchor="end",
+        random_state=seed,
+    )
+    paths = sim.to_numpy() if isinstance(sim, pd.DataFrame) else np.asarray(sim)
+    # statsmodels returns shape (h, repetitions); transpose to (N, h).
+    paths = paths.T if paths.shape == (h, n_samples) else paths
+
+    obs_arr = post.to_numpy(dtype=float)
+    pointwise_paths = obs_arr[None, :] - paths
+    cumulative_paths = np.cumsum(pointwise_paths, axis=1)
+
+    alpha = 1.0 - level
+    lo_q, hi_q = alpha / 2.0, 1.0 - alpha / 2.0
+    pw_lower = np.quantile(pointwise_paths, lo_q, axis=0)
+    pw_upper = np.quantile(pointwise_paths, hi_q, axis=0)
+    cum_mean = cumulative_paths.mean(axis=0)
+    cum_lower = np.quantile(cumulative_paths, lo_q, axis=0)
+    cum_upper = np.quantile(cumulative_paths, hi_q, axis=0)
+    pw_mean = obs_arr - cf_mean
+
+    # Summary scalars — Brodersen "average effect" is over the post window.
+    avg_effect = float(pw_mean.mean())
+    avg_lower = float(np.quantile(pointwise_paths.mean(axis=1), lo_q))
+    avg_upper = float(np.quantile(pointwise_paths.mean(axis=1), hi_q))
+    cf_mean_avg = float(cf_mean.mean())
+    relative_effect = (
+        avg_effect / cf_mean_avg if abs(cf_mean_avg) > 1e-12 else float("nan")
+    )
+    # Posterior probability of no effect: fraction of paths where the avg
+    # effect crosses zero — two-tailed.
+    avg_effect_per_path = pointwise_paths.mean(axis=1)
+    if avg_effect >= 0:
+        p_no_effect = float((avg_effect_per_path <= 0).mean()) * 2.0
+    else:
+        p_no_effect = float((avg_effect_per_path >= 0).mean()) * 2.0
+    p_no_effect = min(1.0, max(0.0, p_no_effect))
+
+    # Build the long table — one row per post-event period. Use the
+    # original series' index so callers see Period objects if that's
+    # what they passed in.
+    if isinstance(series.index, pd.PeriodIndex):
+        periods_out: pd.Index = series.index[post_mask]
+    else:
+        periods_out = work.index[post_mask]
+    table = pd.DataFrame(
+        {
+            "period": periods_out,
+            "observed": obs_arr,
+            "counterfactual": cf_mean,
+            "counterfactual_lower": cf_lower,
+            "counterfactual_upper": cf_upper,
+            "pointwise_effect": pw_mean,
+            "pointwise_lower": pw_lower,
+            "pointwise_upper": pw_upper,
+            "cumulative_effect": cum_mean,
+            "cumulative_lower": cum_lower,
+            "cumulative_upper": cum_upper,
+        }
+    )
+
+    metrics = {
+        "avg_effect": avg_effect,
+        "avg_effect_lower": avg_lower,
+        "avg_effect_upper": avg_upper,
+        "cumulative_effect": float(cum_mean[-1]),
+        "cumulative_effect_lower": float(cum_lower[-1]),
+        "cumulative_effect_upper": float(cum_upper[-1]),
+        "relative_effect": relative_effect,
+        "counterfactual_mean": cf_mean_avg,
+        "posterior_prob_no_effect": p_no_effect,
+    }
+    return CausalImpactResult(
+        target="",  # filled in by the caller — TemporalTrajectory knows the name
+        event_date=event_ts,
+        table=table,
+        metrics=metrics,
+        level=level,
+        n_pre=int(pre_mask.sum()),
+        n_post=int(post_mask.sum()),
+        params={"model": model, "n_samples": n_samples, "seed": seed},
+    )
+
+
+def _coerce_event(event: object, series: pd.Series) -> pd.Timestamp:
+    """Coerce an event-date argument to a Timestamp aligned with the series."""
+    if isinstance(event, pd.Timestamp):
+        return event
+    if isinstance(event, pd.Period):
+        return pd.Timestamp(str(event))
+    return pd.Timestamp(str(event))

pycorpdiff/temporal/changepoint.py

@@ -0,0 +1,92 @@
+"""Changepoint detection on temporal frequency / similarity series.
+
+Wraps the ``ruptures`` library; importable only when the ``temporal``
+extra is installed.
+
+References
+----------
+Truong, C., Oudre, L., & Vayatis, N. (2020). Selective review of
+offline change point detection methods. *Signal Processing*, 167,
+107299.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+
+ChangepointMethod = Literal["pelt", "binseg", "window"]
+
+
+def detect_changepoints(
+    series: pd.Series,
+    method: ChangepointMethod = "pelt",
+    penalty: float | None = None,
+    model: str = "rbf",
+) -> pd.DataFrame:
+    """Detect changepoints in a temporal value series.
+
+    Parameters
+    ----------
+    series
+        A 1-D series indexed by period (or any orderable). Index values
+        propagate into the output so changepoints can be reported in
+        their original time vocabulary.
+    method
+        ``"pelt"`` (default), ``"binseg"``, or ``"window"`` — the three
+        offline algorithms ruptures exposes. PELT is exact and usually
+        best; BinSeg is greedy but faster on long series; window scans
+        a fixed window across the signal.
+    penalty
+        Penalty term for adding a changepoint. Larger = fewer
+        changepoints. If ``None``, defaults to ``log(n)`` (BIC-style).
+        Pass an explicit float to tune sensitivity.
+    model
+        Cost function: ``"rbf"`` (default), ``"l1"``, ``"l2"``,
+        ``"normal"``. See ruptures documentation for the full list.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Columns ``period`` (index value at the breakpoint), ``index``
+        (positional index), and ``method`` (echo of the chosen method).
+    """
+    try:
+        import ruptures as rpt
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "detect_changepoints requires ruptures. "
+            "Install with: pip install 'pycorpdiff[temporal]'"
+        ) from exc
+
+    values = np.asarray(series.to_numpy(dtype=float))
+    if values.ndim != 1:
+        raise ValueError("series must be 1-D")
+    if len(values) < 4:
+        raise ValueError(f"need at least 4 observations; got {len(values)}")
+    if np.isnan(values).any():
+        raise ValueError("series contains NaN values; impute or drop them first")
+
+    pen = float(np.log(len(values))) if penalty is None else float(penalty)
+
+    if method == "pelt":
+        algo = rpt.Pelt(model=model)
+    elif method == "binseg":
+        algo = rpt.Binseg(model=model)
+    elif method == "window":
+        algo = rpt.Window(model=model)
+    else:  # pragma: no cover - typing makes this unreachable
+        raise ValueError(f"unknown method={method!r}")
+
+    algo.fit(values.reshape(-1, 1))
+    # ruptures returns endpoint indices including len(values) as the
+    # final "boundary"; drop it to keep only interior changepoints.
+    breakpoints = [bp for bp in algo.predict(pen=pen) if bp < len(values)]
+
+    rows = [
+        {"period": series.index[bp], "index": bp, "method": method}
+        for bp in breakpoints
+    ]
+    return pd.DataFrame(rows, columns=["period", "index", "method"])