forecastscope 0.1.0__py3-none-any.whl

forecastscope/diagnostics/distribution.py

@@ -0,0 +1,180 @@
+"""Distribution, normality, and entropy/complexity: the value-distribution and predictability diagnostics.
+
+Two facets of "what kind of values does this series take, and how predictable is its pattern?": (1) the
+DISTRIBUTION of the values (shape, tails, normality) and (2) the COMPLEXITY of the ordering (entropy measures
+that quantify regularity vs randomness, and a nonlinearity test). Together they answer whether Gaussian
+assumptions hold and how much exploitable structure the sequence carries.
+
+Methods / references (verified 2026-07-04):
+  * Summary moments - mean, variance, skewness (asymmetry), kurtosis (tail-heaviness). Standard.
+  * KDE - Gaussian kernel density estimate. Parzen 1962, Ann. Math. Stat. 33(3):1065-1076,
+    DOI 10.1214/aoms/1177704472. ``scipy.stats.gaussian_kde``.
+  * Q-Q plot - sample vs theoretical (normal) quantiles. Wilk & Gnanadesikan 1968, Biometrika 55(1):1-17,
+    DOI 10.1093/biomet/55.1.1. ``scipy.stats.probplot``.
+  * Jarque-Bera - normality from skew+kurtosis; large-sample. Jarque & Bera 1980, Economics Letters
+    6(3):255-259, DOI 10.1016/0165-1765(80)90024-5. ``scipy.stats.jarque_bera``.
+  * Shapiro-Wilk - most powerful normality test for small/moderate n. Shapiro & Wilk 1965, Biometrika
+    52(3-4):591-611, DOI 10.1093/biomet/52.3-4.591. ``scipy.stats.shapiro``.
+  * Sample entropy - bias-corrected regularity (lower = more predictable). Richman & Moorman 2000,
+    Am. J. Physiol. 278(6):H2039-H2049, DOI 10.1152/ajpheart.2000.278.6.H2039. ``antropy.sample_entropy``.
+  * Permutation entropy - ordinal-pattern entropy, noise-robust. Bandt & Pompe 2002, PRL 88:174102,
+    DOI 10.1103/PhysRevLett.88.174102. ``antropy.perm_entropy``.
+  * Spectral entropy - Shannon entropy of the normalized PSD (flat spectrum = high). ``antropy.spectral_entropy``.
+  * BDS test - i.i.d. vs hidden nonlinear structure via the correlation integral. Broock, Scheinkman,
+    Dechert & LeBaron 1996, Econometric Reviews 15(3):197-235, DOI 10.1080/07474939608800353.
+    ``statsmodels.tsa.stattools.bds``.
+  * catch22 - 22 canonical features (Lubba et al. 2019, DOI 10.1007/s10618-019-00647-x). OPTIONAL: pycatch22
+    needs a C toolchain to build; when unavailable the report records that honestly rather than faking it.
+"""
+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)]
+
+
+@dataclass(frozen=True)
+class DistributionSummary:
+    """Moments + normality verdicts + a KDE/Q-Q payload for the distribution panel."""
+
+    n: int
+    mean: float
+    std: float
+    skewness: float
+    kurtosis_excess: float       # excess kurtosis (0 = normal); >0 heavy-tailed
+    jarque_bera_stat: float
+    jarque_bera_pvalue: float
+    shapiro_stat: float | None
+    shapiro_pvalue: float | None
+    normal: bool                 # combined verdict at alpha (both tests non-significant where applicable)
+    reference: str
+
+
+def summary(x, alpha: float = 0.05) -> DistributionSummary:
+    """Moments + Jarque-Bera + Shapiro-Wilk (n <= 5000) with a combined normality verdict."""
+    from scipy import stats
+
+    a = _clean(x)
+    n = len(a)
+    skew = float(stats.skew(a))
+    kurt = float(stats.kurtosis(a, fisher=True))         # excess kurtosis
+    jb_stat, jb_p = stats.jarque_bera(a)
+    sh_stat, sh_p = (None, None)
+    if 3 <= n <= 5000:                                    # Shapiro is defined/reliable in this range
+        sh = stats.shapiro(a)
+        sh_stat, sh_p = float(sh[0]), float(sh[1])
+    normal = bool(jb_p >= alpha and (sh_p is None or sh_p >= alpha))
+    return DistributionSummary(
+        n=n, mean=float(np.mean(a)), std=float(np.std(a)), skewness=skew, kurtosis_excess=kurt,
+        jarque_bera_stat=float(jb_stat), jarque_bera_pvalue=float(jb_p),
+        shapiro_stat=sh_stat, shapiro_pvalue=sh_p, normal=normal,
+        reference="Jarque & Bera 1980, DOI 10.1016/0165-1765(80)90024-5; Shapiro & Wilk 1965, DOI 10.1093/biomet/52.3-4.591",
+    )
+
+
+def kde_curve(x, num: int = 100) -> dict:
+    """Gaussian KDE evaluated on a grid, for the histogram+density panel (Parzen 1962)."""
+    from scipy import stats
+
+    a = _clean(x)
+    kde = stats.gaussian_kde(a)
+    grid = np.linspace(float(a.min()), float(a.max()), num)
+    return {"grid": grid.tolist(), "density": kde(grid).tolist(),
+            "reference": "Parzen 1962, Ann. Math. Stat. 33(3):1065-1076, DOI 10.1214/aoms/1177704472"}
+
+
+def qq_points(x) -> dict:
+    """Normal Q-Q points (theoretical vs ordered sample quantiles) + the fitted reference line."""
+    from scipy import stats
+
+    a = _clean(x)
+    (osm, osr), (slope, intercept, r) = stats.probplot(a, dist="norm")
+    return {"theoretical": osm.tolist(), "sample": osr.tolist(),
+            "slope": float(slope), "intercept": float(intercept), "r": float(r),
+            "reference": "Wilk & Gnanadesikan 1968, Biometrika 55(1):1-17, DOI 10.1093/biomet/55.1.1"}
+
+
+@dataclass(frozen=True)
+class ComplexitySummary:
+    """Entropy/complexity measures + the BDS nonlinearity verdict (predictability of the ordering)."""
+
+    sample_entropy: float
+    permutation_entropy: float   # normalized to [0, 1]
+    spectral_entropy: float      # normalized to [0, 1]
+    bds_stat: float | None
+    bds_pvalue: float | None
+    iid: bool | None             # BDS verdict: True if not rejected (behaves i.i.d.)
+    reference: str
+
+
+def complexity(x, order: int = 3, bds_dim: int = 2, alpha: float = 0.05) -> ComplexitySummary:
+    """Sample/permutation/spectral entropy + the BDS i.i.d.-vs-nonlinear test."""
+    import antropy as ant
+    from statsmodels.tsa.stattools import bds as _bds
+
+    a = _clean(x)
+    samp = float(ant.sample_entropy(a))
+    perm = float(ant.perm_entropy(a, order=order, normalize=True))
+    spec = float(ant.spectral_entropy(a, sf=1.0, method="welch", normalize=True))
+    bds_stat = bds_p = None
+    iid = None
+    if len(a) >= 20:
+        try:
+            stat, pval = _bds(a, max_dim=bds_dim)
+            bds_stat = float(np.ravel(stat)[-1])          # statistic at the largest embedding dim
+            bds_p = float(np.ravel(pval)[-1])
+            iid = bool(bds_p >= alpha)
+        except Exception:  # noqa: BLE001 - BDS can fail on degenerate input; record as unavailable
+            warnings.warn("BDS diagnostic unavailable", RuntimeWarning, stacklevel=2)
+    return ComplexitySummary(
+        sample_entropy=samp, permutation_entropy=perm, spectral_entropy=spec,
+        bds_stat=bds_stat, bds_pvalue=bds_p, iid=iid,
+        reference="Richman & Moorman 2000, DOI 10.1152/ajpheart.2000.278.6.H2039; Bandt & Pompe 2002, DOI 10.1103/PhysRevLett.88.174102; BDS: Broock et al. 1996, DOI 10.1080/07474939608800353",
+    )
+
+
+def catch22_features(x) -> dict:
+    """The canonical catch22 feature set, in its catch24 form (+ mean and std). Lubba et al. 2019.
+
+    This is the PRINCIPLED answer to "extract many features": 22 features distilled from the ~7700 of hctsa
+    by selecting for classification performance and LOW REDUNDANCY - so it carries the information of a large
+    feature bank without the shotgun. We bake it per case (it is pinned in requirements-precompute.txt;
+    pycatch22 ships prebuilt wheels, no C toolchain needed). Kept import-guarded so the pipeline still runs
+    on a slim install, and if it is ever absent the report SAYS so rather than fabricating values.
+    """
+    try:
+        import pycatch22
+    except ImportError:
+        return {"available": False,
+                "reason": "pycatch22 not installed (pin it: requirements-precompute.txt)",
+                "reference": "Lubba et al. 2019, Data Min. Knowl. Disc. 33(6):1821-1852, DOI 10.1007/s10618-019-00647-x"}
+    a = _clean(x)
+    res = pycatch22.catch22_all(a.tolist(), catch24=True)
+    return {"available": True,
+            "features": dict(zip(res["names"], [float(v) for v in res["values"]])),
+            "reference": "Lubba et al. 2019, DOI 10.1007/s10618-019-00647-x"}
+
+
+def distribution_report(x, order: int = 3) -> dict:
+    """Run the distribution + complexity panel and return a JSON-ready report."""
+    a = _clean(x)
+    s = summary(a)
+    c = complexity(a, order=order)
+    return {
+        "n": len(a),
+        "summary": {"mean": s.mean, "std": s.std, "skewness": s.skewness,
+                    "kurtosis_excess": s.kurtosis_excess, "jarque_bera_pvalue": s.jarque_bera_pvalue,
+                    "shapiro_pvalue": s.shapiro_pvalue, "normal": s.normal, "reference": s.reference},
+        "kde": kde_curve(a),
+        "qq": qq_points(a),
+        "complexity": {"sample_entropy": c.sample_entropy, "permutation_entropy": c.permutation_entropy,
+                       "spectral_entropy": c.spectral_entropy, "bds_pvalue": c.bds_pvalue, "iid": c.iid,
+                       "reference": c.reference},
+        "catch22": catch22_features(a),
+    }

