forecastscope 0.1.0__py3-none-any.whl

forecastscope/diagnostics/autocorrelation.py

@@ -0,0 +1,217 @@
+"""Autocorrelation analysis: ACF, PACF (Durbin-Levinson), Ljung-Box, Box-Pierce, Durbin-Watson.
+
+The structure of a series' dependence on its own past is read off the ACF/PACF and quantified by the
+portmanteau (Ljung-Box / Box-Pierce) and serial-correlation (Durbin-Watson) tests. Each is delegated to its
+authoritative implementation in statsmodels, wrapped in one stable, NaN-safe API that returns a typed result
+carrying the statistic, the p-value where defined, the Bartlett significance band, and the primary reference.
+
+Tests / references (verified 2026-07-04):
+  * ACF  - sample autocorrelation r_k = c_k / c_0, with c_k the autocovariance at lag k. Box, Jenkins,
+           Reinsel & Ljung 2015, *Time Series Analysis*, 5th ed., Wiley, ISBN 978-1-118-67502-1.
+           ``statsmodels.tsa.stattools.acf``. Under white noise, r_k ~ N(0, 1/n) so the 95% band is
+           +/-1.96/sqrt(n) (Bartlett's approximation for independent data; wider under a MA process).
+  * PACF - partial autocorrelation: the correlation at lag k after removing the effect of lags 1..k-1,
+           computed here by the Durbin-Levinson recursion (``method='ld'``). Identifies the AR order p
+           (PACF cuts off after p). Same reference.
+  * Ljung-Box - portmanteau test that the first m autocorrelations are jointly zero; the standard
+           "are the residuals white noise?" check. Ljung & Box 1978, Biometrika 65(2):297-303,
+           DOI 10.1093/biomet/65.2.297. ``statsmodels.stats.diagnostic.acorr_ljungbox``.
+  * Box-Pierce - the older portmanteau (Ljung-Box is its small-sample refinement). Box & Pierce 1970,
+           JASA 65(332):1509-1526, DOI 10.2307/2284333. Same function, ``boxpierce=True``.
+  * Durbin-Watson - tests first-order serial correlation in regression residuals (DW~2 = none, <2 positive
+           serial correlation, >2 negative). Durbin & Watson 1950, Biometrika 37(3-4):409-428,
+           DOI 10.1093/biomet/37.3-4.409. ``statsmodels.stats.stattools.durbin_watson``.
+
+How to read them together (Box-Jenkins identification): a slowly-decaying ACF with a sharp PACF cut-off after
+lag p suggests an AR(p); a sharp ACF cut-off after lag q with a slowly-decaying PACF suggests an MA(q); both
+tailing off suggests ARMA. White noise has every r_k inside the Bartlett band and a non-significant Ljung-Box.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class Correlogram:
+    """ACF or PACF up to ``nlags``, with point values, the Bartlett band, and the read-out.
+
+    ``signif_lags`` lists the lags whose value escapes the +/-1.96/sqrt(n) band (the spikes a reader would
+    mark), already translated so callers do not have to re-derive the threshold.
+    """
+
+    name: str
+    lags: np.ndarray
+    values: np.ndarray
+    band: float
+    reference: str
+    signif_lags: list[int] = field(default_factory=list)
+
+
+def _clean(x) -> np.ndarray:
+    a = np.asarray(x, dtype=float).ravel()
+    return a[np.isfinite(a)]
+
+
+def bartlett_band(n: int, alpha: float = 0.05) -> float:
+    """The +/- z_{1-alpha/2}/sqrt(n) significance bound for the ACF of an independent series.
+
+    For alpha=0.05 this is the familiar +/-1.96/sqrt(n). Bartlett's formula gives a wider, variance-
+    dependent band under a moving-average process; the simple form is the standard first-pass threshold.
+    """
+    if n <= 0:
+        return float("inf")
+    # Normal quantile via the inverse error function (accurate; matches statsmodels' default band).
+    from scipy.special import erfinv
+
+    z = math.sqrt(2.0) * erfinv(1.0 - alpha)
+    return float(z / math.sqrt(n))
+
+
+def acf(x, nlags: int = 40, alpha: float = 0.05) -> Correlogram:
+    """Sample autocorrelation function with the Bartlett significance band (statsmodels, FFT-based)."""
+    from statsmodels.tsa.stattools import acf as _acf
+
+    a = _clean(x)
+    n = len(a)
+    nlags = min(nlags, n - 1)
+    values = _acf(a, nlags=nlags, fft=True, missing="drop")
+    lags = np.arange(len(values))
+    band = bartlett_band(n, alpha)
+    signif = [int(k) for k in lags[1:] if abs(values[k]) > band]  # exclude the trivial lag-0 = 1
+    return Correlogram(
+        name="ACF", lags=lags, values=values, band=band, signif_lags=signif,
+        reference="Box, Jenkins, Reinsel & Ljung 2015, Time Series Analysis, 5th ed., Wiley, ISBN 978-1-118-67502-1",
+    )
+
+
+def pacf(x, nlags: int = 40, alpha: float = 0.05) -> Correlogram:
+    """Partial autocorrelation via the Durbin-Levinson recursion (``method='ld'``) with the Bartlett band."""
+    from statsmodels.tsa.stattools import pacf as _pacf
+
+    a = _clean(x)
+    n = len(a)
+    nlags = min(nlags, n - 1)
+    values = _pacf(a, nlags=nlags, method="ld")
+    lags = np.arange(len(values))
+    band = bartlett_band(n, alpha)
+    signif = [int(k) for k in lags[1:] if abs(values[k]) > band]
+    return Correlogram(
+        name="PACF", lags=lags, values=values, band=band, signif_lags=signif,
+        reference="Durbin-Levinson recursion; Box, Jenkins, Reinsel & Ljung 2015, ISBN 978-1-118-67502-1",
+    )
+
+
+@dataclass(frozen=True)
+class PortmanteauTest:
+    """Ljung-Box or Box-Pierce: a joint test that the first ``lags`` autocorrelations are all zero."""
+
+    name: str
+    stat: float
+    pvalue: float
+    lags: int
+    df: int
+    white_noise: bool | None
+    reference: str
+
+
+def ljung_box(x, lags: int | list[int] = 10, model_df: int = 0, alpha: float = 0.05) -> PortmanteauTest:
+    """Ljung-Box Q. Small p => reject "no autocorrelation up to lag m" => the series is NOT white noise.
+
+    ``model_df`` is the number of ARMA parameters already fitted, subtracted from the degrees of freedom when
+    the test is run on residuals (so the residual diagnostic is not biased toward significance).
+    """
+    from statsmodels.stats.diagnostic import acorr_ljungbox
+
+    a = _clean(x)
+    m = max(lags) if isinstance(lags, (list, tuple)) else int(lags)
+    res = acorr_ljungbox(a, lags=[m], model_df=model_df, return_df=True)
+    stat = float(res["lb_stat"].iloc[0])
+    pvalue = float(res["lb_pvalue"].iloc[0])
+    return PortmanteauTest(
+        name="Ljung-Box", stat=stat, pvalue=pvalue, lags=m, df=max(0, m - model_df),
+        white_noise=bool(pvalue >= alpha),
+        reference="Ljung & Box 1978, Biometrika 65(2):297-303, DOI 10.1093/biomet/65.2.297",
+    )
+
+
+def box_pierce(x, lags: int = 10, model_df: int = 0, alpha: float = 0.05) -> PortmanteauTest:
+    """Box-Pierce: the older portmanteau; Ljung-Box is its small-sample refinement."""
+    from statsmodels.stats.diagnostic import acorr_ljungbox
+
+    a = _clean(x)
+    res = acorr_ljungbox(a, lags=[int(lags)], boxpierce=True, model_df=model_df, return_df=True)
+    stat = float(res["bp_stat"].iloc[0])
+    pvalue = float(res["bp_pvalue"].iloc[0])
+    return PortmanteauTest(
+        name="Box-Pierce", stat=stat, pvalue=pvalue, lags=int(lags), df=max(0, int(lags) - model_df),
+        white_noise=bool(pvalue >= alpha),
+        reference="Box & Pierce 1970, JASA 65(332):1509-1526, DOI 10.2307/2284333",
+    )
+
+
+def durbin_watson(x) -> float:
+    """Durbin-Watson statistic on (residual) series: ~2 = no 1st-order serial correlation, <2 positive, >2 negative."""
+    from statsmodels.stats.stattools import durbin_watson as _dw
+
+    a = _clean(x)
+    return float(_dw(a))
+
+
+def lag_plot_pairs(x, lag: int = 1) -> tuple[np.ndarray, np.ndarray]:
+    """Return the (x_{t-lag}, x_t) pairs a lag plot would render, dropping non-finite points.
+
+    A linear band => AR(1)-style dependence; a circular cloud => white noise; curved => nonlinearity;
+    isolated off-diagonal points => outliers (NIST e-Handbook sec. 1.3.3.15).
+    """
+    a = _clean(x)
+    if lag < 1 or lag >= len(a):
+        raise ValueError(f"lag must be in 1..{len(a) - 1}, got {lag}")
+    return a[:-lag], a[lag:]
+
+
+def autocorrelation_report(x, nlags: int = 40, lags_m: int = 10) -> dict:
+    """Run the full autocorrelation panel and return a JSON-ready report (for the baked artifact + docs)."""
+    a = _clean(x)
+    n = len(a)
+    acf_c = acf(a, nlags=nlags)
+    pacf_c = pacf(a, nlags=nlags)
+    lb = ljung_box(a, lags=lags_m)
+    bp = box_pierce(a, lags=lags_m)
+    return {
+        "n": int(n),
+        "bartlett_band": acf_c.band,
+        "acf": [{"lag": int(k), "value": float(v)} for k, v in zip(acf_c.lags, acf_c.values)],
+        "acf_signif_lags": acf_c.signif_lags,
+        "pacf": [{"lag": int(k), "value": float(v)} for k, v in zip(pacf_c.lags, pacf_c.values)],
+        "pacf_signif_lags": pacf_c.signif_lags,
+        "ljung_box": {"stat": lb.stat, "pvalue": lb.pvalue, "lags": lb.lags, "white_noise": lb.white_noise,
+                      "reference": lb.reference},
+        "box_pierce": {"stat": bp.stat, "pvalue": bp.pvalue, "lags": bp.lags, "white_noise": bp.white_noise,
+                       "reference": bp.reference},
+        "durbin_watson": durbin_watson(a),
+        "identification_hint": _identify(acf_c, pacf_c, lb),
+    }
+
+
+def _identify(acf_c: Correlogram, pacf_c: Correlogram, lb: PortmanteauTest) -> str:
+    """A conservative Box-Jenkins reading of the correlograms (a hint, not a fitted model)."""
+    if lb.white_noise:
+        return "no significant autocorrelation (white-noise-like); ARMA identification not warranted"
+    # tail-off vs cut-off via the count of signif lags and the decay of |acf| over the last quarter
+    a_vals = np.abs(acf_c.values[1:])
+    p_vals = np.abs(pacf_c.values[1:])
+    if len(a_vals) < 4:
+        return "series too short for a reliable ARMA-shape reading"
+    a_tail = float(np.mean(a_vals[len(a_vals) // 2:]))  # ACF in its later half
+    p_tail = float(np.mean(p_vals[len(p_vals) // 2:]))
+    a_band, p_band = acf_c.band, pacf_c.band
+    if p_tail < a_band and a_tail > a_band:
+        return "ACF tails off, PACF cuts off -> suggests an AR(p) (p ~ last significant PACF lag)"
+    if a_tail < a_band and p_tail > p_band:
+        return "ACF cuts off, PACF tails off -> suggests an MA(q) (q ~ last significant ACF lag)"
+    if a_tail > a_band and p_tail > p_band:
+        return "both tail off -> suggests ARMA; fit by AIC over a small (p,q) grid"
+    return "autocorrelation present but shape is mixed; inspect the correlograms directly"

forecastscope/diagnostics/causality.py

@@ -0,0 +1,183 @@
+"""Cross-series relationships: cross-correlation, Granger causality, and cointegration.
+
+The single-series diagnostics answer "what is this series?"; these answer "how do two series relate?" - which
+one leads, whether past values of one improve forecasts of the other (Granger), and whether two nonstationary
+series share a long-run equilibrium (cointegration) so their spread is stationary and forecastable even when
+the levels are not. This is the analysis foundation for the covariate and multivariate cases in the product.
+
+Methods / references (verified 2026-07-04):
+  * Cross-correlation function (CCF) - correlation of x_t with y_{t-k} across lags; the lead/lag detector.
+    Box-Jenkins tradition. ``statsmodels.tsa.stattools.ccf``.
+  * Granger causality - does the past of x improve a forecast of y beyond y's own past? An F-test on nested
+    VAR models. Granger 1969, Econometrica 37(3):424-438, DOI 10.2307/1912791. PREDICTIVE, not true cause.
+    ``statsmodels.tsa.stattools.grangercausalitytests``.
+  * Engle-Granger cointegration - two-step: regress one series on the other, ADF-test the residuals for a
+    unit root; a single cointegrating vector. Engle & Granger 1987, Econometrica 55(2):251-276,
+    DOI 10.2307/1913236. ``statsmodels.tsa.stattools.coint``.
+  * Johansen cointegration - ML/VECM rank test (trace + max-eigenvalue) for MULTIPLE cointegrating relations.
+    Johansen 1991, Econometrica 59(6):1551-1580, DOI 10.2307/2938278.
+    ``statsmodels.tsa.vector_ar.vecm.coint_johansen``.
+
+HONESTY: Granger "causality" is a statement about PREDICTABILITY, not mechanism - a common driver or a
+confound produces Granger causality without a causal link. Cointegration requires both series to be I(1)
+(unit-root nonstationary); it is meaningless on already-stationary series. The report checks and records this.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+def _clean_pair(x, y) -> tuple[np.ndarray, np.ndarray]:
+    a = np.asarray(x, dtype=float).ravel()
+    b = np.asarray(y, dtype=float).ravel()
+    m = min(len(a), len(b))
+    a, b = a[:m], b[:m]
+    mask = np.isfinite(a) & np.isfinite(b)
+    return a[mask], b[mask]
+
+
+@dataclass(frozen=True)
+class CrossCorrelation:
+    """CCF of x vs y across signed lags, with the lag of peak absolute correlation (the lead/lag)."""
+
+    lags: np.ndarray
+    values: np.ndarray
+    peak_lag: int                # >0: x leads y; <0: y leads x
+    peak_value: float
+    band: float                  # +/-1.96/sqrt(n) significance band
+    reference: str
+
+
+def cross_correlation(x, y, max_lag: int = 40) -> CrossCorrelation:
+    """Cross-correlation across signed lags; a positive peak lag means x leads y.
+
+    Defined unambiguously as corr(x_t, y_{t+k}) for k = -max_lag..max_lag. If the peak is at k > 0 then a
+    future value of y correlates with the present of x (x leads y); at k < 0, y leads x. Computed directly on
+    mean-centred, shifted overlaps so the sign convention is explicit (statsmodels' ccf mixes the convention).
+    """
+    a, b = _clean_pair(x, y)
+    n = len(a)
+    max_lag = min(max_lag, n - 1)
+    am, bm = a - a.mean(), b - b.mean()
+    denom = float(np.sqrt(np.sum(am ** 2) * np.sum(bm ** 2)))
+    if denom == 0:
+        denom = 1e-12
+    lags = np.arange(-max_lag, max_lag + 1)
+    values = np.empty(len(lags))
+    for i, k in enumerate(lags):
+        if k >= 0:
+            # corr(x_t, y_{t+k}): overlap x[:n-k] with y[k:]
+            cov = float(np.sum(am[: n - k] * bm[k:]))
+        else:
+            cov = float(np.sum(am[-k:] * bm[: n + k]))
+        values[i] = cov / denom
+    peak_idx = int(np.argmax(np.abs(values)))
+    band = float(1.96 / np.sqrt(n))
+    return CrossCorrelation(
+        lags=lags, values=values, peak_lag=int(lags[peak_idx]), peak_value=float(values[peak_idx]),
+        band=band, reference="Box & Jenkins (CCF); direct shifted-overlap correlation",
+    )
+
+
+@dataclass(frozen=True)
+class GrangerResult:
+    """Granger-causality F-test across lags: does the past of ``cause`` help predict ``effect``?"""
+
+    direction: str               # "cause -> effect"
+    best_lag: int
+    pvalues: dict[int, float]
+    causes: bool                 # min p-value across lags < alpha
+    alpha: float
+    reference: str
+
+
+def granger_causality(cause, effect, max_lag: int = 6, alpha: float = 0.05) -> GrangerResult:
+    """Test whether ``cause`` Granger-causes ``effect`` (past of cause improves the forecast of effect)."""
+    from statsmodels.tsa.stattools import grangercausalitytests
+
+    a, b = _clean_pair(cause, effect)
+    # statsmodels tests whether the SECOND column Granger-causes the FIRST -> stack [effect, cause]
+    data = np.column_stack([b, a])
+    res = grangercausalitytests(data, maxlag=max_lag)
+    pvals = {lag: float(res[lag][0]["ssr_ftest"][1]) for lag in res}
+    best_lag = min(pvals, key=pvals.get)
+    return GrangerResult(
+        direction="cause -> effect", best_lag=int(best_lag), pvalues=pvals,
+        causes=bool(pvals[best_lag] < alpha), alpha=alpha,
+        reference="Granger 1969, Econometrica 37(3):424-438, DOI 10.2307/1912791",
+    )
+
+
+@dataclass(frozen=True)
+class CointegrationResult:
+    """Engle-Granger + Johansen cointegration verdicts for a pair of (ideally I(1)) series."""
+
+    eg_stat: float
+    eg_pvalue: float
+    eg_cointegrated: bool
+    johansen_trace_stat: float
+    johansen_trace_crit95: float
+    johansen_rank_at_least_1: bool
+    both_i1: bool                # both series are unit-root nonstationary (precondition)
+    alpha: float
+    reference: str
+
+
+def _is_i1(a: np.ndarray, alpha: float) -> bool:
+    """A series is I(1) if ADF does NOT reject a unit root on levels but DOES on first differences."""
+    from statsmodels.tsa.stattools import adfuller
+
+    try:
+        p_level = adfuller(a, autolag="AIC")[1]
+        p_diff = adfuller(np.diff(a), autolag="AIC")[1]
+        return bool(p_level >= alpha and p_diff < alpha)
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def cointegration(x, y, alpha: float = 0.05) -> CointegrationResult:
+    """Engle-Granger (residual ADF) + Johansen (trace rank) cointegration, with the I(1) precondition check."""
+    from statsmodels.tsa.stattools import coint
+    from statsmodels.tsa.vector_ar.vecm import coint_johansen
+
+    a, b = _clean_pair(x, y)
+    eg_stat, eg_p, _crit = coint(a, b)
+    j = coint_johansen(np.column_stack([a, b]), det_order=0, k_ar_diff=1)
+    trace0 = float(j.trace_stat[0])
+    crit95_0 = float(j.trace_stat_crit_vals[0][1])        # 95% critical value for rank r=0
+    both_i1 = bool(_is_i1(a, alpha) and _is_i1(b, alpha))
+    return CointegrationResult(
+        eg_stat=float(eg_stat), eg_pvalue=float(eg_p), eg_cointegrated=bool(eg_p < alpha),
+        johansen_trace_stat=trace0, johansen_trace_crit95=crit95_0,
+        johansen_rank_at_least_1=bool(trace0 > crit95_0), both_i1=both_i1, alpha=alpha,
+        reference="Engle & Granger 1987, DOI 10.2307/1913236; Johansen 1991, DOI 10.2307/2938278",
+    )
+
+
+def causality_report(x, y, max_lag: int = 6) -> dict:
+    """Run the cross-series panel (CCF + bidirectional Granger + cointegration) and return a JSON-ready report."""
+    a, b = _clean_pair(x, y)
+    ccf_res = cross_correlation(a, b)
+    g_xy = granger_causality(a, b, max_lag=max_lag)       # does x cause y?
+    g_yx = granger_causality(b, a, max_lag=max_lag)       # does y cause x?
+    coint_res = cointegration(a, b)
+    return {
+        "n": len(a),
+        "ccf": {"peak_lag": ccf_res.peak_lag, "peak_value": ccf_res.peak_value, "band": ccf_res.band,
+                "lead": ("x leads y" if ccf_res.peak_lag > 0 else "y leads x" if ccf_res.peak_lag < 0 else "synchronous"),
+                "reference": ccf_res.reference},
+        "granger": {"x_causes_y": {"causes": g_xy.causes, "best_lag": g_xy.best_lag,
+                                   "pvalue": g_xy.pvalues[g_xy.best_lag]},
+                    "y_causes_x": {"causes": g_yx.causes, "best_lag": g_yx.best_lag,
+                                   "pvalue": g_yx.pvalues[g_yx.best_lag]},
+                    "reference": g_xy.reference},
+        "cointegration": {"engle_granger_pvalue": coint_res.eg_pvalue,
+                          "engle_granger_cointegrated": coint_res.eg_cointegrated,
+                          "johansen_rank_at_least_1": coint_res.johansen_rank_at_least_1,
+                          "both_series_I1": coint_res.both_i1,
+                          "valid": coint_res.both_i1,     # cointegration is only meaningful when both are I(1)
+                          "reference": coint_res.reference},
+        "note": "Granger = predictability, not mechanism; cointegration requires both series I(1)",
+    }

