fdnkit 1.0.0__py3-none-any.whl

fdnkit/io.py

@@ -0,0 +1,163 @@
+"""Input/output: load recordings, load trial labels, read/write feature tables.
+
+Heavy IO dependencies are optional and imported lazily so the core analysis
+stack (numpy/scipy/pandas/scikit-learn) stays lightweight:
+
+* EDF reading uses **MNE-Python** (``pip install fdnkit[io]``).
+* HDF5 reading uses **h5py**.
+
+Both raise a clear, actionable error if the backend is missing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+__all__ = ["Recording", "load_edf", "load_h5", "load_labels_excel",
+           "save_features", "load_features"]
+
+
+@dataclass
+class Recording:
+    """A loaded multi-channel recording.
+
+    Attributes
+    ----------
+    signals : numpy.ndarray
+        Shape ``(n_channels, n_samples)``.
+    fs : float
+        Sampling frequency in Hz.
+    channel_names : list of str
+    times : numpy.ndarray | None
+        Optional per-sample time vector (seconds).
+    """
+
+    signals: np.ndarray
+    fs: float
+    channel_names: list
+    times: np.ndarray | None = None
+
+    @property
+    def n_channels(self) -> int:
+        return self.signals.shape[0]
+
+    @property
+    def n_samples(self) -> int:
+        return self.signals.shape[1]
+
+    @property
+    def duration(self) -> float:
+        return self.n_samples / self.fs
+
+
+def load_edf(path, *, preload: bool = True) -> Recording:
+    """Load an EDF/EDF+ recording via MNE-Python.
+
+    Parameters
+    ----------
+    path : str | pathlib.Path
+    preload : bool
+        Read sample data into memory immediately.
+
+    Returns
+    -------
+    Recording
+    """
+    try:
+        import mne
+    except ImportError as exc:  # pragma: no cover - exercised only without mne
+        raise ImportError(
+            "Reading EDF requires MNE-Python. Install with `pip install fdnkit[io]` "
+            "or `pip install mne`."
+        ) from exc
+
+    raw = mne.io.read_raw_edf(str(path), preload=preload, verbose="ERROR")
+    signals = raw.get_data()
+    fs = float(raw.info["sfreq"])
+    names = list(raw.ch_names)
+    times = raw.times.copy()
+    return Recording(signals=signals, fs=fs, channel_names=names, times=times)
+
+
+def load_h5(path, *, signals_key="data/Signals", time_key="data/Time",
+            names_key="metadata/channel_names", fs: float = 1000.0) -> Recording:
+    """Load a recording from an HDF5 file (h5py).
+
+    Defaults match the reference layout: signals at ``data/Signals`` with shape
+    ``(n_channels, n_samples)``, an optional time vector at ``data/Time``, and
+    optional channel names at ``metadata/channel_names``.
+    """
+    try:
+        import h5py
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "Reading HDF5 requires h5py. Install with `pip install fdnkit[io]` "
+            "or `pip install h5py`."
+        ) from exc
+
+    with h5py.File(str(path), "r") as f:
+        signals = np.asarray(f[signals_key][:])
+        times = np.asarray(f[time_key][:]) if time_key in f else None
+        if names_key in f:
+            raw_names = f[names_key][:]
+            names = [n.decode("utf-8") if isinstance(n, bytes) else str(n) for n in raw_names]
+        else:
+            names = [f"CH{i + 1}" for i in range(signals.shape[0])]
+
+    if times is not None and times.size > 1:
+        dt = float(np.median(np.diff(times)))
+        if dt > 0:
+            fs = 1.0 / dt
+    return Recording(signals=signals, fs=fs, channel_names=names, times=times)
+
+
+def load_labels_excel(path, *, id_col="Patient_Session_Trial", score_col="Math_Score",
+                      success_code="M1", failure_code="M0", header: int = 1) -> dict:
+    """Load a ``{trial_id: 0/1}`` label mapping from an Excel scoresheet.
+
+    Ports ``utils/label_strategies.ExcelMathScoreLabeler``: rows whose score
+    equals ``success_code`` map to 1, ``failure_code`` to 0; anything else
+    (blank, "MC", ...) is skipped.
+
+    Parameters
+    ----------
+    path : str | pathlib.Path
+    id_col, score_col : str
+        Column names for the trial identifier and the score.
+    success_code, failure_code : str
+        Score strings mapped to 1 and 0 respectively (compared case-insensitively).
+    header : int
+        Row index (0-based) of the header. Defaults to 1 (second row).
+
+    Returns
+    -------
+    dict[str, int]
+    """
+    df = pd.read_excel(path, header=header)
+    df = df[[id_col, score_col]].dropna(subset=[id_col])
+    mapping: dict = {}
+    for _, row in df.iterrows():
+        tid = str(row[id_col]).strip()
+        score = str(row[score_col]).strip().upper()
+        if score == success_code.upper():
+            mapping[tid] = 1
+        elif score == failure_code.upper():
+            mapping[tid] = 0
+    return mapping
+
+
+def save_features(df: pd.DataFrame, path) -> Path:
+    """Write a feature DataFrame to CSV (index omitted). Returns the path."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    df.to_csv(path, index=False)
+    return path
+
+
+def load_features(path) -> pd.DataFrame:
+    """Read a feature table CSV back into a DataFrame."""
+    return pd.read_csv(path)