forecastscope/diagnostics/filters.py

@@ -0,0 +1,201 @@
+"""Trend-cycle filters and adaptive decompositions: HP, Baxter-King, Christiano-Fitzgerald, EMD, wavelets.
+
+Where STL/MSTL (see ``seasonality``) split a series by a FIXED period, the tools here separate components by
+FREQUENCY BAND (the econometric filters) or fully adaptively (EMD's intrinsic mode functions, the wavelet
+scalogram). They answer "what lives at which time scale?", which is how trend, business-cycle, and
+high-frequency structure are told apart when no single seasonal period exists.
+
+Methods / references (verified 2026-07-04):
+  * Hodrick-Prescott - penalized trend: min sum (y_t - tau_t)^2 + lambda * sum (Delta^2 tau_t)^2. Hodrick &
+    Prescott 1997, J. Money, Credit and Banking 29(1):1-16, DOI 10.2307/2953682.
+    ``statsmodels.tsa.filters.hp_filter.hpfilter``. Conventional lambda: 1600 quarterly, 129600 monthly,
+    6.25 annual.
+  * Baxter-King - symmetric finite-MA approximate band-pass isolating cycles of period [low, high];
+    loses K observations at each end. Baxter & King 1999, Rev. Econ. & Stat. 81(4):575-593,
+    DOI 10.1162/003465399558454. ``statsmodels.tsa.filters.bk_filter.bkfilter``.
+  * Christiano-Fitzgerald - asymmetric random-walk band-pass, usable in real time (no end-loss).
+    Christiano & Fitzgerald 2003, Int. Economic Review 44(2):435-465, DOI 10.1111/1468-2354.t01-1-00076.
+    ``statsmodels.tsa.filters.cf_filter.cffilter``.
+  * EMD / EEMD / CEEMDAN - adaptive decomposition into Intrinsic Mode Functions by sifting; EEMD adds
+    noise-assisted ensembling against mode mixing; CEEMDAN adds adaptive noise with complete reconstruction.
+    Huang et al. 1998, Proc. R. Soc. A 454:903-995, DOI 10.1098/rspa.1998.0193; Wu & Huang 2009,
+    Adv. Adaptive Data Analysis 1(1):1-41, DOI 10.1142/S1793536909000047; Torres et al. 2011, ICASSP,
+    DOI 10.1109/ICASSP.2011.5947265. Package ``EMD-signal`` (import ``PyEMD``).
+  * CWT scalogram - time-scale energy map |CWT(t, s)|^2 via PyWavelets (``pywt.cwt``; NOTE
+    ``scipy.signal.cwt`` was deprecated in scipy 1.12 and REMOVED in 1.15). Torrence & Compo 1998,
+    Bull. Amer. Meteor. Soc. 79(1):61-78, DOI 10.1175/1520-0477(1998)079<0061:APGTWA>2.0.CO;2.
+"""
+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 FilterResult:
+    """A two-way split into a smooth component (trend) and a cyclical component, by a named filter."""
+
+    name: str
+    trend: np.ndarray | None     # None for pure band-pass outputs (Baxter-King returns only the cycle)
+    cycle: np.ndarray
+    reference: str
+
+
+def hodrick_prescott(x, lamb: float = 1600.0) -> FilterResult:
+    """HP filter: penalized smooth trend + cycle. lambda 1600 quarterly / 129600 monthly / 6.25 annual."""
+    from statsmodels.tsa.filters.hp_filter import hpfilter
+
+    a = _clean(x)
+    cycle, trend = hpfilter(a, lamb=lamb)
+    return FilterResult(
+        name="HodrickPrescott", trend=np.asarray(trend, dtype=float), cycle=np.asarray(cycle, dtype=float),
+        reference="Hodrick & Prescott 1997, JMCB 29(1):1-16, DOI 10.2307/2953682",
+    )
+
+
+def baxter_king(x, low: int = 6, high: int = 32, K: int = 12) -> FilterResult:
+    """Baxter-King band-pass for cycles with period in [low, high]; symmetric MA, loses K points per end."""
+    from statsmodels.tsa.filters.bk_filter import bkfilter
+
+    a = _clean(x)
+    cycle = np.asarray(bkfilter(a, low=low, high=high, K=K), dtype=float).ravel()
+    return FilterResult(
+        name="BaxterKing", trend=None, cycle=cycle,
+        reference="Baxter & King 1999, REStat 81(4):575-593, DOI 10.1162/003465399558454",
+    )
+
+
+def christiano_fitzgerald(x, low: int = 6, high: int = 32) -> FilterResult:
+    """Christiano-Fitzgerald asymmetric band-pass; keeps the full sample length (real-time usable)."""
+    from statsmodels.tsa.filters.cf_filter import cffilter
+
+    a = _clean(x)
+    cycle, trend = cffilter(a, low=low, high=high, drift=True)
+    return FilterResult(
+        name="ChristianoFitzgerald", trend=np.asarray(trend, dtype=float).ravel(),
+        cycle=np.asarray(cycle, dtype=float).ravel(),
+        reference="Christiano & Fitzgerald 2003, IER 44(2):435-465, DOI 10.1111/1468-2354.t01-1-00076",
+    )
+
+
+@dataclass(frozen=True)
+class EMDResult:
+    """Intrinsic Mode Functions (rows of ``imfs``) + the residual trend, from EMD or CEEMDAN sifting."""
+
+    name: str
+    imfs: np.ndarray             # (n_imfs, n) - each row one IMF, fastest oscillation first
+    residual: np.ndarray         # the final monotone-ish trend left after all IMFs
+    reference: str
+
+
+def emd(x, max_imfs: int = -1, seed: int = 0) -> EMDResult:
+    """Plain EMD sifting into IMFs (fastest first) + the residual trend (``get_imfs_and_residue``)."""
+    from PyEMD import EMD as _EMD
+
+    a = _clean(x)
+    del seed  # plain EMD is deterministic (no noise); the seed applies to EEMD/CEEMDAN only
+    engine = _EMD()
+    engine.emd(a, max_imf=max_imfs)
+    imfs, residue = engine.get_imfs_and_residue()
+    return EMDResult(
+        name="EMD", imfs=np.asarray(imfs, dtype=float), residual=np.asarray(residue, dtype=float),
+        reference="Huang et al. 1998, Proc. R. Soc. A 454:903-995, DOI 10.1098/rspa.1998.0193",
+    )
+
+
+def ceemdan(x, trials: int = 50, seed: int = 0) -> EMDResult:
+    """CEEMDAN: noise-assisted EMD with adaptive noise and complete reconstruction (slower, cleaner IMFs)."""
+    from PyEMD import CEEMDAN as _CEEMDAN
+
+    a = _clean(x)
+    engine = _CEEMDAN(trials=trials)
+    engine.noise_seed(seed)
+    engine.ceemdan(a)
+    imfs, residue = engine.get_imfs_and_residue()
+    return EMDResult(
+        name="CEEMDAN", imfs=np.asarray(imfs, dtype=float), residual=np.asarray(residue, dtype=float),
+        reference="Torres et al. 2011, ICASSP, DOI 10.1109/ICASSP.2011.5947265",
+    )
+
+
+@dataclass(frozen=True)
+class Scalogram:
+    """|CWT|^2 energy over (scale, time): the standard wavelet time-frequency picture."""
+
+    power: np.ndarray            # (n_scales, n) - |coef|^2
+    scales: np.ndarray
+    periods: np.ndarray          # the pseudo-period of each scale (in samples, for the given wavelet)
+    wavelet: str
+    reference: str
+
+
+def cwt_scalogram(x, wavelet: str = "morl", num_scales: int = 64, max_period_frac: float = 0.5,
+                  detrend: bool = True) -> Scalogram:
+    """Continuous wavelet transform scalogram via PyWavelets (scipy's cwt is removed since 1.15).
+
+    Scales are geometric from ~2 samples up to ``max_period_frac`` of the series length, converted to
+    pseudo-periods so the y-axis reads in samples-per-cycle. Following Torrence & Compo 1998, the series is
+    linearly detrended by default: an un-removed trend dumps its energy into the longest scales and swamps
+    the cyclic structure the scalogram is meant to reveal (set ``detrend=False`` to see the raw picture).
+    """
+    import pywt
+
+    a = _clean(x)
+    n = len(a)
+    if n < 8:
+        raise ValueError("series too short for a scalogram")
+    if detrend:
+        t = np.arange(n, dtype=float)
+        slope, intercept = np.polyfit(t, a, 1)
+        a = a - (slope * t + intercept)
+    max_period = max(4.0, max_period_frac * n)
+    fc = pywt.central_frequency(wavelet)
+    # period = scale / fc  ->  scale = period * fc
+    periods = np.geomspace(2.0, max_period, num_scales)
+    scales = periods * fc
+    coefs, freqs = pywt.cwt(a, scales, wavelet)
+    power = np.abs(coefs) ** 2
+    out_periods = 1.0 / freqs
+    return Scalogram(
+        power=power, scales=np.asarray(scales, dtype=float), periods=np.asarray(out_periods, dtype=float),
+        wavelet=wavelet,
+        reference="Torrence & Compo 1998, BAMS 79(1):61-78, DOI 10.1175/1520-0477(1998)079<0061:APGTWA>2.0.CO;2",
+    )
+
+
+def filters_report(x, hp_lambda: float = 1600.0, band: tuple[int, int] = (6, 32), max_imfs: int = 6) -> dict:
+    """Run the filter panel (HP + CF + EMD + scalogram summary) and return a JSON-ready report.
+
+    Baxter-King is exposed as a function but not baked by default (its K-point end-loss makes panel arrays
+    ragged); CF covers the band-pass role in the artifact.
+    """
+    a = _clean(x)
+    hp = hodrick_prescott(a, lamb=hp_lambda)
+    cf = christiano_fitzgerald(a, low=band[0], high=band[1])
+    e = emd(a, max_imfs=max_imfs)
+    sc = cwt_scalogram(a) if len(a) >= 8 else None
+    out = {
+        "n": len(a),
+        "hp": {"lambda": hp_lambda, "trend": hp.trend.tolist(), "cycle": hp.cycle.tolist(),
+               "reference": hp.reference},
+        "cf": {"band": list(band), "cycle": cf.cycle.tolist(), "reference": cf.reference},
+        "emd": {"n_imfs": int(e.imfs.shape[0]), "imfs": e.imfs.tolist(), "residual": e.residual.tolist(),
+                "reference": e.reference},
+    }
+    if sc is not None:
+        # bake a compact scalogram summary: per-scale total energy + the dominant period by energy
+        energy = sc.power.sum(axis=1)
+        out["scalogram"] = {
+            "wavelet": sc.wavelet,
+            "periods": sc.periods.tolist(),
+            "energy_by_period": energy.tolist(),
+            "dominant_period": float(sc.periods[int(np.argmax(energy))]),
+            "reference": sc.reference,
+        }
+    return out