forecastscope/diagnostics/changepoints.py

@@ -0,0 +1,172 @@
+"""Change-point and regime analysis: PELT, Binary Segmentation, CUSUM, Markov-switching regimes.
+
+A structural break (a shift in mean, variance, or dynamics) violates the "one process generated all of it"
+assumption every fitted model makes. This module locates WHERE a series changes (offline change-point
+detection), tests WHETHER parameters are stable (CUSUM), and models WHICH regime each point belongs to
+(Markov switching). Drift, level shifts, and regime changes are exactly the structures that fool both the
+classical ladder and a zero-shot foundation model, so the case narratives lean on this panel.
+
+Methods / references (verified 2026-07-04):
+  * PELT - exact penalized change-point search in expected linear time via pruning. Killick, Fearnhead &
+    Eckley 2012, JASA 107(500):1590-1598, DOI 10.1080/01621459.2012.737745. ``ruptures.Pelt``.
+  * Binary Segmentation - greedy sequential single-break search, O(n log n), approximate. ``ruptures.Binseg``.
+    Library reference: Truong, Oudre & Vayatis 2020, Signal Processing 167:107299,
+    DOI 10.1016/j.sigpro.2019.107299 (the ruptures review, its recommended citation).
+  * OLS-CUSUM - parameter-stability test on cumulative OLS residuals against Brownian-bridge bounds.
+    Brown, Durbin & Evans 1975 lineage; implemented by
+    ``statsmodels.stats.diagnostic.breaks_cusumolsresid``.
+  * Markov switching - Hamilton 1989, Econometrica 57(2):357-384 (JSTOR 1912559): latent K-regime Markov
+    chain over mean/variance; smoothed regime probabilities per point.
+    ``statsmodels.tsa.regime_switching.markov_regression.MarkovRegression``.
+
+NOTE: the Chow test (single KNOWN break date) is deliberately not wrapped - it is NOT first-class in
+statsmodels' public API (verified); PELT/Binseg + Zivot-Andrews (stationarity page) cover the unknown-date
+problem the product actually has. BOCPD (Adams & MacKay 2007) is an online method; it belongs to the
+streaming lane (preqts) and is recorded in the plan, not duplicated here.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import pairwise
+
+import numpy as np
+
+
+def _clean(x) -> np.ndarray:
+    a = np.asarray(x, dtype=float).ravel()
+    return a[np.isfinite(a)]
+
+
+@dataclass(frozen=True)
+class ChangePoints:
+    """Detected break indices (each the FIRST index of a new segment; excludes 0 and n) + segment stats."""
+
+    name: str
+    breakpoints: list[int]
+    segments: list[dict]         # per segment: {start, end, mean, std}
+    model: str                   # the cost model used ("l2" mean-shift, "normal" mean+var, "rbf" generic)
+    penalty: float | None
+    reference: str
+
+
+def _segments(a: np.ndarray, bkps_first_index: list[int]) -> list[dict]:
+    bounds = [0, *bkps_first_index, len(a)]
+    out = []
+    for s, e in pairwise(bounds):
+        seg = a[s:e]
+        out.append({"start": int(s), "end": int(e), "mean": float(np.mean(seg)), "std": float(np.std(seg))})
+    return out
+
+
+def pelt(x, model: str = "l2", penalty: float | None = None, min_size: int = 5) -> ChangePoints:
+    """PELT with a BIC-style default penalty (2 * sigma^2 * log n for the l2 cost when none is given)."""
+    import ruptures as rpt
+
+    a = _clean(x)
+    n = len(a)
+    if penalty is None:
+        sigma2 = float(np.var(np.diff(a))) / 2.0 or 1e-8   # robust noise-variance proxy
+        penalty = 2.0 * sigma2 * np.log(max(n, 2))
+    algo = rpt.Pelt(model=model, min_size=min_size).fit(a)
+    ends = algo.predict(pen=penalty)                        # ruptures returns segment END indices incl. n
+    bkps = [int(b) for b in ends if b < n]
+    return ChangePoints(
+        name="PELT", breakpoints=bkps, segments=_segments(a, bkps), model=model, penalty=float(penalty),
+        reference="Killick, Fearnhead & Eckley 2012, JASA 107(500):1590-1598, DOI 10.1080/01621459.2012.737745",
+    )
+
+
+def binseg(x, n_bkps: int, model: str = "l2", min_size: int = 5) -> ChangePoints:
+    """Binary segmentation for a KNOWN number of breaks (fast, approximate)."""
+    import ruptures as rpt
+
+    a = _clean(x)
+    algo = rpt.Binseg(model=model, min_size=min_size).fit(a)
+    ends = algo.predict(n_bkps=n_bkps)
+    bkps = [int(b) for b in ends if b < len(a)]
+    return ChangePoints(
+        name="BinSeg", breakpoints=bkps, segments=_segments(a, bkps), model=model, penalty=None,
+        reference="Truong, Oudre & Vayatis 2020, Signal Processing 167:107299, DOI 10.1016/j.sigpro.2019.107299",
+    )
+
+
+@dataclass(frozen=True)
+class CusumResult:
+    """OLS-CUSUM parameter-stability test: sup |cumulative scaled OLS residual| vs Brownian-bridge bounds."""
+
+    stat: float
+    pvalue: float
+    stable: bool
+    alpha: float
+    reference: str
+
+
+def cusum_stability(x, alpha: float = 0.05) -> CusumResult:
+    """OLS-CUSUM on the series demeaned by OLS-on-constant: rejects when the mean is unstable over time."""
+    from statsmodels.stats.diagnostic import breaks_cusumolsresid
+
+    a = _clean(x)
+    resid = a - a.mean()                                   # OLS residuals of y ~ const
+    stat, pvalue, _crit = breaks_cusumolsresid(resid)
+    return CusumResult(
+        stat=float(stat), pvalue=float(pvalue), stable=bool(pvalue >= alpha), alpha=alpha,
+        reference="Brown, Durbin & Evans 1975 lineage; statsmodels breaks_cusumolsresid (Ploberger-Kramer OLS-CUSUM)",
+    )
+
+
+@dataclass(frozen=True)
+class RegimeFit:
+    """A fitted K-regime Markov-switching mean(+variance) model with per-point smoothed probabilities."""
+
+    k_regimes: int
+    regime_means: list[float]
+    smoothed_probabilities: np.ndarray   # (n, k) - P(regime j | full sample) per point
+    most_likely: np.ndarray              # (n,) argmax regime per point
+    transition_matrix: list[list[float]]
+    reference: str
+
+
+def markov_regimes(x, k_regimes: int = 2, switching_variance: bool = True) -> RegimeFit:
+    """Hamilton Markov-switching regression (mean per regime; optionally variance per regime)."""
+    from statsmodels.tsa.regime_switching.markov_regression import MarkovRegression
+
+    a = _clean(x)
+    model = MarkovRegression(a, k_regimes=k_regimes, trend="c", switching_variance=switching_variance)
+    res = model.fit(disp=False)
+    smoothed = np.asarray(res.smoothed_marginal_probabilities)
+    if smoothed.ndim == 1:
+        smoothed = smoothed.reshape(-1, k_regimes)
+    # Pull each regime's mean by its named parameter (the leading params are transition probabilities).
+    names = list(res.model.param_names)
+    means = [float(res.params[names.index(f"const[{j}]")]) for j in range(k_regimes)]
+    tm = np.asarray(res.regime_transition)[..., 0] if hasattr(res, "regime_transition") else np.full((k_regimes, k_regimes), np.nan)
+    return RegimeFit(
+        k_regimes=k_regimes, regime_means=means, smoothed_probabilities=smoothed,
+        most_likely=np.asarray(smoothed.argmax(axis=1)),
+        transition_matrix=[[float(v) for v in row] for row in np.asarray(tm).reshape(k_regimes, k_regimes)],
+        reference="Hamilton 1989, Econometrica 57(2):357-384, JSTOR 1912559; statsmodels MarkovRegression",
+    )
+
+
+def changepoints_report(x, k_regimes: int = 2) -> dict:
+    """Run the change-point panel (PELT + CUSUM + Markov regimes) and return a JSON-ready report."""
+    a = _clean(x)
+    p = pelt(a)
+    c = cusum_stability(a)
+    out = {
+        "n": len(a),
+        "pelt": {"breakpoints": p.breakpoints, "segments": p.segments, "model": p.model,
+                 "penalty": p.penalty, "reference": p.reference},
+        "cusum": {"stat": c.stat, "pvalue": c.pvalue, "stable": c.stable, "reference": c.reference},
+    }
+    # Markov regimes can fail to converge on degenerate series; report honestly instead of crashing.
+    try:
+        r = markov_regimes(a, k_regimes=k_regimes)
+        out["markov"] = {
+            "k_regimes": r.k_regimes, "regime_means": r.regime_means,
+            "most_likely": r.most_likely.tolist(), "transition_matrix": r.transition_matrix,
+            "reference": r.reference,
+        }
+    except Exception as exc:  # noqa: BLE001 - baked artifact must record the failure, not die
+        out["markov"] = {"error": f"{type(exc).__name__}: {exc}"}
+    return out