fdnkit/mfdfa.py

@@ -0,0 +1,233 @@
+"""Multifractal detrended fluctuation analysis (MFDFA).
+
+Ports the validated reference implementation, cross-checked against its MATLAB
+counterpart, into a clean, array-first API.
+
+The generalized Hurst exponent ``h(q)`` describes how the ``q``-th order
+fluctuation of a signal scales with window size. A signal is *monofractal* when
+``h(q)`` is (nearly) constant in ``q`` and *multifractal* when it varies; the
+width ``delta_h = max h(q) - min h(q)`` quantifies multifractality.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+__all__ = ["MFDFAResult", "mfdfa", "generalized_hurst", "delta_hq", "multifractal_spectrum"]
+
+# Default analysis grids (match the validated reference / MATLAB settings).
+DEFAULT_SCALES = np.array([4, 6, 8, 12, 16, 24, 32, 48, 64, 96, 128, 192, 256])
+DEFAULT_Q = np.array([-5, -3, -2, -1, 0, 1, 2, 3, 5], dtype=float)
+
+
+@dataclass
+class MFDFAResult:
+    """Container for the output of :func:`mfdfa`.
+
+    Attributes
+    ----------
+    hurst : float
+        Monofractal Hurst exponent ``H`` (slope of ``log2 F`` vs ``log2 scale``,
+        equivalent to ``h(q=2)``).
+    hq : numpy.ndarray
+        Generalized Hurst exponents, one per entry of :attr:`q`.
+    q : numpy.ndarray
+        The moment orders used.
+    scales : numpy.ndarray
+        The window sizes used.
+    fluct : numpy.ndarray
+        Standard (``q=2``) fluctuation function ``F`` per scale.
+    fluct_q : numpy.ndarray
+        Fluctuation function per ``(q, scale)`` -- shape ``(len(q), len(scales))``.
+    """
+
+    hurst: float
+    hq: np.ndarray
+    q: np.ndarray
+    scales: np.ndarray
+    fluct: np.ndarray
+    fluct_q: np.ndarray
+
+    @property
+    def delta_h(self) -> float:
+        """Multifractal width ``max h(q) - min h(q)`` (0 for a monofractal)."""
+        finite = self.hq[np.isfinite(self.hq)]
+        if finite.size == 0:
+            return float("nan")
+        return float(finite.max() - finite.min())
+
+    def hq_at(self, q_value: float) -> float:
+        """Return ``h(q)`` at the grid point nearest ``q_value``."""
+        idx = int(np.argmin(np.abs(self.q - q_value)))
+        return float(self.hq[idx])
+
+
+def _fluctuations(signal, scales, order, rel_floor: float = 1e-3):
+    """Local detrended RMS fluctuations for each scale (q=2 base quantities).
+
+    Returns a list whose ``i``-th entry is the array of per-segment RMS values at
+    ``scales[i]`` (empty if the scale exceeds the signal length).
+
+    ``rel_floor`` sets a *scale-relative* lower bound on each RMS value. Quantized
+    or degenerately-detrended segments (common in real, integer-stored recordings,
+    especially at small scales) can drive a segment's RMS to ~0; raised to a
+    negative moment ``q`` this dominates ``F_q(s)`` and fabricates a huge apparent
+    multifractal width. Flooring at ``rel_floor * median(RMS)`` for the scale --
+    rather than at machine epsilon -- tames this without perturbing well-behaved
+    (e.g. synthetic) signals, whose fluctuations never approach the floor.
+    """
+    eps = np.finfo(float).eps
+    x = np.asarray(signal, dtype=float)
+    n = x.size
+    y = np.cumsum(x - x.mean())
+
+    rms_per_scale = []
+    for s in scales:
+        s = int(s)
+        segs = n // s
+        if segs == 0:  # scale larger than the signal
+            rms_per_scale.append(np.empty(0))
+            continue
+        t = np.arange(s)
+        rms = np.empty(segs)
+        for v in range(segs):
+            seg = y[v * s : (v + 1) * s]
+            coef = np.polyfit(t, seg, order)
+            fit = np.polyval(coef, t)
+            rms[v] = np.sqrt(np.mean((seg - fit) ** 2))
+        positive = rms[rms > 0]
+        floor = rel_floor * np.median(positive) if positive.size else eps
+        floor = max(floor, eps)
+        np.maximum(rms, floor, out=rms)
+        rms_per_scale.append(rms)
+    return rms_per_scale
+
+
+def _loglog_slope(scales, values):
+    """Slope of log2(values) vs log2(scales) over finite, positive points."""
+    lg_s = np.log2(np.asarray(scales, dtype=float))
+    lg_v = np.log2(np.asarray(values, dtype=float))
+    good = np.isfinite(lg_v) & np.isfinite(lg_s)
+    if good.sum() < 2:
+        return float("nan")
+    # Ordinary least-squares slope.
+    xs, ys = lg_s[good], lg_v[good]
+    xm, ym = xs.mean(), ys.mean()
+    denom = np.sum((xs - xm) ** 2)
+    if denom == 0:
+        return float("nan")
+    return float(np.sum((xs - xm) * (ys - ym)) / denom)
+
+
+def mfdfa(signal, scales=None, q=None, order: int = 1, rel_floor: float = 1e-3) -> MFDFAResult:
+    """Run multifractal detrended fluctuation analysis on a 1-D signal.
+
+    Parameters
+    ----------
+    signal : array-like
+        1-D time series.
+    scales : array-like, optional
+        Window sizes (in samples). Defaults to
+        ``[4, 6, 8, 12, 16, 24, 32, 48, 64, 96, 128, 192, 256]``. Every scale
+        should be smaller than ``len(signal)``.
+    q : array-like, optional
+        Moment orders. Defaults to ``[-5, -3, -2, -1, 0, 1, 2, 3, 5]``.
+    order : int
+        Order of the polynomial used to detrend each segment (1 = linear).
+    rel_floor : float
+        Scale-relative floor on per-segment fluctuations, as a fraction of the
+        median fluctuation at each scale. Guards the negative-``q`` moments
+        against degenerate near-zero segments in real (e.g. integer-quantized)
+        recordings; set to 0 to disable. Does not affect well-behaved signals.
+
+    Returns
+    -------
+    MFDFAResult
+
+    Notes
+    -----
+    Follows Kantelhardt et al. (2002) with a forward (non-overlapping) segment
+    partition, matching the validated reference implementation. The ``q = 0``
+    moment uses the logarithmic-average limit
+    ``F_0(s) = exp(0.5 * mean(log RMS^2))``.
+    """
+    eps = np.finfo(float).eps
+    scales = DEFAULT_SCALES if scales is None else np.asarray(scales)
+    scales = np.asarray(scales, dtype=int)
+    q = DEFAULT_Q if q is None else np.asarray(q, dtype=float)
+
+    x = np.asarray(signal, dtype=float).ravel()
+    if x.size < int(scales.min()) * 2:
+        raise ValueError(
+            f"signal length {x.size} too short for smallest scale {int(scales.min())}"
+        )
+
+    rms_per_scale = _fluctuations(x, scales, order, rel_floor=rel_floor)
+
+    fluct = np.full(len(scales), np.nan)
+    fluct_q = np.full((len(q), len(scales)), np.nan)
+    for i, rms in enumerate(rms_per_scale):
+        if rms.size == 0:
+            continue
+        fluct[i] = np.sqrt(np.mean(rms**2))
+        for j, qq in enumerate(q):
+            if qq == 0:
+                fluct_q[j, i] = np.exp(0.5 * np.mean(np.log(rms**2)))
+            else:
+                fluct_q[j, i] = np.mean(rms**qq) ** (1.0 / qq)
+
+    hurst = _loglog_slope(scales, fluct + eps)
+    hq = np.array([_loglog_slope(scales, fluct_q[j] + eps) for j in range(len(q))])
+
+    return MFDFAResult(
+        hurst=hurst, hq=hq, q=np.asarray(q, dtype=float),
+        scales=np.asarray(scales), fluct=fluct, fluct_q=fluct_q,
+    )
+
+
+def generalized_hurst(signal, scales=None, q=None, order: int = 1):
+    """Convenience wrapper returning ``(q, h(q))`` arrays only."""
+    res = mfdfa(signal, scales=scales, q=q, order=order)
+    return res.q, res.hq
+
+
+def delta_hq(signal, scales=None, q=None, order: int = 1) -> float:
+    """Multifractal width ``max h(q) - min h(q)`` for a signal."""
+    return mfdfa(signal, scales=scales, q=q, order=order).delta_h
+
+
+def multifractal_spectrum(result: MFDFAResult):
+    """Legendre-transform the generalized Hurst exponents to ``(alpha, f(alpha))``.
+
+    Uses the standard MFDFA relations
+
+    ``tau(q) = q * h(q) - 1``,
+    ``alpha = d tau / d q``,
+    ``f(alpha) = q * alpha - tau(q)``.
+
+    Parameters
+    ----------
+    result : MFDFAResult
+        Output of :func:`mfdfa` (needs at least 3 finite ``h(q)`` points).
+
+    Returns
+    -------
+    alpha : numpy.ndarray
+        Holder exponents (singularity strengths).
+    f_alpha : numpy.ndarray
+        Singularity spectrum values.
+    """
+    q = result.q
+    hq = result.hq
+    good = np.isfinite(hq)
+    q, hq = q[good], hq[good]
+    if q.size < 3:
+        raise ValueError("need at least 3 finite h(q) points for a spectrum")
+    order = np.argsort(q)
+    q, hq = q[order], hq[order]
+    tau = q * hq - 1.0
+    alpha = np.gradient(tau, q)
+    f_alpha = q * alpha - tau
+    return alpha, f_alpha

fdnkit/preprocessing.py

@@ -0,0 +1,125 @@
+"""Preprocessing helpers: normalization, artifact-channel flagging, windowing.
+
+Kept deliberately small -- FDNkit depends on MNE-Python for montages, filtering,
+and ICA rather than reimplementing them. These utilities cover only what the
+fractal/FODN pipeline needs: z-scoring, dropping obviously-bad channels, and
+cutting a recording into fixed-length analysis windows.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["zscore", "flag_bad_channels", "segment", "sliding_windows"]
+
+
+def zscore(signals, axis: int = -1, eps: float = 1e-12) -> np.ndarray:
+    """Z-score signals along ``axis`` (per-channel by default).
+
+    Parameters
+    ----------
+    signals : array-like
+        1-D or 2-D ``(n_channels, n_samples)`` array.
+    axis : int
+        Axis along which to standardize (default ``-1`` = time).
+    eps : float
+        Floor for the standard deviation to avoid divide-by-zero on flat channels.
+    """
+    x = np.asarray(signals, dtype=float)
+    mean = np.mean(x, axis=axis, keepdims=True)
+    std = np.std(x, axis=axis, keepdims=True)
+    return (x - mean) / np.maximum(std, eps)
+
+
+def flag_bad_channels(
+    signals,
+    channel_names=None,
+    *,
+    flat_std: float = 1e-8,
+    amplitude_z: float = 5.0,
+    name_prefixes=("EKG", "ECG", "X1 DC", "DC", "TRIG", "STI"),
+) -> list[int]:
+    """Return indices of channels that look like artifacts.
+
+    A channel is flagged if it is (a) effectively flat, (b) has an
+    root-mean-square amplitude more than ``amplitude_z`` robust-SDs from the
+    median across channels, or (c) its name starts with a known non-neural
+    prefix (EKG, trigger, DC, ...).
+
+    Parameters
+    ----------
+    signals : array-like, shape (n_channels, n_samples)
+    channel_names : sequence of str, optional
+        Used only for prefix-based flagging.
+    flat_std : float
+        Channels with standard deviation below this are flat.
+    amplitude_z : float
+        Robust z-threshold on per-channel RMS.
+    name_prefixes : tuple of str
+        Case-insensitive channel-name prefixes to treat as non-neural.
+    """
+    x = np.asarray(signals, dtype=float)
+    if x.ndim != 2:
+        raise ValueError("signals must be 2-D (n_channels, n_samples)")
+    n_ch = x.shape[0]
+    bad = set()
+
+    std = x.std(axis=1)
+    bad.update(np.where(std < flat_std)[0].tolist())
+
+    rms = np.sqrt(np.mean(x**2, axis=1))
+    med = np.median(rms)
+    mad = np.median(np.abs(rms - med)) + 1e-12
+    robust_z = 0.6745 * (rms - med) / mad
+    bad.update(np.where(np.abs(robust_z) > amplitude_z)[0].tolist())
+
+    if channel_names is not None:
+        prefixes = tuple(p.upper() for p in name_prefixes)
+        for i, name in enumerate(channel_names):
+            if i < n_ch and str(name).upper().startswith(prefixes):
+                bad.add(i)
+
+    return sorted(bad)
+
+
+def segment(signals, window: int, *, step: int = None, min_size: int = None):
+    """Cut a signal into non-overlapping (or strided) windows along time.
+
+    Parameters
+    ----------
+    signals : array-like
+        1-D ``(n_samples,)`` or 2-D ``(n_channels, n_samples)`` array.
+    window : int
+        Window length in samples.
+    step : int, optional
+        Hop size in samples. Defaults to ``window`` (non-overlapping).
+    min_size : int, optional
+        Discard a trailing window shorter than this. Defaults to ``window``
+        (i.e. drop any partial final window).
+
+    Yields
+    ------
+    (start, stop, chunk) : tuple[int, int, numpy.ndarray]
+        Sample bounds and the windowed data (``chunk`` keeps the input ndim).
+    """
+    x = np.asarray(signals)
+    if window <= 0:
+        raise ValueError("window must be positive")
+    step = window if step is None else step
+    if step <= 0:
+        raise ValueError("step must be positive")
+    min_size = window if min_size is None else min_size
+    n = x.shape[-1]
+    start = 0
+    while start < n:
+        stop = min(start + window, n)
+        if stop - start < min_size:
+            break
+        chunk = x[..., start:stop]
+        yield start, stop, chunk
+        start += step
+
+
+def sliding_windows(signals, window: int, *, step: int = None, min_size: int = None):
+    """List form of :func:`segment` -- returns ``[(start, stop, chunk), ...]``."""
+    return list(segment(signals, window, step=step, min_size=min_size))