forecastscope/diagnostics/fractal.py

@@ -0,0 +1,206 @@
+"""Fractal, multifractal, and long-memory analysis: Hurst, DFA, MF-DFA, fractal dimension, DCCA.
+
+The self-affine / scaling structure of a series: does it have long-range dependence (persistent memory)? Is a
+single scaling exponent enough (monofractal) or does it need a spectrum (multifractal)? How rough is it? For
+the forecastability story this is decisive: a Hurst exponent far from 0.5 signals exploitable structure, a
+wide multifractal spectrum signals scale-dependent burstiness, and both temper naive "it's just noise"
+conclusions. Each method delegates to its authoritative library and carries the primary reference.
+
+Methods / references (verified 2026-07-04; dossiers research-hurst-dfa / research-multifractal /
+research-fractal-dimension / research-cross-series-modeling-honesty):
+  * Hurst via R/S - Hurst 1951, Trans. ASCE 116:770-799. H<0.5 anti-persistent, =0.5 random walk, >0.5
+    persistent. ``hurst.compute_Hc`` (Anis-Lloyd corrected) and ``nolds.hurst_rs``.
+  * DFA - Peng et al. 1994, Phys. Rev. E 49:1685-1689 (detrended fluctuation analysis). Scaling exponent
+    alpha (fGn: H=alpha; fBm: H=alpha-1; alpha~1 = 1/f noise). ``nolds.dfa`` / ``antropy.detrended_fluctuation``.
+  * MF-DFA - Kantelhardt et al. 2002, Physica A 316:87-114, DOI 10.1016/S0378-4371(02)01383-3. The
+    generalized Hurst h(q), mass exponent tau(q)=q*h(q)-1, and the singularity spectrum f(alpha) via the
+    Legendre transform. Spectrum WIDTH = degree of multifractality. ``MFDFA.MFDFA``.
+  * Fractal dimension - Higuchi 1988, Physica D 31:277-283, DOI 10.1016/0167-2789(88)90081-4; Katz 1988;
+    Petrosian 1995. D in [1, 2] for a series graph: higher = rougher. ``antropy.{higuchi_fd,katz_fd,petrosian_fd}``.
+  * Modeling counterpart: ARFIMA fractional differencing d = H - 0.5 (Granger-Joyeux 1980; Hosking 1981) -
+    recorded as the long-memory link, not fitted here (no maintained Python ARFIMA mean-estimator; see plan).
+
+HONESTY: DFA always returns a positive alpha even for non-self-similar data, and R/S is biased on short
+series (needs n > ~50-100). We report the value AND a caveat flag; forecastability claims are gated by the
+[nonlinear-dynamics] surrogate tests, not by a single exponent.
+"""
+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 HurstResult:
+    """Long-range dependence: the Hurst exponent by R/S and by DFA, with an interpretation."""
+
+    hurst_rs: float
+    dfa_alpha: float
+    interpretation: str          # anti-persistent / random-walk-like / persistent
+    reliable: bool               # False when n is too short for a stable estimate
+    reference: str
+
+
+def _interpret_hurst(h: float) -> str:
+    if h < 0.45:
+        return "anti-persistent (mean-reverting; H < 0.5)"
+    if h > 0.55:
+        return "persistent (long-range positive dependence; H > 0.5)"
+    return "random-walk-like (no long-range dependence; H ~ 0.5)"
+
+
+def hurst(x) -> HurstResult:
+    """Hurst exponent by rescaled-range (Anis-Lloyd corrected) and by DFA; flags short-sample unreliability."""
+    import nolds
+    from hurst import compute_Hc
+
+    a = _clean(x)
+    n = len(a)
+    # R/S on the series levels (compute_Hc expects a positive-ish level series; use kind='change' for returns)
+    try:
+        h_rs, _c, _data = compute_Hc(a, kind="random_walk", simplified=True)
+    except Exception:  # noqa: BLE001 - fall back to nolds if compute_Hc rejects the input
+        h_rs = float(nolds.hurst_rs(a, fit="poly"))
+    # Explicit least-squares slopes avoid nolds' unseeded randomized default.
+    dfa_alpha = float(nolds.dfa(a, fit_exp="poly"))
+    # DFA alpha maps to H: fGn regime alpha in [0,1] -> H=alpha; fBm regime alpha in [1,2] -> H=alpha-1
+    h_from_dfa = dfa_alpha if dfa_alpha <= 1.0 else dfa_alpha - 1.0
+    return HurstResult(
+        hurst_rs=float(h_rs), dfa_alpha=dfa_alpha,
+        interpretation=_interpret_hurst(0.5 * (float(h_rs) + h_from_dfa)),
+        reliable=bool(n >= 100),
+        reference="Hurst 1951, Trans. ASCE 116:770-799 (R/S); Peng et al. 1994, Phys. Rev. E 49:1685-1689 (DFA)",
+    )
+
+
+@dataclass(frozen=True)
+class MultifractalSpectrum:
+    """MF-DFA output: generalized Hurst h(q), mass exponent tau(q), and the singularity spectrum f(alpha)."""
+
+    q: np.ndarray
+    hq: np.ndarray               # generalized Hurst exponent per q
+    tau: np.ndarray              # mass exponent tau(q) = q*h(q) - 1
+    alpha: np.ndarray            # singularity strength (Holder exponent)
+    f_alpha: np.ndarray          # singularity spectrum
+    width: float                 # max(alpha) - min(alpha): the degree of multifractality
+    is_multifractal: bool        # width above a small threshold
+    reference: str
+
+
+def mfdfa(x, q=None, order: int = 1) -> MultifractalSpectrum:
+    """MF-DFA generalized Hurst h(q) and the Legendre singularity spectrum f(alpha) (Kantelhardt 2002)."""
+    from MFDFA import MFDFA as _MFDFA
+
+    a = _clean(x)
+    n = len(a)
+    if n < 200:
+        raise ValueError("MF-DFA needs a longer series (>= ~200 points) for a stable spectrum")
+    q = np.asarray(q if q is not None else [-5, -3, -2, -1, 1, 2, 3, 5], dtype=float)
+    q = q[q != 0]                                          # q=0 needs the log-averaging variant; skip it
+    # geometric scales from ~8 up to n/4 (Kantelhardt's recommended range)
+    lag = np.unique(np.geomspace(8, max(16, n // 4), 24).astype(int))
+    lag2, dfa = _MFDFA(a, lag=lag, q=q, order=order)
+    # h(q) = slope of log F_q(s) vs log s per q
+    logs = np.log(lag2)
+    hq = np.array([np.polyfit(logs, np.log(dfa[:, i]), 1)[0] for i in range(len(q))])
+    tau = q * hq - 1.0
+    # singularity spectrum via the Legendre transform: alpha = dtau/dq, f = q*alpha - tau
+    alpha = np.gradient(tau, q)
+    f_alpha = q * alpha - tau
+    width = float(np.max(alpha) - np.min(alpha))
+    return MultifractalSpectrum(
+        q=q, hq=hq, tau=tau, alpha=alpha, f_alpha=f_alpha, width=width,
+        is_multifractal=bool(width > 0.15),
+        reference="Kantelhardt et al. 2002, Physica A 316:87-114, DOI 10.1016/S0378-4371(02)01383-3",
+    )
+
+
+@dataclass(frozen=True)
+class FractalDimension:
+    """Graph fractal dimension by three estimators (D in [1, 2]; higher = rougher)."""
+
+    higuchi: float
+    katz: float
+    petrosian: float
+    reference: str
+
+
+def fractal_dimension(x, kmax: int = 10) -> FractalDimension:
+    """Higuchi, Katz, and Petrosian fractal dimension of the series graph (antropy)."""
+    import antropy as ant
+
+    a = _clean(x)
+    return FractalDimension(
+        higuchi=float(ant.higuchi_fd(a, kmax=kmax)), katz=float(ant.katz_fd(a)),
+        petrosian=float(ant.petrosian_fd(a)),
+        reference="Higuchi 1988, Physica D 31:277-283, DOI 10.1016/0167-2789(88)90081-4; Katz 1988; Petrosian 1995",
+    )
+
+
+def dcca_coefficient(x, y, scale: int | None = None) -> dict:
+    """Detrended cross-correlation coefficient rho_DCCA at one scale (Zebende 2011), in [-1, 1].
+
+    Measures scale-dependent cross-correlation between two nonstationary series after local detrending.
+    Uses a direct DCCA implementation (Podobnik & Stanley 2008): integrate both series, slide a window,
+    locally detrend, and form the detrended covariance normalized by the two detrended variances.
+    """
+    a, b = _clean(x), _clean(y)
+    m = min(len(a), len(b))
+    a, b = a[:m], b[:m]
+    if scale is None:
+        scale = max(8, m // 8)
+    if scale >= m:
+        raise ValueError("scale must be smaller than the series length")
+    # integrate to profiles
+    A = np.cumsum(a - a.mean())
+    B = np.cumsum(b - b.mean())
+    fa2 = fb2 = fab = 0.0
+    count = 0
+    t = np.arange(scale + 1, dtype=float)
+    for start in range(m - scale):
+        wa, wb = A[start:start + scale + 1], B[start:start + scale + 1]
+        # local linear detrend
+        ca = np.polyfit(t, wa, 1)
+        cb = np.polyfit(t, wb, 1)
+        ra = wa - np.polyval(ca, t)
+        rb = wb - np.polyval(cb, t)
+        fab += float(np.mean(ra * rb))
+        fa2 += float(np.mean(ra * ra))
+        fb2 += float(np.mean(rb * rb))
+        count += 1
+    denom = np.sqrt(fa2 * fb2) if fa2 > 0 and fb2 > 0 else 0.0
+    rho = float(fab / denom) if denom > 0 else float("nan")
+    return {"scale": int(scale), "rho_dcca": rho, "n_windows": count,
+            "reference": "Podobnik & Stanley 2008, PRL 100:084102, DOI 10.1103/PhysRevLett.100.084102; Zebende 2011, Physica A 390:614-618"}
+
+
+def fractal_report(x) -> dict:
+    """Run the fractal panel (Hurst + fractal dimension + MF-DFA where the series is long enough)."""
+    a = _clean(x)
+    h = hurst(a)
+    fd = fractal_dimension(a)
+    out = {
+        "n": len(a),
+        "hurst": {"rs": h.hurst_rs, "dfa_alpha": h.dfa_alpha, "interpretation": h.interpretation,
+                  "reliable": h.reliable, "reference": h.reference},
+        "fractal_dimension": {"higuchi": fd.higuchi, "katz": fd.katz, "petrosian": fd.petrosian,
+                              "reference": fd.reference},
+        "arfima_link": {"d": round(h.hurst_rs - 0.5, 4),
+                        "note": "long-memory fractional-differencing order d ~ H - 0.5 (Granger-Joyeux 1980)"},
+    }
+    try:
+        mf = mfdfa(a)
+        out["multifractal"] = {
+            "q": mf.q.tolist(), "hq": mf.hq.tolist(), "alpha": mf.alpha.tolist(),
+            "f_alpha": mf.f_alpha.tolist(), "width": mf.width, "is_multifractal": mf.is_multifractal,
+            "reference": mf.reference,
+        }
+    except Exception as exc:  # noqa: BLE001 - series too short or degenerate; record, do not crash
+        out["multifractal"] = {"error": f"{type(exc).__name__}: {exc}"}
+    return out