forecastscope 0.1.0__py3-none-any.whl

forecastscope/diagnostics/stationarity.py

@@ -0,0 +1,233 @@
+"""Stationarity and unit-root analysis: real, verified tests, not toy reimplementations.
+
+The forecasting question "is this series stationary, and if not how many differences make it so?" is
+answered here by the standard unit-root / stationarity tests, each delegated to its authoritative
+implementation (statsmodels or the ``arch`` package, per the verified library survey), wrapped in one
+stable, NaN-safe API that returns a typed result carrying the statistic, the p-value / critical values,
+a plain verdict, and the primary reference so the foundation travels with the code.
+
+Tests and where they live (verified 2026-07-04):
+  * ADF  - Augmented Dickey-Fuller. H0: unit root (non-stationary). Dickey & Fuller 1979,
+           DOI 10.1080/01621459.1979.10482531. ``statsmodels.tsa.stattools.adfuller``.
+  * KPSS - H0: (level/trend) stationary -- the OPPOSITE null to ADF. Kwiatkowski, Phillips, Schmidt &
+           Shin 1992, DOI 10.1016/0304-4076(92)90104-Y. ``statsmodels.tsa.stattools.kpss``.
+  * PP   - Phillips-Perron, nonparametric HAC correction. H0: unit root. Phillips & Perron 1988,
+           DOI 10.1093/biomet/75.2.335. ``arch.unitroot.PhillipsPerron`` (statsmodels has no PP).
+  * DF-GLS- GLS-detrended, locally most powerful DF. Elliott, Rothenberg & Stock 1996,
+           DOI 10.2307/2171846. ``arch.unitroot.DFGLS`` (statsmodels has no DF-GLS).
+  * Zivot-Andrews - unit-root test allowing ONE endogenous structural break. Zivot & Andrews 1992,
+           DOI 10.1080/07350015.1992.10509904. ``statsmodels.tsa.stattools.zivot_andrews``.
+
+Differencing-order selection follows FPP3 (Hyndman & Athanasopoulos, sec. 9.1): ``ndiffs`` is the
+KPSS-sequential rule (difference while KPSS rejects stationarity), and ``nsdiffs`` uses the seasonal
+strength measure Fs from an STL decomposition (difference seasonally when Fs >= 0.64). This is the
+FPP3-correct procedure; it deliberately does NOT use the ADF+KPSS four-quadrant table (that table is
+valid general econometrics and is exposed as an interpretation in ``combined_verdict``, but it is not
+what FPP3 prescribes). No pmdarima dependency.
+"""
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass, field
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class TestResult:
+    """One unit-root / stationarity test outcome.
+
+    ``null`` states the null hypothesis so a p-value is never read backwards (ADF and KPSS have opposite
+    nulls). ``stationary`` is the test's verdict at ``alpha`` already translated to the common language
+    "is the series stationary?", so callers do not have to remember each test's polarity.
+    """
+
+    name: str
+    stat: float
+    pvalue: float | None
+    crit: dict[str, float]
+    null: str
+    stationary: bool | None
+    alpha: float
+    reference: str
+    extra: dict[str, float] = field(default_factory=dict)
+
+
+def _clean(x) -> np.ndarray:
+    """Coerce to a 1-D float array and drop non-finite points (tests require finite input)."""
+    a = np.asarray(x, dtype=float).ravel()
+    return a[np.isfinite(a)]
+
+
+def adf(x, regression: str = "c", alpha: float = 0.05) -> TestResult:
+    """Augmented Dickey-Fuller. Rejecting H0 (small p) => evidence the series IS stationary."""
+    from statsmodels.tsa.stattools import adfuller
+
+    a = _clean(x)
+    stat, pvalue, _usedlag, _nobs, crit, _icbest = adfuller(a, regression=regression, autolag="AIC")
+    return TestResult(
+        name="ADF", stat=float(stat), pvalue=float(pvalue),
+        crit={k: float(v) for k, v in crit.items()},
+        null="unit root (non-stationary)", stationary=bool(pvalue < alpha), alpha=alpha,
+        reference="Dickey & Fuller 1979, DOI 10.1080/01621459.1979.10482531",
+    )
+
+
+def kpss(x, regression: str = "c", alpha: float = 0.05) -> TestResult:
+    """KPSS. Its null is STATIONARITY, so rejecting H0 (small p) => evidence the series is NON-stationary."""
+    from statsmodels.tsa.stattools import kpss as _kpss
+
+    a = _clean(x)
+    with warnings.catch_warnings():
+        # statsmodels warns when the p-value is clipped at the table edge; that is expected, not an error.
+        warnings.simplefilter("ignore")
+        stat, pvalue, _lags, crit = _kpss(a, regression=regression, nlags="auto")
+    return TestResult(
+        name="KPSS", stat=float(stat), pvalue=float(pvalue),
+        crit={k: float(v) for k, v in crit.items()},
+        null="stationary", stationary=bool(pvalue >= alpha), alpha=alpha,
+        reference="Kwiatkowski, Phillips, Schmidt & Shin 1992, DOI 10.1016/0304-4076(92)90104-Y",
+    )
+
+
+def phillips_perron(x, trend: str = "c", alpha: float = 0.05) -> TestResult:
+    """Phillips-Perron (arch). Nonparametric HAC correction; H0: unit root. Small p => stationary."""
+    from arch.unitroot import PhillipsPerron
+
+    a = _clean(x)
+    t = PhillipsPerron(a, trend=trend)
+    return TestResult(
+        name="PhillipsPerron", stat=float(t.stat), pvalue=float(t.pvalue),
+        crit={k: float(v) for k, v in t.critical_values.items()},
+        null="unit root (non-stationary)", stationary=bool(t.pvalue < alpha), alpha=alpha,
+        reference="Phillips & Perron 1988, DOI 10.1093/biomet/75.2.335",
+    )
+
+
+def dfgls(x, trend: str = "c", alpha: float = 0.05) -> TestResult:
+    """DF-GLS (arch). GLS-detrended, locally most powerful DF; H0: unit root. Small p => stationary."""
+    from arch.unitroot import DFGLS
+
+    a = _clean(x)
+    t = DFGLS(a, trend=trend)
+    return TestResult(
+        name="DFGLS", stat=float(t.stat), pvalue=float(t.pvalue),
+        crit={k: float(v) for k, v in t.critical_values.items()},
+        null="unit root (non-stationary)", stationary=bool(t.pvalue < alpha), alpha=alpha,
+        reference="Elliott, Rothenberg & Stock 1996, DOI 10.2307/2171846",
+    )
+
+
+def zivot_andrews(x, regression: str = "c", alpha: float = 0.05) -> TestResult:
+    """Zivot-Andrews: unit-root test allowing ONE endogenous structural break (reports the break index)."""
+    from statsmodels.tsa.stattools import zivot_andrews as _za
+
+    a = _clean(x)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        stat, pvalue, crit, _baselag, bpidx = _za(a, regression=regression)
+    return TestResult(
+        name="ZivotAndrews", stat=float(stat), pvalue=float(pvalue),
+        crit={k: float(v) for k, v in crit.items()},
+        null="unit root with no break", stationary=bool(pvalue < alpha), alpha=alpha,
+        reference="Zivot & Andrews 1992, DOI 10.1080/07350015.1992.10509904",
+        extra={"break_index": float(bpidx)},
+    )
+
+
+def ndiffs(x, alpha: float = 0.05, max_d: int = 2) -> int:
+    """Number of first differences to make the series stationary, via the FPP3 KPSS-sequential rule.
+
+    Apply KPSS; while it rejects stationarity (p < alpha) and we are under ``max_d``, difference once
+    more and re-test. This is Hyndman & Athanasopoulos FPP3 sec. 9.1 (``unitroot_ndiffs``), not the
+    ADF+KPSS four-quadrant heuristic.
+    """
+    a = _clean(x)
+    d = 0
+    while d < max_d:
+        if len(a) < 8 or np.allclose(a, a[0]):
+            break
+        try:
+            res = kpss(a, regression="c", alpha=alpha)
+        except (ValueError, np.linalg.LinAlgError):
+            break
+        if res.stationary:  # KPSS did not reject stationarity -> stop
+            break
+        a = np.diff(a)
+        d += 1
+    return d
+
+
+def seasonal_strength(x, period: int) -> float:
+    """FPP3 seasonal strength Fs = max(0, 1 - Var(remainder)/Var(seasonal+remainder)) from an STL fit.
+
+    Wang, Smith & Hyndman 2006 (DOI 10.1007/s10618-005-0039-x) feature; strength form per FPP3 sec. 4.3.
+    Returns 0.0 when the series is too short for two full periods (STL is undefined there).
+    """
+    from statsmodels.tsa.seasonal import STL
+
+    a = _clean(x)
+    if period < 2 or len(a) < 2 * period:
+        return 0.0
+    res = STL(a, period=period, robust=True).fit()
+    var_r = float(np.var(res.resid))
+    var_sr = float(np.var(res.seasonal + res.resid))
+    if var_sr <= 0:
+        return 0.0
+    return float(max(0.0, 1.0 - var_r / var_sr))
+
+
+def nsdiffs(x, period: int, max_D: int = 1, threshold: float = 0.64) -> int:
+    """Number of SEASONAL differences via the FPP3 seasonal-strength rule (difference while Fs >= 0.64)."""
+    a = _clean(x)
+    D = 0
+    while D < max_D:
+        if len(a) < 2 * period or seasonal_strength(a, period) < threshold:
+            break
+        a = a[period:] - a[:-period]
+        D += 1
+    return D
+
+
+def combined_verdict(adf_res: TestResult, kpss_res: TestResult) -> str:
+    """The ADF+KPSS four-quadrant interpretation (general econometrics, not FPP3).
+
+    ADF rejects unit root (stationary) x KPSS rejects stationarity (non-stationary) -> four cases:
+      both agree stationary / both agree non-stationary / trend-stationary / difference-stationary.
+    """
+    adf_stat = adf_res.stationary
+    kpss_stat = kpss_res.stationary
+    if adf_stat and kpss_stat:
+        return "stationary (both tests agree)"
+    if not adf_stat and not kpss_stat:
+        return "non-stationary (both tests agree)"
+    if adf_stat and not kpss_stat:
+        return "difference-stationary (ADF stationary, KPSS rejects: likely needs differencing)"
+    return "trend-stationary (KPSS stationary, ADF unit root: detrend rather than difference)"
+
+
+def stationarity_report(x, period: int | None = None, alpha: float = 0.05) -> dict:
+    """Run the full stationarity panel and return a JSON-ready report (for the baked artifact + docs).
+
+    Includes ADF, KPSS, Phillips-Perron, DF-GLS, Zivot-Andrews, the four-quadrant combined verdict, and
+    the FPP3 differencing recommendation (d via KPSS-sequential; D via seasonal strength when ``period``).
+    """
+    a = _clean(x)
+    adf_res = adf(a, alpha=alpha)
+    kpss_res = kpss(a, alpha=alpha)
+    tests = [adf_res, kpss_res, phillips_perron(a, alpha=alpha), dfgls(a, alpha=alpha),
+             zivot_andrews(a, alpha=alpha)]
+    report = {
+        "n": int(a.size),
+        "tests": [
+            {"name": t.name, "stat": t.stat, "pvalue": t.pvalue, "crit": t.crit,
+             "null": t.null, "stationary": t.stationary, "reference": t.reference, **t.extra}
+            for t in tests
+        ],
+        "combined_verdict": combined_verdict(adf_res, kpss_res),
+        "recommended_d": ndiffs(a, alpha=alpha),
+    }
+    if period and period >= 2:
+        report["seasonal_strength"] = seasonal_strength(a, period)
+        report["recommended_D"] = nsdiffs(a, period)
+    return report

