"""Build per-trial caches for both preprocessing pipelines (58-ch baseline montage, 32 Hz).
Normalisation per prep: norm=trial -> full-trial z-score (loadSubject.m), norm=running -> causal running z.
cache/<prep>/<key>.npz: eeg (T,58) float32, env (T,2) float32 (column 0 = majority-attended), att (T,) int8, t0."""
import os
import sys

import numpy as np
from joblib import Parallel, delayed

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from common_exp import CFG, cache_path, resolve_read  # noqa: E402
from common import CFG as ECFG, FS as FS_RAW, B64U, MONTAGES, b64_idx, load_eeg, load_env, load_labels, load_pp, trial_index  # noqa: E402
from scipy.signal import detrend  # noqa: E402


def fft_bandpass(x, fs, lo, hi, taper=0.25, pad_s=4.0):
    """Zero-phase FFT band-pass of a whole trial (NON-causal): linear detrend, reflect-pad pad_s on both sides,
    rfft, keep lo..hi Hz with raised-cosine edges of width `taper` Hz (0.25 Hz: EEG 1/f power below 1 Hz is large), irfft, crop."""
    x = detrend(np.asarray(x, np.float64), axis=0, type="linear")
    p = int(pad_s * fs)
    xp = np.pad(x, ((p, p), (0, 0)), mode="reflect")
    f = np.fft.rfftfreq(len(xp), 1 / fs)
    g = np.zeros_like(f)
    g[(f >= lo) & (f <= hi)] = 1.0
    a = (f > lo - taper) & (f < lo)
    g[a] = 0.5 - 0.5 * np.cos(np.pi * (f[a] - (lo - taper)) / taper)
    b = (f > hi) & (f < hi + taper)
    g[b] = 0.5 + 0.5 * np.cos(np.pi * (f[b] - hi) / taper)
    y = np.fft.irfft(np.fft.rfft(xp, axis=0) * g[:, None], n=len(xp), axis=0)
    return y[p:p + len(x)]


def load_fft(row, montage, band=(1.0, 9.0)):
    """'fft' pipeline: raw 128 Hz -> FFT band-pass 1-9 Hz (0.25-Hz cosine edges) on EEG and envelopes -> 32 Hz
    (every 4th sample; band-limited to < 9.5 Hz so no aliasing) -> montage -> CAR over present channels -> 1-s edge trim.
    Normalisation is applied by the caller (same as the other preps)."""
    key = row["key"]
    src, present = b64_idx(row)
    raw = load_eeg(key)
    x = np.zeros((raw.shape[0], 64))
    x[:, present] = np.asarray(raw[:, src[present]], dtype=np.float64)
    e = load_env(key).astype(np.float64)
    q = FS_RAW // CFG["fs"]
    x = fft_bandpass(x, FS_RAW, band[0], band[1])[::q]
    e = fft_bandpass(e, FS_RAW, band[0], band[1])[::q]
    x[:, ~present] = 0.0
    sel = np.array([B64U.index(c) for c in MONTAGES[montage]])
    x, pres = x[:, sel], present[sel]
    x[:, pres] -= x[:, pres].mean(1, keepdims=True)
    lab = load_labels(key)
    att = lab["att_col"][::q][: len(x)]
    n = min(len(x), len(e), len(att))
    k = int(round(ECFG["pipeline"]["edge_trim_s"] * CFG["fs"]))
    return dict(eeg=x[k:n - k], env=e[k:n - k], fs=CFG["fs"], att_col=att[k:n - k], t0_s=k / CFG["fs"])


def zscore_trial(x):
    """MATLAB zscore along time: N-1 std, a zero-variance column (zero-filled channel) is divided by 1."""
    x = np.asarray(x, np.float64)
    sd = x.std(0, ddof=1)
    sd[sd == 0] = 1.0
    return (x - x.mean(0)) / sd