fdnkit/synthetic.py

@@ -0,0 +1,173 @@
+"""Synthetic signal generators for testing, examples, and quickstarts.
+
+These let FDNkit's tutorials and test suite run with **no data download** and give
+analyses ground-truth answers to check against:
+
+* :func:`fgn` / :func:`fbm` -- fractional Gaussian noise / motion with a known
+  Hurst exponent (exact Davies-Harte circulant-embedding synthesis). Detrended
+  fluctuation analysis of ``fgn(H)`` should recover ``H``.
+* :func:`binomial_cascade` -- a multiplicative cascade whose multifractal
+  spectrum is known in closed form; used to check that MFDFA reports a genuinely
+  broad ``h(q)``.
+* :func:`synthetic_ieeg` -- a small multi-channel, sparsely-coupled recording
+  that stands in for an intracranial-EEG trial in examples and FODN tests.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["fgn", "fbm", "binomial_cascade", "synthetic_ieeg"]
+
+
+def _as_rng(seed):
+    if isinstance(seed, np.random.Generator):
+        return seed
+    return np.random.default_rng(seed)
+
+
+def fgn(n: int, hurst: float = 0.7, *, seed=None) -> np.ndarray:
+    """Exact fractional Gaussian noise via Davies-Harte circulant embedding.
+
+    Parameters
+    ----------
+    n : int
+        Number of samples.
+    hurst : float
+        Target Hurst exponent in (0, 1). ``0.5`` gives ordinary white noise.
+    seed : int | numpy.random.Generator | None
+        Seed or generator for reproducibility.
+
+    Returns
+    -------
+    numpy.ndarray
+        Length-``n`` unit-variance fractional Gaussian noise. Its DFA exponent is
+        (asymptotically) ``hurst``.
+
+    Notes
+    -----
+    Davies, R. B. & Harte, D. S. (1987). *Tests for Hurst effect.* Biometrika 74.
+    The circulant embedding is exact when all embedded eigenvalues are
+    non-negative; for the fGn autocovariance and ``0 < H < 1`` this holds.
+    """
+    if n < 2:
+        raise ValueError("n must be >= 2")
+    if not 0.0 < hurst < 1.0:
+        raise ValueError("hurst must be in the open interval (0, 1)")
+    rng = _as_rng(seed)
+    H = float(hurst)
+
+    # fGn autocovariance gamma(k) for unit-variance increments.
+    k = np.arange(n)
+    gamma = 0.5 * (
+        np.abs(k - 1) ** (2 * H) - 2 * np.abs(k) ** (2 * H) + np.abs(k + 1) ** (2 * H)
+    )
+
+    # First row of the size-M = 2(n-1) circulant embedding.
+    row = np.concatenate([gamma, gamma[-2:0:-1]])
+    m = row.size  # 2*(n-1)
+    eig = np.fft.fft(row).real
+    # Clip tiny negative eigenvalues from floating error; warn only if large.
+    if np.any(eig < -1e-8 * np.abs(eig).max()):
+        eig = np.clip(eig, 0.0, None)
+    else:
+        eig = np.clip(eig, 0.0, None)
+
+    # Build spectral coefficients W with the exact Davies-Harte weighting.
+    w = np.zeros(m, dtype=complex)
+    half = m // 2
+    v1 = rng.standard_normal(m)
+    v2 = rng.standard_normal(m)
+    w[0] = np.sqrt(eig[0]) * v1[0]
+    w[half] = np.sqrt(eig[half]) * v1[half]
+    idx = np.arange(1, half)
+    w[idx] = np.sqrt(eig[idx] / 2.0) * (v1[idx] + 1j * v2[idx])
+    w[m - idx] = np.conj(w[idx])
+
+    y = np.fft.fft(w) / np.sqrt(m)
+    return y.real[:n]
+
+
+def fbm(n: int, hurst: float = 0.7, *, seed=None) -> np.ndarray:
+    """Fractional Brownian motion: the cumulative sum of :func:`fgn`.
+
+    Returns a length-``n`` path with Hurst exponent ``hurst`` (DFA exponent
+    ``hurst + 1``).
+    """
+    return np.cumsum(fgn(n, hurst, seed=seed))
+
+
+def binomial_cascade(n_levels: int = 12, p: float = 0.3, *, seed=None) -> np.ndarray:
+    """Deterministic-weight binomial multiplicative cascade (a multifractal).
+
+    Builds a measure on ``2**n_levels`` points by repeatedly splitting mass with
+    multipliers ``p`` and ``1 - p``. The result is strongly multifractal, so
+    MFDFA should return a wide ``h(q)`` (large ``delta_h``). With ``p = 0.5`` the
+    cascade is uniform (monofractal).
+
+    Parameters
+    ----------
+    n_levels : int
+        Number of cascade levels; output length is ``2 ** n_levels``.
+    p : float
+        Multiplier in (0, 1). Distance of ``p`` from 0.5 sets multifractal width.
+    seed : int | Generator | None
+        Randomises which child receives ``p`` at each split (order only).
+    """
+    if not 0.0 < p < 1.0:
+        raise ValueError("p must be in (0, 1)")
+    rng = _as_rng(seed)
+    measure = np.array([1.0])
+    for _ in range(n_levels):
+        left = rng.random(measure.size) < 0.5
+        m_left = np.where(left, p, 1 - p)
+        m_right = 1.0 - m_left
+        nxt = np.empty(measure.size * 2)
+        nxt[0::2] = measure * m_left
+        nxt[1::2] = measure * m_right
+        measure = nxt
+    # Return as increments of the cumulative measure (a fluctuating series).
+    return measure * measure.size
+
+
+def synthetic_ieeg(
+    n_channels: int = 8,
+    n_samples: int = 5000,
+    fs: float = 1000.0,
+    *,
+    hurst: float = 0.7,
+    coupling_density: float = 0.25,
+    coupling_strength: float = 0.35,
+    noise: float = 0.1,
+    seed=None,
+) -> tuple[np.ndarray, list[str]]:
+    """A small, sparsely-coupled multi-channel recording resembling iEEG.
+
+    Each channel starts as long-range-correlated fractional Gaussian noise, then
+    a sparse random coupling matrix mixes a fraction of each channel's past into
+    its neighbours. This yields data with (a) non-trivial Hurst exponents and
+    (b) a recoverable directed coupling structure -- suitable for exercising the
+    DFA, MFDFA, and FODN paths in examples and tests.
+
+    Returns
+    -------
+    signals : numpy.ndarray
+        Array of shape ``(n_channels, n_samples)``.
+    channel_names : list of str
+        Names like ``["CH1", "CH2", ...]``.
+    """
+    rng = _as_rng(seed)
+    base = np.vstack([fgn(n_samples, hurst, seed=rng) for _ in range(n_channels)])
+
+    # Sparse random coupling matrix A (off-diagonal drives).
+    A = np.zeros((n_channels, n_channels))
+    mask = rng.random((n_channels, n_channels)) < coupling_density
+    np.fill_diagonal(mask, False)
+    A[mask] = coupling_strength * rng.standard_normal(mask.sum())
+
+    signals = base.copy()
+    for t in range(1, n_samples):
+        signals[:, t] += A @ signals[:, t - 1] + noise * rng.standard_normal(n_channels)
+
+    names = [f"CH{i + 1}" for i in range(n_channels)]
+    return signals, names