# Setup: dependencies, the shared helpers, non-interactive plotting.
import importlib.util
import subprocess
import sys
import warnings
from pathlib import Path

# 1. Dependencies are pinned in notebooks/requirements.txt.  Nothing is installed when the
#    pinned stack is already present (local runs, CI); a fresh Colab or Binder kernel installs
#    it once.  On Colab, run from a clone of the repository so that notebooks/_shared/ is
#    available (repository URL: TODO(confirm), spec section 13 item 3).
_needed = ('mne', 'scipy', 'matplotlib', 'pooch', 'specparam')
_missing = [p for p in _needed if importlib.util.find_spec(p) is None]
if _missing:
    _req = next((d / "requirements.txt" for d in (Path.cwd(), *Path.cwd().parents)
                 if (d / "requirements.txt").exists()), None)
    _cmd = [sys.executable, "-m", "pip", "install", "-q"]
    _cmd += ["-r", str(_req)] if _req else ["mne==1.10.2", "pooch>=1.8"]
    subprocess.check_call(_cmd)

# 2. Shared helpers, located relative to the working directory -- notebooks/<level>/ or
#    notebooks/ -- never through an absolute path.
_shared = next((d / "_shared" for d in (Path.cwd(), *Path.cwd().parents)
                if (d / "_shared" / "helpers_l4.py").exists()), None)
if _shared is None:
    raise FileNotFoundError("start the kernel in notebooks/L4/ (or notebooks/) so that "
                            "_shared/helpers_l4.py is found")
sys.path.insert(0, str(_shared))
import helpers
import helpers_l1
import helpers_l4 as L4
from scipy import signal as sps
from scipy import stats as sstats

# 3. Plotting: Jupyter's default inline backend renders static PNGs through Agg (no windows,
#    nothing blocks); outside Jupyter the helpers select Agg.  Every MNE figure is requested
#    with show=False and each figure cell ends with plt.show().
import matplotlib.pyplot as plt
import numpy as np
import mne

mne.set_log_level("WARNING")
plt.rcParams["figure.dpi"] = 72
print(f"MNE {mne.__version__}; helpers_l4 imported from notebooks/_shared")
print(f"downloads go to {helpers_l1.download_dir().name}/ (resolved relative to the working directory, "
      "or $EEG_COURSE_DOWNLOADS) and are deleted at the end of this notebook")

FULL_COHORT = False          # True: every loadable subject (~103, ~740 MB) -- a local run, not CI

CHANNELS = ["C3", "C4"]
if FULL_COHORT:
    SUBJECTS = [s for s in (f"S{i:03d}" for i in range(1, 110))
                if s not in helpers.EEGBCI_EXCLUDE_DEFAULT and s not in helpers.EEGBCI_EXCLUDE_OPTIONAL]
else:
    SUBJECTS = list(L4.SUBSET_DEFAULT)
print(f"FULL_COHORT = {FULL_COHORT} -> {len(SUBJECTS)} subjects: {SUBJECTS[0]}..{SUBJECTS[-1]}")
print(f"excluded always : {', '.join(helpers.EEGBCI_EXCLUDE_DEFAULT)} -- "
      f"'{L4.DATASETS_L4['ds-eegbci']['caveats'][1]}'")
print(f"excluded by default: {', '.join(helpers.EEGBCI_EXCLUDE_OPTIONAL)} (same caveat)")
print(f"download estimate: {len(SUBJECTS) * len(L4.MI_RUNS) * 2.4:.0f} MB, deleted at the end")
for key, value in L4.MI_PIPELINE.items():
    print(f"  {key:16s} : {value}")

import time