def causal_ea(x, fs, tau_s=60.0, block_s=1.0, shrink=0.1, R0=None, return_R=False, n0=None):
    """Causal running Euclidean alignment (whitening by R^-1/2). R = exponentially weighted spatial covariance of
    PAST 1-s blocks only (time constant tau_s), shrunk towards the identity; block k is whitened with R estimated
    from blocks < k (R starts at the identity: data are z-scored). Zero (absent) channels are left untouched.
    Not an exempted whole-trial method, hence causal (1-s lookahead rule).
    n0 (s): weight of the start value R0 / identity, as seconds of data. None = tau_s (the original recursion). A small n0
    gives a fast warm-up: a plain cumulative mean of the trial's own blocks at first, exponential forgetting (tau_s) later."""
    x = np.asarray(x, np.float64)
    pres = x.std(0) > 0
    y = x.copy()
    xp = x[:, pres]
    C = xp.shape[1]
    R = np.eye(C) if R0 is None or R0.shape != (C, C) else R0.copy()   # R0: carried over from earlier trials
    a = block_s / tau_s
    N = None if n0 is None else n0 / block_s
    B = int(block_s * fs)
    for s0 in range(0, len(xp), B):
        blk = xp[s0:s0 + B]
        Rs = (1 - shrink) * R + shrink * np.trace(R) / C * np.eye(C)
        w, V = np.linalg.eigh(Rs)
        y[s0:s0 + B, pres] = blk @ (V * (1.0 / np.sqrt(np.maximum(w, 1e-8)))) @ V.T
        Cb = (blk.T @ blk) / max(len(blk), 1)
        if n0 is None:
            R = (1 - a) * R + a * Cb
        else:                                             # weighted mean with effective count N (in blocks), N -> tau
            N1 = (1 - a) * N + 1.0
            R, N = ((1 - a) * N * R + Cb) / N1, N1
    return (y, R) if return_R else y


def causal_tw(x, fs, order=6, tau_s=60.0, block_s=1.0, shrink=0.05, strength=1.0, state=None, return_state=False,
              recolor_acf=None):
    """Causal TEMPORAL whitening per channel: adaptive linear-prediction error filter.
    y(t) = (x(t) - strength * sum_k a_k x(t-k)) / sd_err, with the AR(order) coefficients a of every channel solved
    (Yule-Walker, diagonal loading shrink * r0) from the exponentially weighted autocovariances r_0..r_order of PAST
    1-s blocks only (time constant tau_s; `state` = r carried across a subject's trials). Block k is filtered with
    coefficients estimated from blocks < k; the first block of a subject is unfiltered (r = [1, 0, ...]: data are
    z-scored). sd_err = sqrt of the predicted error variance (from the same past statistics), so the output has about
    unit variance. Flattens each channel's spectrum inside the pass band (1/f slope, alpha peak), which differs between
    subjects and datasets. Filter memory restarts at a trial start (zeros). Absent (zero) channels stay zero.
    Not an exempted whole-trial method, hence strictly causal.
    recolor_acf (autocorrelation at lags 1..order of a CANONICAL spectrum): spectral STANDARDISATION instead of
    whitening: the whitened signal is re-coloured by the FIXED all-pole filter of that canonical AR model (same
    shrinkage), so every channel of every recording gets the same canonical spectral shape. Recordings whose spectrum is
    already canonical come out nearly unchanged, atypical ones (e.g. KUL-AV-GC) are pulled to the canonical shape."""
    x = np.asarray(x, np.float64)
    T, C = x.shape
    p, B, al = int(order), int(block_s * fs), block_s / tau_s
    r = np.zeros((C, p + 1)) if state is None else state.copy()
    if state is None:
        r[:, 0] = 1.0
    xp = np.vstack([np.zeros((p, C)), x])                       # p zeros of filter memory before the trial
    y = np.empty_like(x)
    ii = np.abs(np.arange(p)[:, None] - np.arange(p)[None, :])
    for s0 in range(0, T, B):
        n = min(B, T - s0)
        seg = xp[s0:s0 + n + p]                                 # block with its p preceding samples
        ok = r[:, 0] > 1e-12
        a = np.zeros((C, p))
        if ok.any():
            R = r[ok][:, ii] + shrink * r[ok, :1, None] * np.eye(p)
            a[ok] = np.linalg.solve(R, r[ok, 1:, None])[..., 0]
        a *= strength
        pred = sum(seg[p - k:p - k + n] * a[:, k - 1] for k in range(1, p + 1))
        ev = r[:, 0] - 2 * (a * r[:, 1:]).sum(1) + np.einsum("ci,cij,cj->c", a, r[:, ii], a)   # error variance (past)
        y[s0:s0 + n] = (seg[p:] - pred) / np.sqrt(np.where(ok, np.maximum(ev, 1e-6 * r[:, 0]), 1.0))
        rb = np.stack([(seg[p:] * seg[p - k:p - k + n]).mean(0) for k in range(p + 1)], 1)
        r = (1 - al) * r + al * rb
    if recolor_acf is not None:
        from scipy.signal import lfilter
        rc = np.concatenate([[1.0], np.asarray(recolor_acf, float)[:p]])
        ac = np.linalg.solve(rc[ii] + shrink * np.eye(p), rc[1:])
        evc = rc[0] - 2 * ac @ rc[1:] + ac @ rc[ii] @ ac
        y = lfilter([np.sqrt(evc)], np.concatenate([[1.0], -ac]), y, axis=0)     # causal, zero state at trial start
    y[:, x.std(0) == 0] = 0.0
    return (y, r) if return_state else y


