forecastscope 0.1.0__py3-none-any.whl

forecastscope/diagnostics/nonlinear.py

@@ -0,0 +1,267 @@
+"""Nonlinear dynamics and chaos: phase-space embedding, correlation dimension, Lyapunov, RQA, 0-1, surrogates.
+
+Is the series the output of a low-dimensional deterministic (possibly chaotic) system, or is it stochastic?
+This distinction bounds forecastability: a chaotic system is deterministic yet has a finite prediction
+horizon (errors grow like e^{lambda t}), while a stochastic one has no such structure to exploit. The tools
+here reconstruct the state space (Takens), measure its dimension (Grassberger-Procaccia) and its sensitivity
+to initial conditions (largest Lyapunov exponent), visualize recurrences (RQA), and - crucially - guard every
+"it's chaotic" claim behind SURROGATE testing, because colored noise can mimic a low correlation dimension.
+
+Methods / references (verified 2026-07-04; dossier research-nonlinear-dynamics-2026-07-04.md):
+  * Takens time-delay embedding - Takens 1981, LNM 898:366-381, DOI 10.1007/BFb0091924.
+  * Correlation dimension D2 (Grassberger-Procaccia) - 1983, Physica D 9:189-208,
+    DOI 10.1016/0167-2789(83)90298-1. ``nolds.corr_dim``.
+  * Largest Lyapunov exponent - Rosenstein et al. 1993, Physica D 65:117-134,
+    DOI 10.1016/0167-2789(93)90009-P. ``nolds.lyap_r``.
+  * Recurrence plots + RQA - Eckmann, Kamphorst & Ruelle 1987, EPL 4(9):973-977,
+    DOI 10.1209/0295-5075/4/9/004; Marwan et al. 2007, Phys. Rep. 438:237-329,
+    DOI 10.1016/j.physrep.2006.11.001. RQA implemented directly (RR/DET/LAM/L_max).
+  * IAAFT surrogates - Schreiber & Schmitz 1996, PRL 77:635-638, DOI 10.1103/PhysRevLett.77.635; the
+    surrogate-data method: Theiler et al. 1992, Physica D 58:77-94, DOI 10.1016/0167-2789(92)90102-S.
+
+HONESTY GATE: Osborne & Provenzale 1989 showed colored noise yields a finite, saturating correlation
+dimension - so a low D2 alone does NOT prove chaos. The unit requires the surrogate test (a nonlinear
+statistic must differ from phase-randomized surrogates) before any determinism/chaos claim.
+"""
+from __future__ import annotations
+
+import warnings
+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)]
+
+
+def time_delay_embed(x, dim: int = 3, lag: int = 1) -> np.ndarray:
+    """Takens embedding: rows are state vectors [x_t, x_{t+lag}, ..., x_{t+(dim-1)lag}]."""
+    a = _clean(x)
+    n = len(a) - (dim - 1) * lag
+    if n <= 0:
+        raise ValueError("series too short for this embedding dim/lag")
+    return np.column_stack([a[i * lag: i * lag + n] for i in range(dim)])
+
+
+@dataclass(frozen=True)
+class ChaosMeasures:
+    """Correlation dimension + largest Lyapunov exponent, with a (surrogate-gated) chaos verdict."""
+
+    corr_dim: float
+    lyap_r: float
+    emb_dim: int
+    lag: int
+    likely_chaotic: bool         # lyap_r > 0 AND the surrogate test rejects linearity (set by caller)
+    reference: str
+
+
+def _seeded_slope(debug, seed: int) -> float:
+    """Fit nolds' exposed log-data with its robust model and an isolated seed."""
+    from sklearn.linear_model import LinearRegression, RANSACRegressor
+    from sklearn.preprocessing import PolynomialFeatures
+
+    x, y, _ = debug
+    x, y = np.asarray(x), np.asarray(y)
+    keep = np.isfinite(x) & np.isfinite(y)
+    x, y = x[keep], y[keep]
+    if len(x) < 2:
+        return float("nan")
+    model = RANSACRegressor(LinearRegression(fit_intercept=False), random_state=seed)
+    try:
+        model.fit(PolynomialFeatures(1).fit_transform(x.reshape(-1, 1)), y)
+        return float(model.estimator_.coef_[-1])
+    except ValueError:
+        return float(np.polyfit(x, y, 1)[0])
+
+
+def chaos_measures(x, emb_dim: int = 4, lag: int = 1, seed: int = 0) -> ChaosMeasures:
+    """Grassberger-Procaccia correlation dimension + Rosenstein largest Lyapunov exponent (nolds)."""
+    import nolds
+
+    a = _clean(x)
+    if not isinstance(seed, int) or not 0 <= seed < 2**32:
+        raise ValueError("seed must be a nonnegative 32-bit integer")
+    _, d2_debug = nolds.corr_dim(a, emb_dim=emb_dim, lag=lag, fit="poly", debug_data=True)
+    d2 = _seeded_slope(d2_debug, seed)
+    # Rosenstein largest Lyapunov: positive => sensitive dependence (a chaos signature, not proof)
+    try:
+        _, lyap_debug = nolds.lyap_r(a, emb_dim=emb_dim, lag=lag, min_tsep=max(5, len(a) // 200),
+                                    fit="poly", debug_data=True)
+        lyap = _seeded_slope(lyap_debug, (seed + 1) % 2**32)
+    except Exception:  # noqa: BLE001
+        lyap = float("nan")
+    return ChaosMeasures(
+        corr_dim=d2, lyap_r=lyap, emb_dim=emb_dim, lag=lag,
+        likely_chaotic=False,   # only the surrogate-gated report sets this True
+        reference="Grassberger & Procaccia 1983, DOI 10.1016/0167-2789(83)90298-1; Rosenstein et al. 1993, DOI 10.1016/0167-2789(93)90009-P",
+    )
+
+
+@dataclass(frozen=True)
+class RQA:
+    """Recurrence quantification: recurrence rate, determinism, laminarity, longest diagonal line."""
+
+    recurrence_rate: float       # RR: density of recurrence points
+    determinism: float           # DET: fraction of recurrence points on diagonal lines (predictability)
+    laminarity: float            # LAM: fraction on vertical lines (intermittency / laminar states)
+    l_max: int                   # longest diagonal line (inversely related to the largest Lyapunov)
+    threshold: float
+    reference: str
+
+
+def recurrence_quantification(x, emb_dim: int = 3, lag: int = 1, rr_target: float = 0.1,
+                              l_min: int = 2, max_n: int = 800) -> RQA:
+    """Build the recurrence matrix at a threshold giving ~rr_target density, then quantify it (RQA).
+
+    Following Marwan et al. 2007: recurrence R(i,j) = 1 iff ||v_i - v_j|| < eps, with eps chosen to hit a
+    target recurrence rate. DET = fraction of recurrence points forming diagonal lines of length >= l_min
+    (determinism); LAM = fraction forming vertical lines (laminarity); L_max = longest diagonal.
+    """
+    v = time_delay_embed(x, dim=emb_dim, lag=lag)
+    n = v.shape[0]
+    if n > max_n:                                         # truncate (not subsample) to keep diagonals intact:
+        v = v[:max_n]                                     # decimating would break the temporal continuity RQA needs
+        n = v.shape[0]
+    # pairwise Euclidean distances
+    diff = v[:, None, :] - v[None, :, :]
+    dist = np.sqrt((diff ** 2).sum(axis=2))
+    eps = float(np.quantile(dist, rr_target))             # threshold hitting ~rr_target density
+    rec = (dist < eps).astype(np.int8)
+    np.fill_diagonal(rec, 0)                              # exclude the trivial main diagonal (LOI)
+    rr = float(rec.sum() / (n * (n - 1)))
+    # diagonal-line lengths (determinism) and vertical-line lengths (laminarity)
+    diag_lengths = _line_lengths_diagonal(rec)
+    vert_lengths = _line_lengths_vertical(rec)
+    total_points = int(rec.sum())
+    det = float(sum(l for l in diag_lengths if l >= l_min) / total_points) if total_points else 0.0
+    lam = float(sum(l for l in vert_lengths if l >= l_min) / total_points) if total_points else 0.0
+    l_max = int(max(diag_lengths)) if diag_lengths else 0
+    return RQA(
+        recurrence_rate=rr, determinism=det, laminarity=lam, l_max=l_max, threshold=eps,
+        reference="Eckmann, Kamphorst & Ruelle 1987, DOI 10.1209/0295-5075/4/9/004; Marwan et al. 2007, DOI 10.1016/j.physrep.2006.11.001",
+    )
+
+
+def _line_lengths_diagonal(rec: np.ndarray) -> list[int]:
+    """Lengths of consecutive-1 runs along all off-main diagonals (both triangles) of the recurrence matrix.
+
+    The matrix is symmetric, so we count both the positive and negative offsets: this matches the denominator
+    (the full recurrence-point count ``rec.sum()``) so DET is the true fraction of points on diagonal lines.
+    """
+    n = rec.shape[0]
+    lengths: list[int] = []
+    for k in range(1, n):
+        lengths.extend(_runs(np.diagonal(rec, offset=k)))     # upper triangle
+        lengths.extend(_runs(np.diagonal(rec, offset=-k)))    # lower triangle
+    return lengths
+
+
+def _line_lengths_vertical(rec: np.ndarray) -> list[int]:
+    """Lengths of consecutive-1 runs down each column (vertical lines)."""
+    lengths: list[int] = []
+    for col in rec.T:
+        lengths.extend(_runs(col))
+    return lengths
+
+
+def _runs(v: np.ndarray) -> list[int]:
+    """Lengths of maximal runs of 1s in a 0/1 vector."""
+    out: list[int] = []
+    run = 0
+    for val in v:
+        if val:
+            run += 1
+        elif run:
+            out.append(run)
+            run = 0
+    if run:
+        out.append(run)
+    return out
+
+
+def iaaft_surrogate(x, n_iter: int = 100, seed: int = 0) -> np.ndarray:
+    """One IAAFT surrogate: same amplitude distribution AND power spectrum, but linearized dynamics.
+
+    Schreiber & Schmitz 1996. If a nonlinear statistic on the data differs from an ensemble of these
+    surrogates, the difference is genuine nonlinear structure, not an artifact of the spectrum/distribution.
+    """
+    a = _clean(x)
+    rng = np.random.default_rng(seed)
+    sorted_a = np.sort(a)
+    amp = np.abs(np.fft.rfft(a))
+    s = rng.permutation(a)
+    for _ in range(n_iter):
+        # match the power spectrum
+        S = np.fft.rfft(s)
+        S = amp * np.exp(1j * np.angle(S))
+        s = np.fft.irfft(S, n=len(a))
+        # match the amplitude distribution (rank-order remap)
+        ranks = np.argsort(np.argsort(s))
+        s = sorted_a[ranks]
+    return s
+
+
+def zero_one_test(x, n_c: int = 100, seed: int = 0) -> float:
+    """Gottwald-Melbourne 0-1 test for chaos: K near 1 => chaotic, near 0 => regular (Gottwald & Melbourne 2004).
+
+    For random phases c, drive p_c(n) = sum x_j cos(j c), q_c(n) = sum x_j sin(j c); the mean-square
+    displacement M_c(n) grows linearly (K~1) for chaos and stays bounded (K~0) for regular dynamics. K is the
+    median asymptotic growth rate over the random phases.
+    """
+    a = _clean(x)
+    n = len(a)
+    rng = np.random.default_rng(seed)
+    a = a - a.mean()
+    ncut = n // 10
+    ks = []
+    for _ in range(n_c):
+        c = rng.uniform(np.pi / 5, 4 * np.pi / 5)
+        j = np.arange(1, n + 1)
+        p = np.cumsum(a * np.cos(j * c))
+        q = np.cumsum(a * np.sin(j * c))
+        M = np.array([np.mean((p[:n - k] - p[k:]) ** 2 + (q[:n - k] - q[k:]) ** 2) for k in range(1, ncut)])
+        t = np.arange(1, ncut)
+        # correlation of M with linear growth -> K
+        if np.std(M) > 0:
+            ks.append(float(np.corrcoef(t, M)[0, 1]))
+    return float(np.median(ks)) if ks else float("nan")
+
+
+def nonlinear_report(x, emb_dim: int = 4, lag: int = 1, n_surrogates: int = 19, seed: int = 0) -> dict:
+    """Full nonlinear-dynamics panel WITH the surrogate gate: chaos claims require surrogate rejection."""
+    a = _clean(x)
+    cm = chaos_measures(a, emb_dim=emb_dim, lag=lag, seed=seed)
+    rqa = recurrence_quantification(a, emb_dim=emb_dim, lag=lag)
+    k01 = zero_one_test(a, seed=seed)
+    # surrogate test: compare the data's correlation dimension to an ensemble of IAAFT surrogates.
+    surr_d2 = []
+    for i in range(n_surrogates):
+        try:
+            surrogate_seed = (seed + i + 2) % 2**32
+            s = iaaft_surrogate(a, seed=surrogate_seed)
+            surr_d2.append(chaos_measures(s, emb_dim=emb_dim, lag=lag, seed=surrogate_seed).corr_dim)
+        except Exception:  # noqa: BLE001
+            warnings.warn("Surrogate diagnostic unavailable", RuntimeWarning, stacklevel=2)
+    nonlinear_detected = None
+    if surr_d2:
+        mu, sd = float(np.mean(surr_d2)), float(np.std(surr_d2))
+        # data D2 significantly LOWER than surrogates => genuine (nonlinear) low-dim structure
+        nonlinear_detected = bool(sd > 0 and cm.corr_dim < mu - 2 * sd)
+    likely_chaotic = bool((cm.lyap_r > 0.01) and (k01 > 0.5) and (nonlinear_detected is True))
+    return {
+        "n": len(a),
+        "seed": seed,
+        "fit": "RANSAC with explicit random_state; OLS on no consensus",
+        "correlation_dimension": cm.corr_dim,
+        "largest_lyapunov": cm.lyap_r,
+        "zero_one_K": k01,
+        "rqa": {"recurrence_rate": rqa.recurrence_rate, "determinism": rqa.determinism,
+                "laminarity": rqa.laminarity, "l_max": rqa.l_max, "reference": rqa.reference},
+        "surrogate_test": {"n_surrogates": len(surr_d2), "nonlinear_detected": nonlinear_detected,
+                           "reference": "Schreiber & Schmitz 1996, DOI 10.1103/PhysRevLett.77.635 (IAAFT); Theiler et al. 1992, DOI 10.1016/0167-2789(92)90102-S"},
+        "likely_chaotic": likely_chaotic,
+        "verdict_note": "chaos claimed only when Lyapunov>0 AND 0-1 K>0.5 AND surrogate rejects linearity",
+        "reference": cm.reference,
+    }

forecastscope/diagnostics/seasonality.py

@@ -0,0 +1,218 @@
+"""Seasonality analysis: periodogram/Welch dominant period, seasonal strength, MSTL, seasonal subseries.
+
+Seasonality is a pattern repeating at a fixed period m (a day, a week, a year). This module answers the four
+questions a forecaster asks before choosing a seasonal model: (1) is there a dominant period at all, and what
+is it? (2) how strong is the seasonality (and is it worth modelling)? (3) are there MULTIPLE seasonal periods
+(e.g. daily + weekly)? (4) what does the per-phase seasonal profile look like? Each answer is delegated to
+its authoritative implementation and wrapped in one stable, NaN-safe API that carries the primary reference.
+
+Methods / references (verified 2026-07-04):
+  * Periodogram (Schuster 1898) / Welch (1967) - the squared magnitude of the FFT; the tallest non-DC peak
+    gives the dominant period. ``scipy.signal.periodogram`` / ``scipy.signal.welch``.
+  * Seasonal strength Fs = max(0, 1 - Var(R)/Var(S+R)) from an STL decomposition - Wang, Smith & Hyndman
+    2006, DOI 10.1007/s10618-005-0039-x; strength form per FPP3 sec. 4.3 (the F_S >= 0.64 threshold drives
+    ``nsdiffs``). Re-implemented here so seasonality does not import stationarity.
+  * MSTL - multiple-seasonal STL. Bandara, Hyndman & Bergmeir 2021, arXiv:2107.13462. ``statsmodels.MSTL``.
+  * Seasonal subseries - the per-phase means + the per-phase series; the standard "month plot" (Cleveland &
+    Terpenning 1982, JASA 77(377), DOI 10.1080/01621459.1982.10477766).
+
+NOTE: ``scipy.signal.cwt`` is DEPRECATED (1.12) and REMOVED (1.15); wavelet/scalogram seasonality uses
+PyWavelets elsewhere. Here we stay on FFT-based spectral estimation, which scipy keeps.
+"""
+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 Spectrum:
+    """A spectral density estimate (periodogram or Welch) over positive frequencies, with the dominant peak."""
+
+    name: str
+    freqs: np.ndarray
+    power: np.ndarray
+    dominant_period: float | None
+    dominant_power: float
+    reference: str
+
+
+def periodogram(x, fs: float = 1.0) -> Spectrum:
+    """Schuster periodogram; the dominant period is 1 / (the tallest non-DC frequency)."""
+    from scipy.signal import periodogram as _periodogram
+
+    a = _clean(x)
+    f, pxx = _periodogram(a, fs=fs)
+    if len(f) > 1:
+        idx = 1 + int(np.argmax(pxx[1:]))   # skip the DC (zero-frequency) bin
+        dom_freq = float(f[idx])
+        dom_power = float(pxx[idx])
+        dom_period = (1.0 / dom_freq) if dom_freq > 0 else None
+    else:
+        dom_period, dom_power = None, 0.0
+    return Spectrum(
+        name="Periodogram", freqs=f, power=pxx, dominant_period=dom_period, dominant_power=dom_power,
+        reference="Schuster 1898, Terrestrial Magnetism 3(1):13-41; scipy.signal.periodogram",
+    )
+
+
+def welch(x, fs: float = 1.0, nperseg: int | None = None) -> Spectrum:
+    """Welch's averaged periodogram (lower variance, coarser resolution) and its dominant period."""
+    from scipy.signal import welch as _welch
+
+    a = _clean(x)
+    nperseg = min(nperseg or 256, len(a))
+    f, pxx = _welch(a, fs=fs, nperseg=nperseg)
+    if len(f) > 1:
+        idx = 1 + int(np.argmax(pxx[1:]))
+        dom_freq = float(f[idx])
+        dom_power = float(pxx[idx])
+        dom_period = (1.0 / dom_freq) if dom_freq > 0 else None
+    else:
+        dom_period, dom_power = None, 0.0
+    return Spectrum(
+        name="Welch", freqs=f, power=pxx, dominant_period=dom_period, dominant_power=dom_power,
+        reference="Welch 1967, IEEE Trans. Audio Electroacoust. 15(2):70-73, DOI 10.1109/TAU.1967.1161901",
+    )
+
+
+def seasonal_strength(x, period: int) -> float:
+    """F_S = max(0, 1 - Var(remainder)/Var(seasonal+remainder)) from a robust STL fit. 0 if too short."""
+    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))
+
+
+@dataclass(frozen=True)
+class Decomp:
+    """An additive decomposition into trend + seasonal + remainder, with the trend/seasonal strength scores."""
+
+    trend: np.ndarray
+    seasonal: np.ndarray
+    remainder: np.ndarray
+    strength_trend: float
+    strength_seasonal: float
+    periods: tuple[int, ...]
+    reference: str
+
+
+def _strengths(trend, seasonal, remainder) -> tuple[float, float]:
+    var_r = float(np.var(remainder)) or 1e-12
+    var_tr = float(np.var(trend + remainder)) or 1e-12
+    var_sr = float(np.var(seasonal + remainder)) or 1e-12
+    f_t = max(0.0, 1.0 - var_r / var_tr)
+    f_s = max(0.0, 1.0 - var_r / var_sr)
+    return f_t, f_s
+
+
+def stl_decompose(x, period: int) -> Decomp:
+    """STL (Cleveland et al. 1990) additive decomposition at a single ``period``."""
+    from statsmodels.tsa.seasonal import STL
+
+    a = _clean(x)
+    if period < 2 or len(a) < 2 * period:
+        raise ValueError(f"STL needs len >= 2*period; got len={len(a)}, period={period}")
+    res = STL(a, period=period, robust=True).fit()
+    f_t, f_s = _strengths(res.trend, res.seasonal, res.resid)
+    return Decomp(
+        trend=np.asarray(res.trend, dtype=float), seasonal=np.asarray(res.seasonal, dtype=float),
+        remainder=np.asarray(res.resid, dtype=float), strength_trend=f_t, strength_seasonal=f_s,
+        periods=(int(period),),
+        reference="Cleveland, Cleveland, McRae & Terpenning 1990, J. Official Statistics 6(1):3-73 (STL)",
+    )
+
+
+def mstl_decompose(x, periods: list[int]) -> Decomp:
+    """MSTL: multiple-seasonal STL (daily + weekly + ...) additive decomposition."""
+    from statsmodels.tsa.seasonal import MSTL
+
+    a = _clean(x)
+    periods = [int(p) for p in periods if int(p) >= 2]
+    if not periods:
+        raise ValueError("MSTL needs at least one period >= 2")
+    if len(a) < 2 * max(periods):
+        raise ValueError(f"MSTL needs len >= 2*max(periods); got len={len(a)}, max period={max(periods)}")
+    res = MSTL(a, periods=periods).fit()
+    seasonal_2d = np.asarray(res.seasonal, dtype=float)
+    # MSTL returns one seasonal column per period; sum them into a single additive seasonal component.
+    seasonal = seasonal_2d.sum(axis=1) if seasonal_2d.ndim == 2 else seasonal_2d
+    trend = np.asarray(res.trend, dtype=float)
+    remainder = np.asarray(res.resid, dtype=float)
+    f_t, f_s = _strengths(trend, seasonal, remainder)
+    return Decomp(
+        trend=trend, seasonal=seasonal, remainder=remainder, strength_trend=f_t, strength_seasonal=f_s,
+        periods=tuple(periods),
+        reference="Bandara, Hyndman & Bergmeir 2021, MSTL, arXiv:2107.13462; statsmodels.tsa.seasonal.MSTL",
+    )
+
+
+@dataclass(frozen=True)
+class SeasonalSubseries:
+    """The per-phase (per-season) means + the per-phase series, for the standard month/subseries plot."""
+
+    period: int
+    means: np.ndarray            # length = period: the mean of each phase
+    profiles: list[np.ndarray]   # one array per phase, each the values that landed in that phase
+
+
+def seasonal_subseries(x, period: int) -> SeasonalSubseries:
+    """Split the series into cycles of length ``period``; return the per-phase mean and per-phase values."""
+    a = _clean(x)
+    if period < 2:
+        raise ValueError("period must be >= 2")
+    n_full = (len(a) // period) * period
+    if n_full == 0:
+        raise ValueError("series shorter than one period")
+    trimmed = a[:n_full]
+    cycles = trimmed.reshape(-1, period)             # rows = cycles, cols = phases
+    means = cycles.mean(axis=0)
+    profiles = [cycles[:, j] for j in range(period)]
+    return SeasonalSubseries(period=int(period), means=means, profiles=profiles)
+
+
+def seasonality_report(x, fs: float = 1.0, candidate_periods: list[int] | None = None) -> dict:
+    """Run the full seasonality panel: periodogram + Welch + per-candidate strength + (optional) MSTL."""
+    a = _clean(x)
+    pg = periodogram(a, fs=fs)
+    wl = welch(a, fs=fs)
+    candidates = candidate_periods or []
+    strengths = {int(p): float(seasonal_strength(a, int(p))) for p in candidates if int(p) >= 2}
+    out = {
+        "n": len(a),
+        "periodogram": {
+            "dominant_period": pg.dominant_period, "dominant_power": pg.dominant_power,
+            "freqs": pg.freqs.tolist(), "power": pg.power.tolist(), "reference": pg.reference,
+        },
+        "welch": {
+            "dominant_period": wl.dominant_period, "dominant_power": wl.dominant_power,
+            "reference": wl.reference,
+        },
+        "seasonal_strength_by_candidate_period": strengths,
+    }
+    # If the periodogram found a dominant period, also report STL strength at that period.
+    if pg.dominant_period is not None and pg.dominant_period >= 2:
+        p_int = round(pg.dominant_period)
+        if p_int >= 2 and len(a) >= 2 * p_int:
+            out["stl_at_dominant"] = _decomp_dict(stl_decompose(a, p_int))
+    return out
+
+
+def _decomp_dict(d: Decomp) -> dict:
+    return {
+        "strength_trend": d.strength_trend, "strength_seasonal": d.strength_seasonal,
+        "periods": list(d.periods), "reference": d.reference,
+    }

forecastscope/diagnostics/sequence.py

@@ -0,0 +1,130 @@
+"""Retrospective sequence diagnostics on original, contiguous observations.
+
+Matrix Profile/FLUSS: Yeh et al. 2016, DOI 10.1109/ICDM.2016.0179;
+Gharghabi et al. 2017, DOI 10.1109/ICDM.2017.21 (STUMPY implementation).
+Multiscale entropy: Costa et al. 2002, DOI 10.1103/PhysRevLett.89.068102.
+Lempel-Ziv: Lempel & Ziv 1976, DOI 10.1109/TIT.1976.1055501.
+Time reversal: the third-order lag statistic documented by tsfresh.
+"""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+
+def finite_sequence(x) -> np.ndarray:
+    a = np.asarray(x, dtype=float)
+    if a.ndim != 1 or len(a) < 3 or not np.isfinite(a).all():
+        raise ValueError("A contiguous finite one-dimensional sequence of at least three observations is required")
+    return a
+
+
+def matrix_profile(x, window: int = 32, regimes: int = 3) -> dict:
+    """Exact z-normalized self join; candidates are descriptive, never causal alarms."""
+    import stumpy
+
+    a = finite_sequence(x)
+    if not isinstance(window, int) or window < 3 or len(a) < 2 * window + 1:
+        raise ValueError("Matrix Profile requires an integer window >=3 and n >= 2*window+1")
+    if not isinstance(regimes, int) or regimes < 2:
+        raise ValueError("FLUSS requires at least two candidate regimes")
+    if np.std(a) == 0:
+        return {"available": False, "reason": "constant sequence has no discriminating shape profile",
+                "n": len(a), "window": window}
+    mp = stumpy.stump(a, m=window)
+    distances = np.asarray(mp.P_, dtype=float)
+    neighbors = np.asarray(mp.I_, dtype=int)
+    motifs = []
+    for i in np.argsort(distances, kind="stable"):
+        j = int(neighbors[i])
+        if np.isfinite(distances[i]) and j >= 0 and abs(int(i)-j) >= window:
+            motifs.append({"start": int(i), "match": j, "distance": float(distances[i])})
+            break
+    discords = []
+    for i in np.argsort(-distances, kind="stable"):
+        if np.isfinite(distances[i]) and all(abs(int(i)-d['start']) >= window for d in discords):
+            discords.append({"start": int(i), "distance": float(distances[i])})
+            if len(discords) == 3:
+                break
+    cac, boundaries = stumpy.fluss(neighbors, L=window, n_regimes=regimes, excl_factor=1)
+    return {"available": True, "n": len(a), "window": window,
+            "exclusion_zone": math.ceil(window / stumpy.config.STUMPY_EXCL_ZONE_DENOM),
+            "profile": [float(v) if np.isfinite(v) else None for v in distances],
+            "nearest_neighbor": neighbors.tolist(), "motifs": motifs, "discords": discords,
+            "corrected_arc_curve": np.asarray(cac, dtype=float).tolist(),
+            "regime_boundaries": sorted(int(b) for b in boundaries if 0 < int(b) < len(distances)),
+            "regimes_requested": regimes, "normalization": "per-window population-standard-deviation z scores",
+            "note": "Retrospective shape candidates, not anomaly probabilities or proven regime changes."}
+
+
+def multiscale_entropy(x, scales=tuple(range(1, 11)), order: int = 2, tolerance_ratio: float = .15) -> dict:
+    """Costa coarse-graining, with original-series tolerance and no self matches.
+
+    Both m and m+1 templates use the same n-m start positions. Matching uses <= r
+    Chebyshev distance; finite-sample no-match estimates remain unavailable.
+    """
+    from scipy.spatial import cKDTree
+
+    a = finite_sequence(x)
+    if order < 1 or not isinstance(order, int) or not 0 < tolerance_ratio < 1:
+        raise ValueError("Invalid entropy order or tolerance ratio")
+    scales = tuple(scales)
+    if not scales or any(not isinstance(s, int) or s < 1 for s in scales) or len(set(scales)) != len(scales):
+        raise ValueError("Scales must be distinct positive integers")
+    tolerance = float(tolerance_ratio * np.std(a))
+    rows = []
+    for scale in scales:
+        coarse = a[:len(a)//scale*scale].reshape(-1, scale).mean(axis=1)
+        row = {"scale": scale, "n": len(coarse), "tolerance": tolerance, "entropy": None,
+               "matching_m": 0, "matching_m_plus_one": 0}
+        if len(coarse) < max(20, order + 3):
+            row["reason"] = "fewer than twenty coarse-grained observations"
+        else:
+            templates = np.lib.stride_tricks.sliding_window_view(coarse, order + 1)
+            counts = []
+            for dimension in (order, order + 1):
+                tree = cKDTree(templates[:, :dimension])
+                counts.append(int((tree.count_neighbors(tree, tolerance, p=np.inf) - len(templates)) // 2))
+            b, matches = counts
+            row.update(matching_m=b, matching_m_plus_one=matches)
+            if matches and b:
+                row["entropy"] = float(-np.log(matches / b))
+            else:
+                row["reason"] = "no matching templates; finite sample entropy is unavailable"
+        rows.append(row)
+    return {"order": order, "tolerance_ratio": tolerance_ratio, "tolerance_basis": "original population standard deviation",
+            "scales": rows}
+
+
+def time_reversal(x, lag: int = 1) -> dict:
+    """E[x[t+2l]^2*x[t+l] - x[t+l]*x[t]^2], raw and standardized."""
+    a = finite_sequence(x)
+    if not isinstance(lag, int) or lag < 1 or len(a) <= 2 * lag:
+        raise ValueError("Time-reversal lag requires n > 2*lag")
+
+    def statistic(values):
+        return float(np.mean(values[lag:-lag] * (values[2*lag:]**2 - values[:-2*lag]**2)))
+
+    sd = np.std(a)
+    return {"lag": lag, "raw": statistic(a), "standardized": statistic((a-np.mean(a))/sd) if sd else 0.0,
+            "note": "A descriptive third-order statistic; no significance or irreversibility verdict is inferred."}
+
+
+def sequence_report(x, seasonality: int = 1, window: int | None = None) -> dict:
+    """One JSON-ready contract for offline case diagnostics and the browser consumer."""
+    import antropy
+
+    a = finite_sequence(x)
+    chosen = window if window is not None else min(max(8, 2*seasonality), 64, len(a)//3)
+    profile = matrix_profile(a, window=chosen) if chosen >= 3 and len(a) >= 2*chosen+1 else {
+        "available": False, "reason": "sequence too short for the profile", "n": len(a), "window": chosen}
+    symbols = (a > np.median(a)).astype(int)
+    return {"n": len(a), "observation_indices": list(range(len(a))), "values": a.tolist(),
+            "matrix_profile": profile, "multiscale_entropy": multiscale_entropy(a),
+            "lempel_ziv": {"raw": int(antropy.lziv_complexity(symbols, normalize=False)),
+                           "normalized": float(antropy.lziv_complexity(symbols, normalize=True)),
+                           "threshold": float(np.median(a)), "alphabet": "0 if x<=median, 1 otherwise",
+                           "normalization": "c(n)*log2(n)/n; finite samples can exceed one"},
+            "time_reversal": [time_reversal(a, lag) for lag in (1, 2, 7) if len(a) > 2*lag],
+            "interpretation": "Retrospective full-sequence diagnostics; not input to a forecast at an earlier origin."}