dl = L4.Downloads("nb-c4").start()
t0 = time.time()
per_subject, failures = {}, []
for sid in SUBJECTS:
    try:
        ep, nfo = L4.load_imagery_epochs(sid, L4.MI_RUNS, dl)
        rec = {"info": nfo}
        for cond in ("T1", "T2"):
            if cond not in ep.event_id or len(ep[cond]) == 0:
                raise ValueError(f"no {cond} epochs")
            X = ep[cond].get_data(picks=CHANNELS) * 1e6
            r = L4.morlet_power(X, sfreq=float(ep.info["sfreq"]), times=ep.times)
            rec[cond] = r["power"]                      # (n_trials, 2, n_freqs, n_times)
        # pre-cue baseline spectrum for the peak check, from the same epochs, C3 and C4
        base = ep.copy().crop(tmin=L4.MI_TMIN, tmax=0.0).get_data(picks=CHANNELS) * 1e6
        rec["baseline_segments"] = base.reshape(-1, base.shape[-1])
        rec["sfreq"] = float(ep.info["sfreq"])
        per_subject[sid] = rec
        freqs, times = r["freqs"], r["times"]
    except Exception as exc:
        failures.append({"subject": sid, "reason": f"{type(exc).__name__}: {exc}"})
        print(f"  {sid}: FAILED -- {type(exc).__name__}: {exc}")
    finally:
        dl.cleanup()                                    # this subject's EDFs go before the next one arrives
COHORT_S = time.time() - t0
edge = L4.edge_seconds(freqs, L4.TF_CYCLES)
safe = (times >= times[0] + edge.max()) & (times <= times[-1] - edge.max())
print(f"\n{len(per_subject)} of {len(SUBJECTS)} subjects processed in {COHORT_S:.0f} s "
      f"({COHORT_S / max(len(per_subject), 1):.1f} s each); {len(failures)} failure(s)")
print(f"edge-safe window {times[safe][0]:+.3f}..{times[safe][-1]:+.3f} s "
      f"({safe.sum()} of {len(times)} points); baseline {L4.TF_BASELINE[0]:g}..{L4.TF_BASELINE[1]:g} s ends "
      f"{L4.TF_BASELINE[0] - (times[0] + edge.max()):+.3f} s after the edge region, so no baseline sample is "
      f"made of zero padding")

rows = []
lat = {}
for sid, rec in per_subject.items():
    row = {"subject": sid, "T1 trials": rec["info"]["n_epochs"].get("T1", 0),
           "T2 trials": rec["info"]["n_epochs"].get("T2", 0),
           "max |sample| (uV)": max(rec["info"]["max_abs_uv"].values())}
    pc = {}
    for cond in ("T1", "T2"):
        P = rec[cond].mean(0)                            # (2, n_freqs, n_times) raw, trial-averaged
        b = (times >= L4.TF_BASELINE[0]) & (times <= L4.TF_BASELINE[1])
        pc[cond] = np.stack([100 * (P[k] - P[k][:, b].mean(1, keepdims=True))
                             / P[k][:, b].mean(1, keepdims=True) for k in range(len(CHANNELS))])
        for band_name, band in (("mu", L4.MU_BAND), ("beta", L4.BETA_BAND)):
            for k, ch in enumerate(CHANNELS):
                row[f"{cond} {band_name} {ch} (%)"] = L4.band_erd(
                    rec[cond][:, k], freqs, times, band, baseline=L4.TF_BASELINE, active=L4.TF_ACTIVE,
                    order="band-first")
    lat[sid] = {c: pc[c][0] - pc[c][1] for c in ("T1", "T2")}
    row["T2 contralateral (C3 < C4)"] = row["T2 mu C3 (%)"] < row["T2 mu C4 (%)"]
    row["T1 contralateral (C4 < C3)"] = row["T1 mu C4 (%)"] < row["T1 mu C3 (%)"]
    rows.append(row)
cols = ["subject", "T1 trials", "T2 trials", "max |sample| (uV)",
        "T2 mu C3 (%)", "T2 mu C4 (%)", "T1 mu C3 (%)", "T1 mu C4 (%)",
        "T2 beta C3 (%)", "T2 beta C4 (%)", "T1 beta C3 (%)", "T1 beta C4 (%)",
        "T2 contralateral (C3 < C4)", "T1 contralateral (C4 < C3)"]