BEQ_BANDS = ((1.0, 2.5), (2.5, 5.0), (5.0, 9.0))


def causal_band_eq(x, fs, state=None, tau_s=60.0, block_s=1.0):
    """F1, causal spectral equalisation: split each channel into BEQ_BANDS with CAUSAL Butterworth band-passes,
    scale every band of every channel by 1/sqrt(its running power) estimated from PAST 1-s blocks only (EW, tau_s;
    state carried across a subject's trials), then sum the bands. Equalises the within-band spectral shape
    (1/f slope, alpha leakage near 9 Hz) that differs between datasets. Absent (zero) channels stay zero."""
    from scipy.signal import butter, sosfilt
    x = np.asarray(x, np.float64)
    pres = x.std(0) > 0
    C, B = x.shape[1], int(block_s * fs)
    bands = [sosfilt(butter(2, [lo, hi], "bandpass", fs=fs, output="sos"), x, axis=0) for lo, hi in BEQ_BANDS]
    Pw = np.full((len(bands), C), 1.0 / len(bands)) if state is None else state.copy()
    a = block_s / tau_s
    y = np.zeros_like(x)
    for s0 in range(0, len(x), B):
        for i, b in enumerate(bands):
            blk = b[s0:s0 + B]
            y[s0:s0 + B] += blk / np.sqrt(np.maximum(Pw[i], 1e-6))
            Pw[i] = (1 - a) * Pw[i] + a * (blk ** 2).mean(0)
    y[:, ~pres] = 0.0
    return y / np.sqrt(len(bands)), Pw