forecastscope/diagnostics/volatility.py

@@ -0,0 +1,187 @@
+"""Volatility, heteroscedasticity, and variance-stabilizing transforms.
+
+Two related questions: (1) is the series' variance constant, or does it cluster in bursts (conditional
+heteroscedasticity)? and (2) can a power transform stabilize a growing variance so an additive model fits a
+multiplicative series? The first is answered by Engle's ARCH-LM test and a fitted GARCH conditional-variance
+model; the second by the Box-Cox family with an MLE or Guerrero (seasonal) lambda. Each is delegated to its
+authoritative implementation and wrapped in one NaN-safe API carrying the primary reference.
+
+IMPORTANT scope note: GARCH here characterises VOLATILITY (the second moment). It is an ANALYSIS tool, not a
+point-forecast method; the forecasting ladder's point methods live in ``model/``. Volatility structure is a
+property the analysis pillar surfaces (e.g. finance/energy series with variance clustering), and it explains
+why a point forecast's intervals should widen in turbulent regimes.
+
+Methods / references (verified 2026-07-04, see wip/chronoscope/research-volatility-transforms-2026-07-04.md):
+  * ARCH-LM - Engle 1982, Econometrica 50(4):987-1007, DOI 10.2307/1912773. ``statsmodels.stats.diagnostic.het_arch``.
+  * GARCH / EGARCH - Bollerslev 1986, J. Econometrics 31(3):307-327, DOI 10.1016/0304-4076(86)90063-1.
+    ``arch.arch_model`` (Sheppard). EGARCH captures leverage asymmetry; FIGARCH captures long-memory volatility.
+  * Box-Cox - Box & Cox 1964, JRSS-B 26(2):211-252, JSTOR 2984418. ``scipy.stats.boxcox`` / ``boxcox_normmax``.
+  * Guerrero lambda - Guerrero 1993, J. Forecasting 12(1):37-48, DOI 10.1002/for.3980120104.
+    ``coreforecast.scalers.boxcox_lambda(method='guerrero', season_length=...)`` (an installed dependency).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+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 ArchTest:
+    """Engle ARCH-LM test for conditional heteroscedasticity (variance clustering)."""
+
+    lm_stat: float
+    lm_pvalue: float
+    f_stat: float
+    f_pvalue: float
+    nlags: int
+    has_arch: bool
+    alpha: float
+    reference: str
+
+
+def arch_lm(x, nlags: int = 12, alpha: float = 0.05, demean: bool = True) -> ArchTest:
+    """ARCH-LM on the series (demeaned by default). Small p => variance clusters (ARCH effects present)."""
+    from statsmodels.stats.diagnostic import het_arch
+
+    a = _clean(x)
+    resid = a - a.mean() if demean else a
+    lm_stat, lm_p, f_stat, f_p = het_arch(resid, nlags=nlags)
+    return ArchTest(
+        lm_stat=float(lm_stat), lm_pvalue=float(lm_p), f_stat=float(f_stat), f_pvalue=float(f_p),
+        nlags=int(nlags), has_arch=bool(lm_p < alpha), alpha=alpha,
+        reference="Engle 1982, Econometrica 50(4):987-1007, DOI 10.2307/1912773",
+    )
+
+
+@dataclass(frozen=True)
+class GarchFit:
+    """A fitted GARCH-family conditional-variance model: per-point conditional volatility + parameters."""
+
+    vol: str
+    p: int
+    q: int
+    params: dict[str, float]
+    conditional_volatility: np.ndarray   # sigma_t per point (std, not variance)
+    persistence: float                   # sum(alpha)+sum(beta): near 1 => shocks persist (IGARCH-like)
+    loglikelihood: float
+    reference: str
+
+
+def garch(x, p: int = 1, q: int = 1, vol: str = "GARCH", dist: str = "normal",
+          rescale: bool = True) -> GarchFit:
+    """Fit a GARCH(p,q) (or EGARCH/FIGARCH) conditional-variance model to the series' mean residuals."""
+    from arch import arch_model
+
+    a = _clean(x)
+    # arch prefers series scaled to roughly unit range; rescale=True lets it handle that internally.
+    model = arch_model(a, mean="Constant", vol=vol, p=p, q=q, dist=dist, rescale=rescale)
+    res = model.fit(disp="off")
+    params = {k: float(v) for k, v in res.params.items()}
+    # persistence: sum of the alpha[*] and beta[*] parameters (standard GARCH stationarity read-out)
+    persistence = float(sum(v for k, v in params.items() if k.startswith(("alpha", "beta"))))
+    return GarchFit(
+        vol=vol, p=p, q=q, params=params,
+        conditional_volatility=np.asarray(res.conditional_volatility, dtype=float),
+        persistence=persistence, loglikelihood=float(res.loglikelihood),
+        reference="Bollerslev 1986, J. Econometrics 31(3):307-327, DOI 10.1016/0304-4076(86)90063-1",
+    )
+
+
+@dataclass(frozen=True)
+class BoxCoxResult:
+    """A Box-Cox variance-stabilizing transform: the fitted lambda, the transformed series, and the shift."""
+
+    lam: float
+    method: str                  # "mle", "guerrero", or "log"
+    transformed: np.ndarray
+    shift: float                 # amount added to make the series strictly positive (0 if already >0)
+    reference: str
+
+
+def _positive_shift(a: np.ndarray) -> tuple[np.ndarray, float]:
+    """Box-Cox needs y > 0; shift by (1 - min) when non-positive values are present. Record the shift."""
+    m = float(np.min(a))
+    if m <= 0:
+        shift = 1.0 - m
+        return a + shift, shift
+    return a, 0.0
+
+
+def box_cox(x, method: str = "mle", season_length: int | None = None) -> BoxCoxResult:
+    """Box-Cox transform with lambda by MLE (scipy) or Guerrero (coreforecast, seasonal-aware).
+
+    ``method='mle'`` maximizes the profile likelihood; ``method='guerrero'`` minimizes the coefficient of
+    variation across seasonal subseries (needs ``season_length``); ``method='log'`` forces lambda=0.
+    """
+    a = _clean(x)
+    shifted, shift = _positive_shift(a)
+    if method == "log":
+        return BoxCoxResult(lam=0.0, method="log", transformed=np.log(shifted), shift=shift,
+                            reference="Box & Cox 1964, JRSS-B 26(2):211-252, JSTOR 2984418 (log special case)")
+    if method == "guerrero":
+        from coreforecast.scalers import boxcox_lambda
+        from scipy.special import boxcox as _bc
+
+        if not season_length or season_length < 2:
+            raise ValueError("Guerrero lambda needs season_length >= 2")
+        lam = float(boxcox_lambda(shifted.astype(np.float64), method="guerrero", season_length=season_length))
+        transformed = np.asarray(_bc(shifted, lam), dtype=float)
+        return BoxCoxResult(lam=lam, method="guerrero", transformed=transformed, shift=shift,
+                            reference="Guerrero 1993, J. Forecasting 12(1):37-48, DOI 10.1002/for.3980120104")
+    # default: MLE via scipy
+    from scipy.stats import boxcox as _scipy_boxcox
+
+    transformed, lam = _scipy_boxcox(shifted)
+    return BoxCoxResult(lam=float(lam), method="mle", transformed=np.asarray(transformed, dtype=float),
+                        shift=shift, reference="Box & Cox 1964, JRSS-B 26(2):211-252, JSTOR 2984418")
+
+
+def rolling_volatility(x, window: int = 20) -> dict:
+    """Rolling mean and std (the visual heteroscedasticity check); returns JSON-ready arrays."""
+    import pandas as pd
+
+    a = _clean(x)
+    s = pd.Series(a)
+    return {
+        "window": int(window),
+        "rolling_mean": s.rolling(window).mean().to_numpy().tolist(),
+        "rolling_std": s.rolling(window).std().to_numpy().tolist(),
+    }
+
+
+def volatility_report(x, arch_lags: int = 12, season_length: int | None = None,
+                      garch_pq: tuple[int, int] = (1, 1)) -> dict:
+    """Run the volatility panel (ARCH-LM + rolling vol + Box-Cox lambda; GARCH only if ARCH is present)."""
+    a = _clean(x)
+    at = arch_lm(a, nlags=arch_lags)
+    out = {
+        "n": len(a),
+        "arch_lm": {"lm_stat": at.lm_stat, "lm_pvalue": at.lm_pvalue, "nlags": at.nlags,
+                    "has_arch": at.has_arch, "reference": at.reference},
+        "rolling": rolling_volatility(a, window=min(20, max(3, len(a) // 10))),
+    }
+    # Box-Cox lambda: Guerrero when a season is given, else MLE. Records the shift if non-positive.
+    try:
+        method = "guerrero" if (season_length and season_length >= 2) else "mle"
+        bc = box_cox(a, method=method, season_length=season_length)
+        out["boxcox"] = {"lambda": bc.lam, "method": bc.method, "shift": bc.shift, "reference": bc.reference}
+    except Exception as exc:  # noqa: BLE001 - record, do not crash the bake
+        out["boxcox"] = {"error": f"{type(exc).__name__}: {exc}"}
+    # Fit GARCH only when ARCH effects are actually present (else the model is not warranted).
+    if at.has_arch:
+        try:
+            g = garch(a, p=garch_pq[0], q=garch_pq[1])
+            out["garch"] = {"vol": g.vol, "p": g.p, "q": g.q, "params": g.params,
+                            "persistence": g.persistence, "loglikelihood": g.loglikelihood,
+                            "reference": g.reference}
+        except Exception as exc:  # noqa: BLE001
+            out["garch"] = {"error": f"{type(exc).__name__}: {exc}"}
+    else:
+        out["garch"] = {"skipped": "no significant ARCH effects (het_arch p >= alpha); GARCH not warranted"}
+    return out

forecastscope/forecasting.py

@@ -0,0 +1,263 @@
+"""Reference finite-prefix forecasts and Gaussian residual approximations.
+
+The extracted kernels retain their historical equations and preprocessing choices.
+Use the top-level forecastscope API for strict finite-input and output validation.
+They are repeated-prefix fits, not native incremental model-state updates.
+"""
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+
+import numpy as np
+
+from .types import MethodForecast
+
+# --- normal quantile: Acklam's rational approximation; not a coverage guarantee -------------------
+_A = [-3.969683028665376e01, 2.209460984245205e02, -2.759285104469687e02,
+      1.383577518672690e02, -3.066479806614716e01, 2.506628277459239e00]
+_B = [-5.447609879822406e01, 1.615858368580409e02, -1.556989798598866e02,
+      6.680131188771972e01, -1.328068155288572e01]
+_C = [-7.784894002430293e-03, -3.223964580411365e-01, -2.400758277161838e00,
+      -2.549732539343734e00, 4.374664141464968e00, 2.938163982698783e00]
+_D = [7.784695709041462e-03, 3.224671290700398e-01, 2.445134137142996e00, 3.754408661907416e00]
+
+
+def normal_ppf(p: float) -> float:
+    """Inverse standard-normal CDF (probit) via Acklam's approximation."""
+    if p <= 0.0:
+        return -math.inf
+    if p >= 1.0:
+        return math.inf
+    plow, phigh = 0.02425, 1 - 0.02425
+    if p < plow:
+        q = math.sqrt(-2 * math.log(p))
+        return (((((_C[0] * q + _C[1]) * q + _C[2]) * q + _C[3]) * q + _C[4]) * q + _C[5]) / \
+               ((((_D[0] * q + _D[1]) * q + _D[2]) * q + _D[3]) * q + 1)
+    if p > phigh:
+        q = math.sqrt(-2 * math.log(1 - p))
+        return -(((((_C[0] * q + _C[1]) * q + _C[2]) * q + _C[3]) * q + _C[4]) * q + _C[5]) / \
+               ((((_D[0] * q + _D[1]) * q + _D[2]) * q + _D[3]) * q + 1)
+    q = p - 0.5
+    r = q * q
+    return (((((_A[0] * r + _A[1]) * r + _A[2]) * r + _A[3]) * r + _A[4]) * r + _A[5]) * q / \
+           (((((_B[0] * r + _B[1]) * r + _B[2]) * r + _B[3]) * r + _B[4]) * r + 1)
+
+
+def _clean(y: np.ndarray) -> np.ndarray:
+    """Fill NaN by forward-fill then back-fill so recursive methods stay defined."""
+    y = np.asarray(y, dtype=float).copy()
+    if np.isnan(y).any():
+        idx = np.where(~np.isnan(y))[0]
+        if idx.size == 0:
+            return np.zeros_like(y)
+        y[: idx[0]] = y[idx[0]]
+        last = y[idx[0]]
+        for i in range(len(y)):
+            if np.isnan(y[i]):
+                y[i] = last
+            else:
+                last = y[i]
+    return y
+
+
+# --- individual methods: each returns (point_path (h,), one_step_sigma) -----------------------------
+def seasonal_naive(y: np.ndarray, m: int, h: int) -> tuple[np.ndarray, float]:
+    y = _clean(y)
+    m = m if (m >= 1 and y.shape[0] > m) else 1
+    season = y[-m:]
+    point = np.tile(season, int(np.ceil(h / m)))[:h]
+    resid = y[m:] - y[:-m]
+    sigma = float(np.std(resid)) if resid.size else 0.0
+    return point, sigma
+
+
+def _ses_run(y: np.ndarray, alpha: float) -> tuple[np.ndarray, float]:
+    """Return in-sample one-step fitted values and the final level for SES."""
+    level = y[0]
+    fitted = np.empty_like(y)
+    fitted[0] = level
+    for t in range(1, y.shape[0]):
+        fitted[t] = level
+        level = alpha * y[t] + (1 - alpha) * level
+    return fitted, level
+
+
+def _opt_alpha(y: np.ndarray) -> float:
+    grid = np.linspace(0.05, 0.95, 19)
+    best_a, best_sse = grid[0], math.inf
+    for a in grid:
+        fitted, _ = _ses_run(y, a)
+        sse = float(np.sum((y[1:] - fitted[1:]) ** 2))
+        if sse < best_sse:
+            best_sse, best_a = sse, a
+    return float(best_a)
+
+
+def ses(y: np.ndarray, m: int, h: int) -> tuple[np.ndarray, float]:
+    y = _clean(y)
+    a = _opt_alpha(y)
+    fitted, level = _ses_run(y, a)
+    sigma = float(np.std(y[1:] - fitted[1:])) if y.shape[0] > 1 else 0.0
+    return np.full(h, level), sigma
+
+
+def _holt_run(y: np.ndarray, alpha: float, beta: float) -> tuple[np.ndarray, float, float]:
+    level, trend = y[0], (y[1] - y[0] if y.shape[0] > 1 else 0.0)
+    fitted = np.empty_like(y)
+    fitted[0] = level
+    for t in range(1, y.shape[0]):
+        fitted[t] = level + trend
+        prev_level = level
+        level = alpha * y[t] + (1 - alpha) * (level + trend)
+        trend = beta * (level - prev_level) + (1 - beta) * trend
+    return fitted, level, trend
+
+
+def holt(y: np.ndarray, m: int, h: int) -> tuple[np.ndarray, float]:
+    y = _clean(y)
+    best = (0.3, 0.1)
+    best_sse = math.inf
+    for a in np.linspace(0.1, 0.9, 9):
+        for b in np.linspace(0.05, 0.5, 6):
+            fitted, _, _ = _holt_run(y, a, b)
+            sse = float(np.sum((y[1:] - fitted[1:]) ** 2))
+            if sse < best_sse:
+                best_sse, best = sse, (a, b)
+    fitted, level, trend = _holt_run(y, *best)
+    sigma = float(np.std(y[1:] - fitted[1:])) if y.shape[0] > 1 else 0.0
+    point = level + trend * np.arange(1, h + 1)
+    return point, sigma
+
+
+def _hw_run(y: np.ndarray, m: int, alpha: float, beta: float, gamma: float):
+    level = float(np.mean(y[:m]))
+    trend = float((np.mean(y[m:2 * m]) - np.mean(y[:m])) / m) if y.shape[0] >= 2 * m else 0.0
+    season = [float(y[i] - level) for i in range(m)]
+    fitted = np.empty_like(y)
+    for t in range(y.shape[0]):
+        s = season[t % m]
+        fitted[t] = level + trend + s
+        prev_level = level
+        level = alpha * (y[t] - s) + (1 - alpha) * (level + trend)
+        trend = beta * (level - prev_level) + (1 - beta) * trend
+        season[t % m] = gamma * (y[t] - level) + (1 - gamma) * s
+    return fitted, level, trend, season
+
+
+def holt_winters(y: np.ndarray, m: int, h: int) -> tuple[np.ndarray, float]:
+    y = _clean(y)
+    if m < 2 or y.shape[0] < 2 * m:
+        return holt(y, m, h)  # not enough seasons -> fall back to trend model
+    best, best_sse = (0.3, 0.1, 0.1), math.inf
+    for a in (0.1, 0.3, 0.5, 0.8):
+        for b in (0.05, 0.2):
+            for g in (0.1, 0.3, 0.6):
+                fitted, *_ = _hw_run(y, m, a, b, g)
+                sse = float(np.sum((y[m:] - fitted[m:]) ** 2))
+                if sse < best_sse:
+                    best_sse, best = sse, (a, b, g)
+    fitted, level, trend, season = _hw_run(y, m, *best)
+    sigma = float(np.std(y[m:] - fitted[m:])) if y.shape[0] > m else 0.0
+    # The next observation occupies phase n % m, including a partial final season.
+    point = np.array([level + trend * (k + 1) + season[(len(y) + k) % m] for k in range(h)])
+    return point, sigma
+
+
+def theta(y: np.ndarray, m: int, h: int) -> tuple[np.ndarray, float]:
+    """Nonseasonal Theta point equation (Hyndman and Billah, 2003, Eq. 5).
+
+    Alpha uses the documented finite grid and first-observation SES initialisation.
+    AutoTheta supplies automatic seasonal adjustment in the statistical engine.
+    """
+    y = _clean(y)
+    n = y.shape[0]
+    t = np.arange(n, dtype=float)
+    b = float(np.polyfit(t, y, 1)[0]) if n >= 2 else 0.0
+    a = _opt_alpha(y)
+    fitted, level = _ses_run(y, a)
+    sigma = float(np.std(y[1:] - fitted[1:])) if n > 1 else 0.0
+    lead = np.arange(1, h + 1)
+    point = level + 0.5 * b * (lead - 1 + (1 - (1 - a) ** n) / a)
+    return point, sigma
+
+
+METHODS: list[tuple[str, str, Callable[[np.ndarray, int, int], tuple[np.ndarray, float]]]] = [
+    ("SeasonalNaive", "classical", seasonal_naive),
+    ("SES", "classical", ses),
+    ("Holt", "classical", holt),
+    ("HoltWinters", "classical", holt_winters),
+    ("Theta", "classical", theta),
+]
+
+METHOD_FNS = {name: fn for name, _fam, fn in METHODS}
+
+
+def gaussian_quantiles(point: np.ndarray, sigma: float, levels: tuple[float, ...]) -> np.ndarray:
+    """Quantile columns from a point path + one-step sigma, widened by sqrt(step). Shape (h, len(levels))."""
+    steps = np.arange(1, point.shape[0] + 1)
+    widen = np.sqrt(steps)
+    cols = [point + normal_ppf(lv) * sigma * widen for lv in levels]
+    return np.maximum.accumulate(np.column_stack(cols), axis=1)  # keep quantiles monotone across levels
+
+
+def mf_from_quantiles(name: str, family: str, cols: np.ndarray, levels: tuple[float, ...]) -> MethodForecast:
+    """Build a MethodForecast (point = level nearest 0.5, outer interval = min/max levels) from quantile columns."""
+    point_col = int(np.argmin([abs(lv - 0.5) for lv in levels]))
+    return MethodForecast(
+        name=name, family=family,
+        point=tuple(round(float(v), 6) for v in cols[:, point_col]),
+        lower=tuple(round(float(v), 6) for v in cols[:, 0]),
+        upper=tuple(round(float(v), 6) for v in cols[:, -1]),
+    )
+
+
+def build_forecast(name: str, family: str, point: np.ndarray, sigma: float,
+                   levels: tuple[float, ...]) -> MethodForecast:
+    """Turn a point path + one-step sigma into a MethodForecast with an outer interval."""
+    return mf_from_quantiles(name, family, gaussian_quantiles(point, sigma, levels), levels)
+
+
+class Forecaster:
+    """Unifies a forecasting method for the pipeline: `quantiles` feeds the preqts backtest, `forecast`
+    feeds the trace. `max_windows` caps the rolling-backtest window count (cheap methods get more)."""
+
+    name: str
+    family: str
+    max_windows: int = 24
+
+    def quantiles(self, y: np.ndarray, m: int, h: int, levels: tuple[float, ...]) -> np.ndarray:
+        raise NotImplementedError
+
+    def forecast(self, y: np.ndarray, m: int, h: int, levels: tuple[float, ...]) -> MethodForecast:
+        return mf_from_quantiles(self.name, self.family, self.quantiles(y, m, h, levels), levels)
+
+
+class ClassicalForecaster(Forecaster):
+    """A pure-numpy classical method (Pyodide-safe): the live lane uses only these."""
+
+    def __init__(self, name: str, family: str, fn, max_windows: int = 24) -> None:
+        self.name = name
+        self.family = family
+        self.fn = fn
+        self.max_windows = max_windows
+
+    def quantiles(self, y: np.ndarray, m: int, h: int, levels: tuple[float, ...]) -> np.ndarray:
+        point, sigma = self.fn(np.asarray(y, dtype=float), m, h)
+        return gaussian_quantiles(point, sigma, levels)
+
+
+def classical_forecasters() -> list[ClassicalForecaster]:
+    """The pure-numpy classical ladder (shared by the offline pipeline and the live lane)."""
+    return [ClassicalForecaster(name, family, fn) for name, family, fn in METHODS]
+
+
+def forecast_all(y: np.ndarray, m: int, h: int, levels: tuple[float, ...]) -> list[MethodForecast]:
+    """Fit and forecast every CLASSICAL method (the live lane; no heavy engines). One MethodForecast each."""
+    return [fc.forecast(np.asarray(y, dtype=float), m, h, levels) for fc in classical_forecasters()]
+
+
+def forecast_point(name: str, y: np.ndarray, m: int, h: int) -> np.ndarray:
+    """Just the point path for one classical method (used by tests/diagnostics)."""
+    point, _sigma = METHOD_FNS[name](np.asarray(y, dtype=float), m, h)
+    return point