print(f"Per subject: percent change from baseline, band-first order, "
      f"{L4.TF_ACTIVE[0]:g}..{L4.TF_ACTIVE[1]:g} s against {L4.TF_BASELINE[0]:g}..{L4.TF_BASELINE[1]:g} s")
print(L4.fmt_table(rows, cols, floatfmt="{:.1f}"))
n_t2 = sum(r["T2 contralateral (C3 < C4)"] for r in rows)
n_t1 = sum(r["T1 contralateral (C4 < C3)"] for r in rows)
print()
print(f"Contralateral dominance in the mu band: {n_t2} of {len(rows)} subjects for right-hand imagery "
      f"(C3 more negative than C4), {n_t1} of {len(rows)} for left-hand imagery.")
print(f"Binomial test against chance (p = .5): right-hand p = "
      f"{sstats.binomtest(n_t2, len(rows), 0.5).pvalue:.4f}, left-hand p = "
      f"{sstats.binomtest(n_t1, len(rows), 0.5).pvalue:.4f}")

fig, axes = plt.subplots(2, 3, figsize=(17.5, 8.0))
G = {c: np.mean([np.stack([100 * (per_subject[s][c].mean(0)[k]
                                  - per_subject[s][c].mean(0)[k][:, (times >= L4.TF_BASELINE[0])
                                                                & (times <= L4.TF_BASELINE[1])].mean(1, keepdims=True))
                           / per_subject[s][c].mean(0)[k][:, (times >= L4.TF_BASELINE[0])
                                                          & (times <= L4.TF_BASELINE[1])].mean(1, keepdims=True)
                           for k in range(2)]) for s in per_subject], axis=0)
     for c in ("T1", "T2")}
for r, cond in enumerate(("T2", "T1")):
    for k, ch in enumerate(CHANNELS):
        L4.plot_tfr(G[cond][k], freqs, times, ax=axes[r, k], vlim=(-40, 40), edge_s=edge,
                    baseline=L4.TF_BASELINE, cbar_label="Power change from baseline (%)",
                    title=f"{cond} ({L4.MI_CONDITIONS[cond]}) at {ch}\ngrand average, "
                          f"{len(per_subject)} subjects (%)")
    L4.plot_tfr(G[cond][0] - G[cond][1], freqs, times, ax=axes[r, 2], vlim=(-25, 25), edge_s=edge,
                baseline=L4.TF_BASELINE, cbar_label="C3 - C4 (percentage points)",
                title=f"{cond}: C3 - C4 lateralisation\n(percentage points)")
fig.suptitle(f"Capstone C4 deliverable 1-2: ERD maps and lateralisation, {len(per_subject)} ds-eegbci subjects",
             y=1.01)
fig.tight_layout()
plt.show()   # render the static figure(s) of this cell inline