def gamma_envelope(row, n_out, k_trim):
    """E2: causal 30-40 Hz envelope per montage channel from the RAW 128 Hz EEG: CAR -> causal band-pass 30-40 Hz
    (Butterworth 4) -> |.| -> causal low-pass 8 Hz -> every 4th sample (32 Hz) -> same 1-s edge trim as the other
    preps -> causal running robust z (EDA running_z; no second full-trial z-score)."""
    from scipy.signal import butter, sosfilt
    from common import B64U, MONTAGES, b64_idx, load_eeg, running_z
    src, present = b64_idx(row)
    raw = load_eeg(row["key"])
    x = np.zeros((raw.shape[0], 64))
    x[:, present] = np.asarray(raw[:, src[present]], dtype=np.float64)
    sel = np.array([B64U.index(c) for c in MONTAGES[CFG["montage"]]])
    x, pres = x[:, sel], present[sel]
    x[:, pres] -= x[:, pres].mean(1, keepdims=True)
    fs_raw = 128
    g = np.abs(sosfilt(butter(4, [30, 40], "bandpass", fs=fs_raw, output="sos"), x, axis=0))
    g = sosfilt(butter(2, 8, "lowpass", fs=fs_raw, output="sos"), g, axis=0)[::fs_raw // CFG["fs"]]
    g = running_z(g, CFG["fs"])
    g[:, ~pres] = 0.0
    g = g[k_trim:k_trim + n_out]
    if len(g) < n_out:
        g = np.vstack([g, np.zeros((n_out - len(g), g.shape[1]))])
    return g


# Planar positions of the 58-channel montage (x = right, y = anterior). Used only to pick anatomical neighbours
# for the surface Laplacian. Distances are approximate 10-10 spacings, not a digitised cap.
_LAP_XY = {
    "FP1": (-0.35, 1.00), "FPZ": (0.00, 1.05), "FP2": (0.35, 1.00),
    "AF3": (-0.35, 0.82), "AF4": (0.35, 0.82),
    "F7": (-0.95, 0.55), "F5": (-0.72, 0.62), "F3": (-0.48, 0.66), "F1": (-0.24, 0.68), "FZ": (0.00, 0.70),
    "F2": (0.24, 0.68), "F4": (0.48, 0.66), "F6": (0.72, 0.62), "F8": (0.95, 0.55),
    "FT7": (-1.05, 0.28), "FC5": (-0.78, 0.36), "FC3": (-0.52, 0.40), "FC1": (-0.26, 0.42), "FCZ": (0.00, 0.44),
    "FC2": (0.26, 0.42), "FC4": (0.52, 0.40), "FC6": (0.78, 0.36), "FT8": (1.05, 0.28),
    "T7": (-1.12, 0.00), "C5": (-0.84, 0.05), "C3": (-0.56, 0.08), "C1": (-0.28, 0.10), "CZ": (0.00, 0.10),
    "C2": (0.28, 0.10), "C4": (0.56, 0.08), "C6": (0.84, 0.05), "T8": (1.12, 0.00),
    "TP7": (-1.05, -0.28), "CP5": (-0.78, -0.22), "CP3": (-0.52, -0.18), "CP1": (-0.26, -0.16), "CPZ": (0.00, -0.14),
    "CP2": (0.26, -0.16), "CP4": (0.52, -0.18), "CP6": (0.78, -0.22), "TP8": (1.05, -0.28),
    "P7": (-0.95, -0.55), "P5": (-0.72, -0.50), "P3": (-0.48, -0.46), "P1": (-0.24, -0.44), "PZ": (0.00, -0.42),
    "P2": (0.24, -0.44), "P4": (0.48, -0.46), "P6": (0.72, -0.50), "P8": (0.95, -0.55),
    "PO7": (-0.55, -0.78), "PO3": (-0.30, -0.72), "POZ": (0.00, -0.68), "PO4": (0.30, -0.72), "PO8": (0.55, -0.78),
    "O1": (-0.22, -0.95), "OZ": (0.00, -1.00), "O2": (0.22, -0.95),
}


def laplacian_neighbors(max_dist=0.42, k=4):
    """Up to k anatomical neighbours per montage channel, within max_dist of the planar 10-10 layout."""
    names = MONTAGES[CFG["montage"]]
    xy = np.array([_LAP_XY[c] for c in names], float)
    d = np.sqrt(((xy[:, None, :] - xy[None, :, :]) ** 2).sum(-1))
    np.fill_diagonal(d, np.inf)
    neigh = []
    for i in range(len(names)):
        order = np.argsort(d[i])
        neigh.append([int(j) for j in order if d[i, j] <= max_dist][:k])
    return neigh


LAP_NEIGH = laplacian_neighbors()


def causal_lowpass(x, hz, fs=None):
    """Causal Butterworth low-pass. Uses only the present and the past (no second filtfilt)."""
    from scipy.signal import butter, sosfilt
    fs = CFG["fs"] if fs is None else fs
    x = np.asarray(x, np.float64)
    sos = butter(2, hz, "lowpass", fs=fs, output="sos")
    y = sosfilt(sos, x, axis=0)
    dead = np.asarray(x).std(0) == 0
    y[:, dead] = 0.0
    return y


def surface_laplacian(x, neigh=None):
    """Hjorth surface Laplacian: each present channel minus the mean of its present neighbours.

    Same-time spatial mix (no samples from the future, no other trial). Absent channels stay zero.
    Neighbours that are absent in this recording are dropped, so a missing electrode is not interpolated
    and is not used as a reference."""
    x = np.asarray(x, np.float64)
    neigh = LAP_NEIGH if neigh is None else neigh
    pres = x.std(0) > 0
    y = np.zeros_like(x)
    for i in np.flatnonzero(pres):
        nb = [j for j in neigh[i] if pres[j]]
        y[:, i] = x[:, i] - (x[:, nb].mean(1) if nb else 0.0)
    return y


def laplacian_prior(R, pres, neigh=None):
    """Map a sensor-space covariance into the Laplacian space of the channels that are present."""
    neigh = LAP_NEIGH if neigh is None else neigh
    idx = np.flatnonzero(pres)
    inv = {int(c): i for i, c in enumerate(idx)}
    k = len(idx)
    L = np.eye(k)
    for i, c in enumerate(idx):
        nb = [inv[j] for j in neigh[int(c)] if j in inv]
        if nb:
            L[i, nb] = -1.0 / len(nb)
    Rp = np.asarray(R, float)[np.ix_(idx, idx)]
    return L @ Rp @ L.T


def nearest_bipolar(x, neigh=None):
    """Nearest-neighbour bipolar: each present channel minus its single nearest present neighbour.

    Distinct from surface_laplacian (which subtracts the mean of ≤k neighbours). Keeps C channels.
    Absent channels / channels whose neighbour is absent stay as the (possibly CAR'd) sensor value.
    """
    x = np.asarray(x, np.float64)
    neigh = LAP_NEIGH if neigh is None else neigh
    pres = x.std(0) > 0
    y = x.copy()
    for i in np.flatnonzero(pres):
        nb = [j for j in neigh[i] if pres[j]]
        if nb:
            y[:, i] = x[:, i] - x[:, nb[0]]
    return y


def bipolar_prior(R, pres, neigh=None):
    """Map a sensor-space covariance into nearest-neighbour bipolar space (L R L^T)."""
    neigh = LAP_NEIGH if neigh is None else neigh
    idx = np.flatnonzero(pres)
    inv = {int(c): i for i, c in enumerate(idx)}
    k = len(idx)
    L = np.eye(k)
    for i, c in enumerate(idx):
        nb = [inv[j] for j in neigh[int(c)] if j in inv]
        if nb:
            L[i, nb[0]] = -1.0
    Rp = np.asarray(R, float)[np.ix_(idx, idx)]
    return L @ Rp @ L.T


def _montage_unit_sphere():
    """Approximate 10–10 positions as unit-sphere vectors from planar _LAP_XY (hemisphere projection)."""
    names = MONTAGES[CFG["montage"]]
    xy = np.array([_LAP_XY[c] for c in names], float)
    r = np.sqrt((xy ** 2).sum(1))
    scale = float(r.max()) * 1.02  # keep all electrodes inside the unit disk
    xy_n = xy / scale
    z = np.sqrt(np.maximum(0.0, 1.0 - (xy_n ** 2).sum(1)))
    pos = np.column_stack([xy_n[:, 0], xy_n[:, 1], z])
    pos /= np.linalg.norm(pos, axis=1, keepdims=True)
    return pos


def _legendre_Pn(n_max, x):
    """P_0..P_n_max evaluated at x (any shape) via Bonnet recurrence. Returns (n_max+1, *x.shape)."""
    x = np.asarray(x, float)
    out = np.empty((n_max + 1,) + x.shape, float)
    out[0] = 1.0
    if n_max >= 1:
        out[1] = x
    for n in range(1, n_max):
        out[n + 1] = ((2 * n + 1) * x * out[n] - n * out[n - 1]) / (n + 1)
    return out


def spherical_spline_Gh(stiffness=4, n_terms=50, pos=None):
    """Perrin et al. spherical-spline G and H kernels on the 58-ch montage (or a subset of unit vectors).

    G_ij = Σ_n (2n+1) / (n^m (n+1)^m) P_n(cos θ_ij)
    H_ij = -Σ_n (2n+1) / (n^{m-1} (n+1)^{m-1}) P_n(cos θ_ij)
    with m = stiffness. Same-time spatial operator (no temporal lookahead).
    """
    pos = _montage_unit_sphere() if pos is None else np.asarray(pos, float)
    cosang = np.clip(pos @ pos.T, -1.0, 1.0)
    Pn = _legendre_Pn(n_terms, cosang)  # (n_terms+1, C, C); use n=1..n_terms
    G = np.zeros_like(cosang)
    H = np.zeros_like(cosang)
    m = int(stiffness)
    for n in range(1, n_terms + 1):
        two = 2 * n + 1
        G += two / ((n ** m) * ((n + 1) ** m)) * Pn[n]
        H -= two / ((n ** (m - 1)) * ((n + 1) ** (m - 1))) * Pn[n]
    return G, H


def spherical_csd_matrix(pres=None, stiffness=4, n_terms=50, lam=1e-5):
    """C×C Perrin CSD transform for (a subset of) present channels: y = x @ L.T on present cols.

    Solves the rigid spherical-spline system on the present electrodes only (absent stay zero):
      [G+λI  1] [c ]   [v]
      [1^T    0] [c0] = [0]
    then CSD = H @ c. Equivalent linear map L such that csd = L @ v (column vector).
    Distinct from nearest-neighbour surface_laplacian (ch − mean of ≤k neighbours).
    """
    names = MONTAGES[CFG["montage"]]
    C = len(names)
    pos_all = _montage_unit_sphere()
    if pres is None:
        pres = np.ones(C, bool)
    else:
        pres = np.asarray(pres, bool)
    idx = np.flatnonzero(pres)
    k = len(idx)
    Lfull = np.zeros((C, C), float)
    if k == 0:
        return Lfull
    G, H = spherical_spline_Gh(stiffness=stiffness, n_terms=n_terms, pos=pos_all[idx])
    # Augmented system (Perrin): (G+λI) c + 1 c0 = v,  1^T c = 0.
    A = np.zeros((k + 1, k + 1), float)
    A[:k, :k] = G + lam * np.eye(k)
    A[:k, k] = 1.0
    A[k, :k] = 1.0
    # Map v -> csd: csd = H @ c, with [c;c0] = A^{-1} [v; 0].
    # So c = Ainv[:k,:k] @ v  (last column of Ainv multiplies the 0 RHS entry).
    Ainv = np.linalg.inv(A)
    Tc = H @ Ainv[:k, :k]          # (k, k): csd_present = Tc @ v_present
    Lfull[np.ix_(idx, idx)] = Tc
    return Lfull


# Precompute the full-montage CSD operator (all 58 present); subsets rebuild on the fly.
_SPH_CSD_FULL = None


def _sph_csd_full():
    global _SPH_CSD_FULL
    if _SPH_CSD_FULL is None:
        _SPH_CSD_FULL = spherical_csd_matrix()
    return _SPH_CSD_FULL


def spherical_surface_laplacian(x, stiffness=4, n_terms=50, lam=1e-5):
    """Spherical-spline / CSD surface Laplacian on present channels. Keeps C channels.

    Same-time spatial mix only. Absent (zero-variance) channels stay zero and are excluded
    from the spline solve (no interpolation of missing electrodes).
    """
    x = np.asarray(x, np.float64)
    pres = x.std(0) > 0
    if not pres.any():
        return np.zeros_like(x)
    if pres.all():
        L = _sph_csd_full()
    else:
        L = spherical_csd_matrix(pres=pres, stiffness=stiffness, n_terms=n_terms, lam=lam)
    y = x @ L.T
    y[:, ~pres] = 0.0
    return y


def spherical_laplacian_prior(R, pres, stiffness=4, n_terms=50, lam=1e-5):
    """Map a sensor-space covariance into spherical-spline CSD space (L R L^T)."""
    idx = np.flatnonzero(pres)
    L = spherical_csd_matrix(pres=pres, stiffness=stiffness, n_terms=n_terms, lam=lam)
    Lp = L[np.ix_(idx, idx)]
    Rp = np.asarray(R, float)[np.ix_(idx, idx)]
    return Lp @ Rp @ Lp.T


def ea_prior(P, x):
    """Start value of the EA covariance: None (identity) or the fixed population prior of build_ea_prior.py, cut to
    the channels present in this recording (prep key ea_prior). A Laplacian/bipolar prep maps that prior by L R L^T so the
    shrinkage target lives in the same space as the spatially remapped EEG."""
    if not P.get("ea_prior"):
        return None
    R = np.load(resolve_read(os.path.join("cache", f"ea_prior_{P['ea_prior']}.npy")))
    pres = np.asarray(x).std(0) > 0
    if P.get("laplacian"):
        return laplacian_prior(R, pres)
    if P.get("spherical_laplacian"):
        return spherical_laplacian_prior(R, pres)
    if P.get("bipolar"):
        return bipolar_prior(R, pres)
    return R[np.ix_(pres, pres)]

def trial_order(rows):
    """Recording order of a subject's trials: orig_pos when the dataset stores it (>= 0), else the trial number."""
    from common import load_labels
    def pos(r):
        op = load_labels(r["key"]).get("orig_pos")
        v = int(np.ravel(op)[0]) if op is not None and np.size(op) else -1
        return (v if v >= 0 else 10 ** 6, int(r["trial"]))
    return sorted(rows, key=pos)


def build_subject_carry(rows, prep):
    """Causal EA with the covariance estimate CARRIED across the subject's trials in recording order (a device
    keeps adapting to its user). Still causal: each trial only uses earlier samples of itself and earlier trials."""
    P = CFG["preps"][prep]
    R, BQ, TW, n = None, None, None, 0
    for row in trial_order(rows):
        p = cache_path(prep, row["key"])
        d = load_pp(row, P["variant"], CFG["montage"], do_car=True, do_runz=False, do_trim=True)
        d["eeg"], d["env"] = zscore_trial(d["eeg"]), zscore_trial(d["env"])
        if P.get("band_eq"):
            d["eeg"], BQ = causal_band_eq(d["eeg"], CFG["fs"], state=BQ)
        if P.get("tw_order"):                             # causal temporal whitening per channel, before the spatial EA
            d["eeg"], TW = causal_tw(d["eeg"], CFG["fs"], order=P["tw_order"], strength=P.get("tw_strength", 1.0),
                                     state=TW, return_state=True, recolor_acf=P.get("tw_recolor_acf"))
        d["eeg"], R = causal_ea(d["eeg"], CFG["fs"], tau_s=P.get("ea_tau", 60.0), R0=R, return_R=True)
        if not os.path.exists(p):
            os.makedirs(os.path.dirname(p), exist_ok=True)
            np.savez(p, eeg=d["eeg"].astype(np.float32), env=d["env"].astype(np.float32),
                     att=d["att_col"].astype(np.int8), t0=d["t0_s"])
            n += 1
    return n


def causal_phase(x, fs, bands=((1.0, 4.0), (4.0, 8.0)), taps=31):
    """E1: CAUSAL instantaneous phase per band: causal Butterworth band-pass, then an analytic signal from a causal
    FIR Hilbert transformer (taps = 2D+1, equiripple) paired with the band signal delayed by D samples:
    z(t) = x_b(t - D) + i H{x_b}(t), i.e. the phase of time t - D computed from samples <= t (a fixed delay, no
    lookahead). Returns [cos(phase), sin(phase)] per band and channel -> (T, 4 C) for two bands."""
    from scipy.signal import butter, remez, sosfilt, lfilter
    D = taps // 2
    h = remez(taps, [0.6, fs / 2 - 0.6], [1.0], type="hilbert", fs=fs)
    out = []
    for lo, hi in bands:
        xb = sosfilt(butter(2, [lo, hi], "bandpass", fs=fs, output="sos"), x, axis=0)
        im = -lfilter(h, [1.0], xb, axis=0)               # remez "hilbert" gives +90 deg; analytic signal needs -90
        re = np.vstack([np.zeros((D, x.shape[1])), xb[:-D]])
        mag = np.sqrt(re ** 2 + im ** 2) + 1e-9
        c, s_ = re / mag, im / mag
        c[:, x.std(0) == 0] = 0.0
        s_[:, x.std(0) == 0] = 0.0
        out += [c, s_]
    return np.hstack(out)


def build_phase(row, prep):
    """prep with 'phase_of': base prep cache + causal cos/sin phase channels (delta, theta) of its EEG."""
    P = CFG["preps"][prep]
    p = cache_path(prep, row["key"])
    if os.path.exists(p):
        return 0
    z = np.load(cache_path(P["phase_of"], row["key"]))
    ph = causal_phase(z["eeg"].astype(np.float64), CFG["fs"])
    os.makedirs(os.path.dirname(p), exist_ok=True)
    np.savez(p, eeg=np.hstack([z["eeg"], ph.astype(np.float32)]), env=z["env"], att=z["att"], t0=z["t0"])
    return 1


def build_gamma(row, prep):
    """prep with 'gamma_of': copy the base prep's cache and append the 58 causal gamma-envelope channels."""
    P = CFG["preps"][prep]
    p = cache_path(prep, row["key"])
    if os.path.exists(p):
        return 0
    z = np.load(cache_path(P["gamma_of"], row["key"]))
    k = int(round(float(z["t0"]) * CFG["fs"]))
    g = gamma_envelope(row, len(z["eeg"]), k)
    os.makedirs(os.path.dirname(p), exist_ok=True)
    np.savez(p, eeg=np.hstack([z["eeg"], g.astype(np.float32)]), env=z["env"], att=z["att"], t0=z["t0"])
    return 1


def build(row, prep):
    p = cache_path(prep, row["key"])
    if os.path.exists(p):
        return 0
    P = CFG["preps"][prep]
    if P["variant"] == "fft":
        assert P["norm"] == "trial"
        d = load_fft(row, CFG["montage"], tuple(P.get("band", (1.0, 9.0))))
    else:
        d = load_pp(row, P["variant"], CFG["montage"], do_car=True, do_runz=P["norm"] == "running", do_trim=True)
    # B1: cwide is 64 Hz; causal LP then integer decimation to CFG["fs"] (32) before trial-z / EA.
    if P.get("wide_ds"):
        q = int(P["wide_ds"])
        assert d["fs"] == CFG["fs"] * q, (d["fs"], CFG["fs"], q)
        if P.get("wide_lp_hz"):
            d["eeg"] = causal_lowpass(d["eeg"], P["wide_lp_hz"], fs=d["fs"])
            d["env"] = causal_lowpass(d["env"], P["wide_lp_hz"], fs=d["fs"])
        d["eeg"], d["env"] = d["eeg"][::q], d["env"][::q]
        d["att_col"] = d["att_col"][::q]
        d["fs"] = CFG["fs"]
        # t0_s already in seconds from load_pp trim; unchanged by uniform decimation after trim
    if P["norm"] == "trial":
        # statistics over the trimmed trial, so the 1-s filter warm-up of the causal pipeline cannot inflate them
        d["eeg"], d["env"] = zscore_trial(d["eeg"]), zscore_trial(d["env"])
    if P.get("lowpass_hz"):
        d["eeg"] = causal_lowpass(d["eeg"], P["lowpass_hz"])
        d["env"] = causal_lowpass(d["env"], P["lowpass_hz"])
    if P.get("laplacian"):
        d["eeg"] = surface_laplacian(d["eeg"])
    if P.get("spherical_laplacian"):
        d["eeg"] = spherical_surface_laplacian(d["eeg"])
    if P.get("bipolar"):
        d["eeg"] = nearest_bipolar(d["eeg"])
    if P.get("ea") == "causal":
        d["eeg"] = causal_ea(d["eeg"], CFG["fs"], tau_s=P.get("ea_tau", 60.0), R0=ea_prior(P, d["eeg"]), n0=P.get("ea_n0"),
                             shrink=P.get("ea_shrink", 0.1))
    assert d["fs"] == CFG["fs"]
    os.makedirs(os.path.dirname(p), exist_ok=True)
    np.savez(p, eeg=d["eeg"].astype(np.float32), env=d["env"].astype(np.float32), att=d["att_col"].astype(np.int8),
             t0=d["t0_s"])
    return 1


if __name__ == "__main__":
    ti = trial_index()
    for prep in (sys.argv[1:] or CFG["preps"]):
        if CFG["preps"][prep].get("phase_of"):
            n = Parallel(n_jobs=4)(delayed(build_phase)(r, prep) for _, r in ti.iterrows())
            print(prep, "built", sum(n), "of", len(ti))
            continue
        if CFG["preps"][prep].get("gamma_of"):
            n = Parallel(n_jobs=4)(delayed(build_gamma)(r, prep) for _, r in ti.iterrows())
            print(prep, "built", sum(n), "of", len(ti))
            continue
        if CFG["preps"][prep].get("ea_carry"):
            subs = [list(g.to_dict("records")) for _, g in ti.groupby("subj_uid")]
            n = Parallel(n_jobs=4)(delayed(build_subject_carry)(rs, prep) for rs in subs)
            print(prep, "built", sum(n), "of", len(ti))
            continue
        n = Parallel(n_jobs=4)(delayed(build)(r, prep) for _, r in ti.iterrows())
        print(prep, "built", sum(n), "of", len(ti))