peaks = []
for sid, rec in per_subject.items():
    sf_s = rec["sfreq"]
    segs = rec["baseline_segments"]
    f_w, P_w = sps.welch(segs, fs=sf_s, nperseg=int(min(2 * sf_s, segs.shape[-1])),
                         noverlap=int(min(sf_s, segs.shape[-1] // 2)), window="hann", axis=-1)
    m = (f_w >= 1.0) & (f_w <= 40.0)
    row = {"subject": sid}
    for k, ch in enumerate(CHANNELS):
        psd = P_w[k::len(CHANNELS)].mean(0)
        fit = helpers_l1.fit_specparam(f_w[m], psd[m])
        row[f"{ch} peak (Hz)"] = fit["iaf"]
        row[f"{ch} exponent"] = fit["exponent"]
        row[f"{ch} r^2"] = fit["r_squared"]
    row["has a mu peak"] = bool(np.isfinite(row["C3 peak (Hz)"]) or np.isfinite(row["C4 peak (Hz)"]))
    peaks.append(row)
print(f"specparam on the pre-cue window ({L4.MI_TMIN:g}..0 s of every epoch, both conditions pooled), "
      f"fit range {helpers_l1.FIT_RANGE[0]:g}-{helpers_l1.FIT_RANGE[1]:g} Hz, peak search "
      f"{helpers_l1.IAF_RANGE[0]:g}-{helpers_l1.IAF_RANGE[1]:g} Hz:")
print(L4.fmt_table(peaks, floatfmt="{:.3f}"))
NO_PEAK = [r["subject"] for r in peaks if not r["has a mu peak"]]
print()
print(f"Subjects with NO fitted mu peak at either C3 or C4: "
      + (", ".join(NO_PEAK) if NO_PEAK else "none of them")
      + f"  ({len(NO_PEAK)} of {len(peaks)})")
print("For those subjects the 8-13 Hz band power is a measurement of the aperiodic background. The ERD "
      "number is still meaningful as a change in band power; calling it 'mu desynchronisation' is the part "
      "that is not supported.")

fig, axes = plt.subplots(1, 2, figsize=(13.5, 4.2))
for ax, ch in zip(axes, CHANNELS):
    v = np.array([r[f"{ch} peak (Hz)"] for r in peaks])
    e = np.array([r[f"{ch} exponent"] for r in peaks])
    ok = np.isfinite(v)
    ax.scatter(v[ok], e[ok], s=40, label=f"{int(ok.sum())} with a peak")
    for i, r in enumerate(peaks):
        if ok[i]:
            ax.annotate(r["subject"][-3:], (v[i], e[i]), fontsize=7, xytext=(3, 3),
                        textcoords="offset points")
    if (~ok).any():
        ax.scatter(np.full((~ok).sum(), helpers_l1.IAF_RANGE[0] - 0.4), e[~ok], marker="x", color="tab:red",
                   s=50, label=f"{int((~ok).sum())} with NO peak (plotted at the left edge)")
    ax.set(xlabel="Fitted alpha/mu peak frequency (Hz)", ylabel="Aperiodic exponent (dimensionless)",
           title=f"{ch}, pre-cue baseline: peak frequency against aperiodic exponent\n"
                 f"{len(peaks)} subjects (Hz and dimensionless)")
    ax.legend(fontsize=8)
    ax.grid(alpha=0.3)
fig.tight_layout()
plt.show()   # render the static figure(s) of this cell inline

X_diff = np.stack([(lat[s]["T1"] - lat[s]["T2"])[:, safe] for s in per_subject])
n_sub = X_diff.shape[0]
N_PERM = min(2 ** n_sub, 10000)
adjacency = mne.stats.combine_adjacency(len(freqs), int(safe.sum()))
thr = sstats.t.ppf(1 - 0.05 / 2, n_sub - 1)
with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    T, clusters, cluster_p, H0 = mne.stats.permutation_cluster_1samp_test(
        X_diff, threshold=thr, n_permutations=N_PERM, tail=0, adjacency=adjacency, out_type="mask",
        seed=20260918, verbose=False)
print(f"Cluster-permutation test: {n_sub} subjects, {len(freqs)} x {int(safe.sum())} cells, "
      f"cluster-forming |t| > {thr:.3f} (two-tailed p < .05), {N_PERM} permutations "
      f"({'exact -- all 2^n sign flips' if N_PERM == 2 ** n_sub else 'sampled'})")
print(f"  {len(clusters)} candidate clusters; {sum(p < 0.05 for p in cluster_p)} at p < .05")
for i, p in enumerate(cluster_p):
    if p < 0.10:
        f_i, t_i = np.where(clusters[i])
        print(f"    cluster {i}: p = {p:.4f}, {int(clusters[i].sum())} cells, "
              f"{freqs[f_i.min()]:.0f}-{freqs[f_i.max()]:.0f} Hz, "
              f"{times[safe][t_i.min()]:+.2f}..{times[safe][t_i.max()]:+.2f} s, sum t = {T[clusters[i]].sum():+.1f}")
if not len(cluster_p):
    print("    no cell passed the cluster-forming threshold, so there is nothing to test")

fm = (freqs >= L4.MU_BAND[0]) & (freqs <= L4.MU_BAND[1])
tm = (times[safe] >= L4.TF_ACTIVE[0]) & (times[safe] <= L4.TF_ACTIVE[1])
roi = X_diff[:, fm][:, :, tm].mean(axis=(1, 2))
t_roi, p_roi = sstats.ttest_1samp(roi, 0)
print()
print(f"A-priori ROI (mu {L4.MU_BAND[0]:g}-{L4.MU_BAND[1]:g} Hz, {L4.TF_ACTIVE[0]:g}..{L4.TF_ACTIVE[1]:g} s), "
      f"one test, no correction needed:")
print(f"  mean {roi.mean():+.3f} percentage points, SD {roi.std(ddof=1):.3f}, "
      f"t({n_sub - 1}) = {t_roi:+.3f}, p = {p_roi:.4f}, dz = {roi.mean() / roi.std(ddof=1):+.3f}; "
      f"{int((roi > 0).sum())} of {n_sub} subjects with the expected sign")

fig, axes = plt.subplots(1, 2, figsize=(14.5, 4.2))
L4.plot_tf_clusters(T, clusters, cluster_p, freqs, times[safe], ax=axes[0],
                    title=f"Left minus right imagery, (C3 - C4) lateralisation\n{n_sub} subjects, "
                          f"significant clusters outlined (t)")
axes[1].hist(H0, bins=30, color="0.7", label=f"{N_PERM} sign-flip permutations")
if len(cluster_p):
    best = int(np.argmin(cluster_p))
    axes[1].axvline(T[clusters[best]].sum(), color="tab:red", lw=2,
                    label=f"largest observed cluster, sum t = {T[clusters[best]].sum():+.1f}, "
                          f"p = {cluster_p[best]:.4f}")
axes[1].set(xlabel="Largest cluster sum-t under the null (t units)", ylabel="Permutations",
            title="The permutation null distribution (t units)")
axes[1].legend(fontsize=8)
fig.tight_layout()
plt.show()   # render the static figure(s) of this cell inline

try:
    print("nb-c4-mu-beta-erd -- Capstone C4 deliverables (draft; TODO(confirm) at author review)")
    print(f"Dataset: ds-eegbci (EEGMMIDB), PhysioNet DOI {L4.DATASETS_L4['ds-eegbci']['dataset_doi']}, "
          f"licence {L4.DATASETS_L4['ds-eegbci']['license']}, access {L4.DATASETS_L4['ds-eegbci']['access']}.")
    print(f"Cohort: FULL_COHORT = {FULL_COHORT} -> {len(per_subject)} of {len(SUBJECTS)} subjects processed "
          f"({len(failures)} failure(s)); runs {'+'.join(f'R{r:02d}' for r in L4.MI_RUNS)}.")
    print(f"Excluded with the reason recorded: {', '.join(helpers.EEGBCI_EXCLUDE_DEFAULT)} "
          f"(inconsistent event timestamps, data/directory.yaml) and "
          f"{', '.join(helpers.EEGBCI_EXCLUDE_OPTIONAL)} (also often dropped).")
    print(f"Wall clock: {COHORT_S:.0f} s for {len(per_subject)} subjects "
          f"({COHORT_S / max(len(per_subject), 1):.1f} s each), downloads deleted per subject.")
    print()
    print("DELIVERABLE 1 -- ERD maps, left vs right hand imagery, per subject (band-first percent change, "
          f"baseline {L4.TF_BASELINE[0]:g}..{L4.TF_BASELINE[1]:g} s, window {L4.TF_ACTIVE[0]:g}.."
          f"{L4.TF_ACTIVE[1]:g} s):")
    for r in rows:
        print(f"    {r['subject']}  T2 mu C3 {r['T2 mu C3 (%)']:+7.1f} % C4 {r['T2 mu C4 (%)']:+7.1f} % | "
              f"T1 mu C3 {r['T1 mu C3 (%)']:+7.1f} % C4 {r['T1 mu C4 (%)']:+7.1f} % | "
              f"T2 beta C3 {r['T2 beta C3 (%)']:+7.1f} % C4 {r['T2 beta C4 (%)']:+7.1f} %")
    mu_c3 = np.array([r["T2 mu C3 (%)"] for r in rows])
    mu_c4 = np.array([r["T2 mu C4 (%)"] for r in rows])
    print(f"    cohort median, right-hand imagery: C3 {np.median(mu_c3):+.1f} % "
          f"(range {mu_c3.min():+.1f} to {mu_c3.max():+.1f}), C4 {np.median(mu_c4):+.1f} % "
          f"(range {mu_c4.min():+.1f} to {mu_c4.max():+.1f})")
    print(f"    NOTE: nb-4-4-erd quotes S001 alone at C3 -47.9 % / C4 -10.5 %. S001 was CHOSEN for the size "
          f"of its effect, and the cohort median above is where a typical subject sits. Quoting the one "
          f"without the other is the selection effect Level 6 is about.")
    print()
    print(f"DELIVERABLE 2 -- contralateral lateralisation: {n_t2} of {len(rows)} subjects show it for "
          f"right-hand imagery (binomial p = {sstats.binomtest(n_t2, len(rows), 0.5).pvalue:.4f}) and "
          f"{n_t1} of {len(rows)} for left-hand imagery "
          f"(p = {sstats.binomtest(n_t1, len(rows), 0.5).pvalue:.4f}).")
    print()
    print("DELIVERABLE 3 -- cluster test on the difference:")
    print(f"    {len(clusters)} candidate clusters, {sum(p < 0.05 for p in cluster_p)} at p < .05, "
          f"{N_PERM} permutations (exact for {n_sub} subjects), cluster-forming |t| > {thr:.3f}.")
    for i, p in enumerate(cluster_p):
        if p < 0.10:
            f_i, t_i = np.where(clusters[i])
            print(f"        cluster {i}: p = {p:.4f}, {int(clusters[i].sum())} cells, "
                  f"{freqs[f_i.min()]:.0f}-{freqs[f_i.max()]:.0f} Hz, "
                  f"{times[safe][t_i.min()]:+.2f}..{times[safe][t_i.max()]:+.2f} s")
    print(f"    A-priori ROI (one test, chosen before the data): t({n_sub - 1}) = {t_roi:+.3f}, "
          f"p = {p_roi:.4f}, mean {roi.mean():+.3f} percentage points, dz {roi.mean() / roi.std(ddof=1):+.3f}.")
    print(f"    INTERPRETATION: a significant cluster rejects the null of no difference ANYWHERE in the "
          f"tested window. It does not locate the effect in time or frequency, and the cluster's extent "
          f"would move with the cluster-forming threshold (nb-4-7-tf-cluster shows by how much).")
    print()
    print("DELIVERABLE 4 -- who has a mu peak:")
    for r in peaks:
        c3 = f"{r['C3 peak (Hz)']:.2f}" if np.isfinite(r["C3 peak (Hz)"]) else "  none"
        c4 = f"{r['C4 peak (Hz)']:.2f}" if np.isfinite(r["C4 peak (Hz)"]) else "  none"
        print(f"    {r['subject']}  C3 peak {c3:>6s} Hz (exponent {r['C3 exponent']:.2f}, r^2 "
              f"{r['C3 r^2']:.3f}) | C4 peak {c4:>6s} Hz (exponent {r['C4 exponent']:.2f}, r^2 "
              f"{r['C4 r^2']:.3f})" + ("   <-- NO MU PEAK AT EITHER SITE" if not r["has a mu peak"] else ""))
    print(f"    {len(NO_PEAK)} of {len(peaks)} subjects have no fitted peak in "
          f"{helpers_l1.IAF_RANGE[0]:g}-{helpers_l1.IAF_RANGE[1]:g} Hz at either site"
          + (f": {', '.join(NO_PEAK)}" if NO_PEAK else "."))
    print()
    RUBRIC = [
        ("Baseline choice justified and edge-safe",
         f"{L4.TF_BASELINE[0]:g}..{L4.TF_BASELINE[1]:g} s, fixed in helpers_l4.TF_BASELINE before the data; "
         f"the edge region ends at {times[0] + edge.max():+.3f} s, so the baseline starts "
         f"{L4.TF_BASELINE[0] - (times[0] + edge.max()):.3f} s clear of it and ends 0.5 s before the cue. "
         f"Every map shades the edge region."),
        ("Normalisation stated",
         "percent change from the baseline mean, per frequency, in the BAND-FIRST order (raw power averaged "
         "over trials, then over the band, then normalised). nb-4-4-erd shows the three other orders give "
         "different answers, so the order is part of the method and is stated wherever a number is."),
        ("Cluster interpretation correct",
         f"the test rejects the null of no difference anywhere in "
         f"{freqs[0]:.0f}-{freqs[-1]:.0f} Hz x {times[safe][0]:+.2f}..{times[safe][-1]:+.2f} s; no claim is "
         f"made about the effect's onset, offset or frequency, and the a-priori ROI is reported beside it as "
         f"the statement that can be made about a named band and window."),
        ("Subjects without a mu peak handled explicitly",
         f"specparam is fitted on each subject's PRE-CUE data at C3 and C4; "
         f"{len(NO_PEAK)} of {len(peaks)} subjects have no peak in "
         f"{helpers_l1.IAF_RANGE[0]:g}-{helpers_l1.IAF_RANGE[1]:g} Hz"
         + (f" ({', '.join(NO_PEAK)})" if NO_PEAK else "")
         + ". They are reported, not dropped; their band-power change is still a change in band power, but "
           "it is not evidence about a rhythm."),
        ("Documented defective subjects excluded with the reason recorded",
         f"{', '.join(helpers.EEGBCI_EXCLUDE_DEFAULT)} always and "
         f"{', '.join(helpers.EEGBCI_EXCLUDE_OPTIONAL)} by default, refused by helpers.load_spine with the "
         f"data/directory.yaml caveat as the reason; none is in this subset."),
        ("Runs on a documented subset within the section 11 limit, with a FULL_COHORT switch",
         f"FULL_COHORT = {FULL_COHORT}; {len(per_subject)} subjects in {COHORT_S:.0f} s here. "
         f"FULL_COHORT = True is about 103 subjects and ~740 MB and has NOT been executed."),
    ]
    print("RUBRIC:")
    for item, state in RUBRIC:
        print(f"  [x] {item}\n      {state}")
    if failures:
        print()
        print("Failures recorded rather than raised:")
        for f_ in failures:
            print(f"    {f_['subject']}: {f_['reason']}")
    print()
    print("Pitfalls: pf-tf-edge-effects, pf-band-power-slope, pf-cluster-inference-misread, "
          "pf-uncorrected-timepoint-tests. Widgets: w-tf-baseline-explorer, w-burst-detector, "
          "w-cluster-permutation-viz (mode tf), w-aperiodic-explorer.")
    print("TODO(confirm): the catalog carries no published ERD value or lateralisation effect size for this "
          "dataset, so nothing above is compared with a literature number; and this dataset's reference is "
          "recorded as TODO(confirm) in data/directory.yaml, so the average reference used here is a choice "
          "of this course, stated rather than inherited.")
finally:
    dl.finish()