"""Build the final report (README.md and EEG-sAAD_full_corpus_EDA_report.pdf) from the result tables.
Every number is read from tables/*.csv produced by the pipeline; nothing is typed in by hand."""
import os
import sys

import numpy as np
import pandas as pd

sys.path.insert(0, os.path.dirname(__file__))
from common import DS_KEYS, LABELS, OUT, TAB  # noqa: E402
from f2_howto import CONVENTIONS, FIG_HOWTO, GLOSSARY, TAB_HOWTO  # noqa: E402
import re  # noqa: E402

MAIN = "c19-common57-car"


def T(n):
    return pd.read_csv(os.path.join(TAB, n))


def f(x, nd=3):
    if isinstance(x, (float, np.floating)):
        if not np.isfinite(x):
            return "n/a" if np.isnan(x) else ("Inf" if x > 0 else "-Inf")
        return f"{x:.{nd}g}"
    return str(x)


def pct(x, nd=1):
    return f"{100 * x:.{nd}f}%"


def ci(m, lo, hi, scale=100, nd=1):
    return f"{m * scale:.{nd}f} [{lo * scale:.{nd}f}, {hi * scale:.{nd}f}]"


# ---------------------------------------------------------------------------
# content model: list of (kind, payload)
B = []


def H1(t): B.append(("h1", t))
def H2(t): B.append(("h2", t))
def P(t): B.append(("p", t))
def UL(items): B.append(("ul", items))
def TAB_(df, caption, widths=None): B.append(("table", (df, caption, widths)))
def FIG(name, caption): B.append(("fig", (name, caption)))
def BREAK(): B.append(("break", None))


# ---------------------------------------------------------------------------
inv = T("corpus_inventory.csv")
qc = T("qc_dataset_summary.csv").set_index("ds")
pre = T("prefilter_inference.csv").set_index("ds")
lab = T("label_audit_summary.csv").set_index("ds")
asym = T("env_asymmetry_summary.csv").set_index("ds")
loud = T("env_loud_column_classifier.csv")
par = T("design_parity.csv").set_index("ds")
drift = T("drift_classifier_summary.csv")
ident = T("stim_identity_summary.csv").set_index("ds")
envc = T("env_character.csv").set_index("ds")
xh = T("crosshalf_h6.csv")
h9 = T("stream_order_audit.csv")
h9s = T("stream_order_audit_subjects.csv")
xc = T("xcorr_summary.csv").set_index("ds")
accw = T("decoder_accuracy_vs_window.csv")
snr = T("decoder_snr_law.csv")
pc = T("decoder_pipeline_comparison.csv")
fp = T("fingerprint_results.csv")
sp = T("spatial_summary.csv")
sp["window_s"] = sp.window_s.astype(str)
phys = T("physiology_direction_effects.csv")
physw = T("physiology_avgc_switch_locked.csv")
physc = T("physiology_avgc_by_condition.csv")
sc_tests = T("scorer_equivalence_tests.csv")
la_test = T("lookahead_test.csv")
budget = T("switch_lookahead_budget_0-500ms.csv")
sw5 = T(f"switch_results_{MAIN}_lodo_pool_0-500ms.csv")
sw2 = T(f"switch_results_{MAIN}_lodo_pool_0-250ms.csv")
rank5 = T(f"switch_ranking_{MAIN}_lodo_pool_0-500ms.csv")
ssw = T("spatial_switch_results.csv")
verd = T("hypotheses_verdicts.csv")

best = rank5.integrator.iloc[0]
real5 = sw5[(~sw5.null) & (sw5.switches == "syn") & (sw5.integrator != "ORACLE")]
null5 = sw5[sw5.null & (sw5.switches == "syn")]
orc = sw5[sw5.integrator == "ORACLE"].set_index("test_ds")
bt = real5[real5.integrator == best].set_index("test_ds")
bn = null5[null5.integrator == best].set_index("test_ds")
lodo = accw[(accw.scheme == "lodo_pool") & (accw.lag == "0-500ms")].set_index(["ds", "w"])
loto = accw[(accw.scheme == "loto") & (accw.lag == "0-500ms")].set_index(["ds", "w"])
snr5 = snr[snr.lag == "0-500ms"].set_index(["scheme", "ds"])
fpd = fp[(fp.task == "dataset") & fp.features.str.startswith("cov")].set_index("alignment")
xb60 = xh[(xh.w == 60) & xh.hypothesis.str.startswith("hypB")].iloc[0]
xa60 = xh[(xh.w == 60) & xh.hypothesis.str.startswith("hypA")].iloc[0]
lk = loud[loud.scheme == "LOSO"].set_index("ds")
q5 = sp[sp.window_s == "5"].pivot_table(index=["model", "ds"], columns="scheme", values="median_acc")
gap5 = q5["within_trial"] - q5["LOTO"]
tid5 = sp[(sp.scheme == "trialID_within") & (sp.window_s == "5")].set_index("ds")
dirv = sw5[(sw5.switches == "dir") & (~sw5.null)].sort_values("H", ascending=False).iloc[0]
sbest = ssw[~ssw.null].sort_values("H", ascending=False).iloc[0]
snull = ssw[ssw.null].L.median()
legal = la_test[la_test.legal]
n_or_miss = int(orc.nUndetected.sum())
n_or = int(orc.nSwitches.sum())
avgc_mixed = int(ident.loc["AVGC", "clusters_with_several_names"])
line_ratio_example = {"UHD": 10.8, "USTC": 9.3}                      # previous EDA (example trial), from the brief
weaker = [line_ratio_example[d] / qc.loc[d, "line_ratio_50"] for d in ("UHD", "USTC")]
fam_all = real5.assign(fam=real5.integrator.str.extract(r"^(argmax|ma|hmmz|hmm|ladder)")[0]).groupby(["fam", "test_ds"]).H.max().unstack()
integ_gain = fam_all.max() - fam_all.loc["argmax"]
snr_ratio = snr5.xs("loto").snr1_median / snr5.xs("lodo_pool").snr1_median
pcsel = pc[(pc.scheme == "lodo_pool") & (pc.ds == "ALL")].set_index(["cfg", "lag", "w"])
cw10 = pcsel.loc[("cwide-common57-car", "0-500ms", 10)]
cw1 = pcsel.loc[("cwide-common57-car", "0-500ms", 1)]
dl_max = drift.median_acc.max()
supav = pc[(pc.scheme == "lodo_pool") & (pc.cfg == "sup-common57-car") & (pc.lag == "0-500ms") & (pc.w == 1) & (pc.ds == "AVGC")].iloc[0]

# ===========================================================================
H1("Full-corpus signal-processing EDA: ICASSP 2027 EEG-sAAD Grand Challenge training data")
P(f"Scope: every trial of the five local training datasets ({int(inv.trials.sum())} trials, {int(inv.subjects.sum())} subjects, "
  f"{inv.hours.sum():.1f} h of EEG at 128 Hz). A previous EDA based on one example trial per dataset proposed hypotheses "
  "H1-H12; this report confirms or refutes each at corpus scale with subject-level statistics (medians with 95% bootstrap "
  "CIs over subjects, 2,000 resamples; Wilcoxon signed-rank tests across subjects; FDR where many tests are made). "
  "Every number was computed by the scripts in reports/eda_full/scripts and is traceable to a CSV in reports/eda_full/tables.")

H2("1. Executive summary")
UL([
    f"Labels (H6 confirmed): the corpus contains no within-trial speaker switch. The only genuine switches are {int(lab.loc['AVGC','direction_switches'])} "
    f"direction switches in KUL-AV-GC, all at exactly t = 300 s, where the attended speaker stays the same and moves side. The trial-level "
    f"label is wrong for {pct(lab.loc['AVGC','frac_direction_samples_label_wrong'],0)} of KUL-AV-GC direction samples. A cross-half decoder test agrees: "
    f"{ci(xb60.median_acc, xb60.ci_lo, xb60.ci_hi)}% at 60 s if the speaker is constant, vs {ci(xa60.median_acc, xa60.ci_lo, xa60.ci_hi)}% if it switched.",
    f"Recording 'dialects' (H1, H3 confirmed): median channel SD spans {f(qc.median_sd.max() / qc.median_sd.min(), 3)}x across datasets; "
    f"DTU, KUL-UHD and USTC are not high-passed (RMS/SD {f(qc.loc['DTU','median_rms_sd'])}, {f(qc.loc['UHD','median_rms_sd'])}, "
    f"{f(qc.loc['USTC','median_rms_sd'])}) and have edge transients in {pct(qc.loc['UHD','share_edge_transient_trials'],0)} (KUL-UHD) and "
    f"{pct(qc.loc['USTC','share_edge_transient_trials'],0)} (USTC) of trials. KUL-AV-GC is band-limited to about 1-41 Hz and notched at 50 Hz.",
    f"Neural tracking is present in every dataset. The envelope-EEG correlation peaks at {f(xc.peak_lag_ms.min())}-{f(xc.peak_lag_ms.max())} ms, "
    f"and the attended envelope is tracked more strongly than the ignored one in all five datasets (Wilcoxon p <= {f(xc.wilcoxon_att_vs_ign_p.max(), 2)}).",
    f"SNR law (H4 confirmed): accuracy follows Phi(k*SNR1*sqrt(w)) with k = {f(snr5.k.min(), 2)}-{f(snr5.k.max(), 2)}. KUL-AV-GC 1-s SNR1 is "
    f"{f(snr5.loc[('loto','AVGC'),'snr1_median'])} within-subject and {f(snr5.loc[('lodo_pool','AVGC'),'snr1_median'])} "
    "leave-one-dataset-out (LODO), close to the 0.099 implied by the official baseline's 53.94% at 1 s.",
    f"Cross-dataset (LODO) accuracy at 1 s is {pct(lodo.xs(1, level='w').median_acc.min())}-{pct(lodo.xs(1, level='w').median_acc.max())}, and at 10 s it is "
    f"{pct(lodo.xs(10, level='w').median_acc.min())}-{pct(lodo.xs(10, level='w').median_acc.max())}. USTC (NeuroScan, Mandarin) is the hardest held-out dataset.",
    "Pipeline (H5 confirmed): causal filtering is never worse than zero-phase filtering or the supplied 32 Hz data under LODO, "
    "and common-average referencing helps. Montage size (57/58/62 channels) and lag range (0-250 vs 0-500 ms) make no reliable difference.",
    f"Shortcuts: the label is locked to trial-ID parity in KUL-UHD and USTC (H8, 100%). In KUL2016 an envelope-statistics classifier "
    f"picks the attended column at {pct(lk.loc['KUL','median_acc'])} under LOSO (H7). The covariance identifies the dataset at "
    f"{pct(fpd.loc['none','acc'])} (H10), and alignment only reduces this to {pct(fpd.loc['ea','acc'])} (EA) or "
    f"{pct(fpd.loc['running_ea','acc'])} (causal running EA).",
    f"Spatial decoders learn trial fingerprints (H11 confirmed). With 5-s windows, the trial ID is predicted at "
    f"{pct(tid5.median_acc.min(),0)}-{pct(tid5.median_acc.max(),0)}. Going from a within-trial split to held-out trials costs "
    f"a median {f(gap5.median()*100)} pp, and LODO accuracy is at chance ({pct(q5['LODO'].min())}-{pct(q5['LODO'].max())}).",
    f"USTC columns are not swapped (H9 refuted): column 1 wins only {pct(h9.set_index(['scheme','ds']).loc[('loso','USTC'),'share_col1_wins'])} "
    "of USTC trials under LOSO, and no subject shows a significant column-1 majority.",
    f"Stimulus reuse: all KUL-UHD audio also occurs in KUL2016. In KUL-AV-GC the streamWav names do not match the audio: "
    f"{avgc_mixed}/30 envelope-identity clusters carry several names. Build story-disjoint folds from envelope identity, not names.",
    f"Switch detection (Phase E, SYNTHETIC switches, LODO evidence): the best integrator on the median held-out dataset is {best}, with "
    f"H = {f(bt.H.min())}-{f(bt.H.max())} against a sign-randomised null of {f(bn.H.min())}-{f(bn.H.max())}. On the 99 genuine KUL-AV-GC direction "
    f"switches, spatial LODO evidence gives Acc = {f(sbest.Acc,3)}% and L = {f(sbest.L)} (null L {f(snull)}): direction is essentially not decodable across datasets.",
    f"Scorer: MATLAB is not installed, so the official scorer was ported to Python and verified ({int(sc_tests.passed.sum())}/{len(sc_tests)} "
    f"tests plus 3,000 random cases against a brute-force reference). The port exposed a property of the metric: a perfect decoder scores SDT = Inf "
    f"on a switch that is followed within 50 s by a switch back ({n_or_miss}/{n_or} synthetic switches). The full causal pipeline passes the "
    f"lookahead perturbation test ({int(legal.passed.sum())}/{len(legal)}).",
])


# ---------------------------------------------------------------------------
H2("2. How to read this report")
P(CONVENTIONS)
P("Every figure and table is followed by a shaded 'How to read this' note explaining its axes, colours and what to look for. "
  "Terms used throughout:")
TAB_(pd.DataFrame(GLOSSARY, columns=["term", "meaning"]), "Glossary.", widths=[0.2, 0.8])

# ---------------------------------------------------------------------------
BREAK()
H2("3. Most interesting findings")
P("These are the results that most change how the data should be used. Each one says what was found, how strong the evidence "
  "is, and why it matters for building and evaluating a decoder.")
usv = h9.set_index(["scheme", "ds"])
FINDINGS = [
    ("The official scorer can mark a perfect decoder as having missed a switch.",
     f"When a switch is followed within 50 s by a switch back, the scorer's split search prefers 'old label until the end of the "
     f"100-s window'. That split fails the 0.5-s sustain check, the search moves past it, and the first switch is scored undetected "
     f"(SDT = Inf, score 0) even when every predicted label is correct. Under the default synthetic schedule (gaps drawn from "
     f"30-90 s) this happens to {n_or_miss} of {n_or} switches ({pct(n_or_miss / n_or)}) for a perfect decoder.",
     "L is a median over switches, so this loss is invisible in the headline L of the perfect decoder (1.00) but not for real "
     "decoders. Synthetic switch spacing must match the real test protocol before integrators are tuned, and results on "
     "closely spaced switches are pessimistic by construction."),
    ("There is no speaker switch anywhere in the training data; the KUL-AV-GC 'switch' is a change of side.",
     f"In all {int(lab.loc['AVGC','trials'])} KUL-AV-GC trials the attended talker stays the same and moves from one side to the "
     f"other at exactly t = 300 s. A decoder trained on one half and tested on the other scores {pct(xb60.median_acc)} at 60 s "
     f"if the talker is constant and {pct(xa60.median_acc)} if it had switched. The trial-level label is wrong for "
     f"{pct(lab.loc['AVGC','frac_direction_samples_label_wrong'],0)} of direction samples.",
     "Speaker-switch detection can only be trained and evaluated with SYNTHETIC switches. A stimulus-reconstruction decoder "
     "cannot see these genuine switches at all, and direction labels must be taken per sample, never from the trial label."),
    ("Stimulus names are unreliable, and two datasets share the same audio.",
     f"Clustering all 3,958 envelopes by content shows that in KUL-AV-GC {avgc_mixed} of 30 distinct audios carry more than one "
     "streamWav name across subjects, so the same name does not mean the same audio. All 240 KUL-UHD envelopes also occur in "
     "KUL2016, and KUL2016 itself has only 8 distinct audios.",
     "Folds that separate stories by name leak stimuli between training and test data. Group folds by envelope identity, and keep "
     "KUL2016 and KUL-UHD on the same side of any split."),
    ("Spatial decoders learn which trial a window came from, not where the listener attends.",
     f"With 5-s windows the same features predict the trial ID at {pct(tid5.median_acc.min(),0)}-{pct(tid5.median_acc.max(),0)} "
     f"(chance 2-25%). Accuracy drops by a median {f(gap5.median()*100)} pp (up to {f(gap5.max()*100)} pp) when whole trials are "
     f"held out, and across datasets it is at chance ({pct(q5['LODO'].min())}-{pct(q5['LODO'].max())}). In USTC and KUL-UHD it "
     "even falls clearly BELOW chance, because labels alternate trial by trial, so the neighbouring trials that look most similar "
     "carry the opposite label.",
     f"Any spatial or direction decoder evaluated on random windows is inflated. On the 99 genuine KUL-AV-GC switches the best "
     f"spatial decoder reaches only {f(sbest.Acc,3)}% sample accuracy."),
    ("Shortcuts are built into the design of three datasets.",
     f"The trial label equals trial-number parity in 100% of KUL-UHD and USTC trials. In KUL2016 the attended envelope is simply "
     f"louder in {pct(asym.loc['KUL','share_col0_larger_sd'],0)} of trials, and a classifier that sees only envelope statistics picks "
     f"the attended stream at {pct(lk.loc['KUL','median_acc'])} for unseen subjects, without looking at the EEG.",
     "A model can score well on these datasets without decoding attention. Envelope inputs should be scale-symmetric, and no "
     "feature may carry trial order or slow drift."),
    ("Cross-dataset decoding works, but at about half the within-subject signal-to-noise ratio.",
     f"Every dataset shows neural tracking, with the attended talker tracked more strongly than the ignored one (peak "
     f"{f(xc.peak_lag_ms.min())}-{f(xc.peak_lag_ms.max())} ms). The 1-s evidence SNR is {f(snr_ratio.min(),2)}-{f(snr_ratio.max(),2)}x "
     f"higher within subject than across datasets. Accuracy follows Phi(k * SNR1 * sqrt(window)) with k = "
     f"{f(snr5.k.min(),2)}-{f(snr5.k.max(),2)}, and USTC (Mandarin, NeuroScan) is the hardest held-out dataset "
     f"({pct(lodo.loc[('USTC',1),'median_acc'])} at 1 s).",
     "Improving SNR1 (better decoders, better alignment) is worth more than tuning the integrator, which changes H by only "
     f"{f(integ_gain.min(),2)}-{f(integ_gain.max(),2)} over plain argmax."),
    ("One suspected problem turned out not to exist.",
     f"The example-trial EDA suggested the USTC stream columns were swapped. At full scale, column 1 wins only "
     f"{pct(usv.loc[('loso','USTC'),'share_col1_wins'])} of USTC trials and no subject shows a significant column-1 majority. "
     "USTC is simply the weakest dataset, not a mislabelled one.",
     "USTC labels can be used as they are. Its difficulty (envelopes with a different extraction, no high-pass, edge "
     "transients in every trial) is a front-end problem, not a labelling problem."),
]
for i, (title, found, why) in enumerate(FINDINGS, 1):
    B.append(("finding", (f"Finding {i}. {title}", found, why)))

# ---------------------------------------------------------------------------
BREAK()
H2("4. Corpus inventory")
inv2 = pd.DataFrame({
    "dataset": [LABELS[d] for d in inv.ds], "subjects": inv.subjects, "trials": inv.trials, "hours": inv.hours.round(1),
    "trial length s (median, range)": [f"{r.dur_med:.0f} ({r.dur_min:.0f}-{r.dur_max:.0f})" for r in inv.itertuples()],
    "stored channels": inv.channels, "distinct audio (envelope clusters)": [int(ident.loc[d, "n_identity_clusters"]) for d in inv.ds],
    "EOG channels": ["yes" if e > 0 else "no" for e in inv.eog_avail], "conditions": inv.conditions.fillna("-")})
TAB_(inv2, "Table 1. Corpus inventory (SuperHuge raw stage, 128 Hz; mapping to the CND sources verified sample by sample: EEG max "
     "abs. difference 0, envelope r = 1.000 for every trial).")
P("Montages (matched by upper-cased channel name): common intersection of all five datasets = 57 channels (BioSemi-64 minus AF7, AF8, "
  "P9, P10, Iz, AFz, FCz); BioSemi-64 ∩ USTC = 58 (missing AF7, AF8, P9, P10, Iz, AFz; identical to the official baseline's list); "
  "BioSemi-64 mapped onto KUL-UHD = 62 (KUL-UHD lacks AFz and FCz). The BioSemi datasets spell AFz as 'Afz', USTC uses upper case "
  "throughout (FP1, FPZ, ...), so index-based pooling would be wrong.")

# ---------------------------------------------------------------------------
H2("5. Phase A: signal quality and recording 'dialects'")
t = pd.DataFrame({
    "dataset": [LABELS[d] for d in DS_KEYS],
    "median ch. SD [95% CI]": [f"{f(qc.loc[d,'median_sd'])} {qc.loc[d,'median_sd_ci']}" for d in DS_KEYS],
    "RMS/SD": [f(qc.loc[d, "median_rms_sd"]) for d in DS_KEYS],
    "|DC|": [f(qc.loc[d, "median_abs_dc"]) for d in DS_KEYS],
    "1/f slope": [f(qc.loc[d, "aperiodic_slope"]) for d in DS_KEYS],
    "alpha peak Hz": [f(qc.loc[d, "alpha_peak_hz"]) for d in DS_KEYS],
    "50 Hz ratio": [f(qc.loc[d, "line_ratio_50"]) for d in DS_KEYS],
    "sub-1 Hz ratio": [f(qc.loc[d, "sub1_ratio"]) for d in DS_KEYS],
    "edge-transient trials": [pct(qc.loc[d, "share_edge_transient_trials"]) for d in DS_KEYS],
    "bad channels": [pct(qc.loc[d, "share_bad_channels"], 2) for d in DS_KEYS],
    "bad trials": [pct(qc.loc[d, "share_bad_trials"]) for d in DS_KEYS]})
TAB_(t, "Table 2. Phase A, per dataset (subject-level medians; 149,336 channel-trials from 1,979 trials). Bad channel: robust SD "
     "> 5x the dataset median; bad trial: >= 10% bad or flat channels; edge transient: first-difference jump > 20 robust SD within 0.5 s "
     "of either trial edge in any channel.")
FIG("a1_qc_metric_distributions", "Figure A1. Trial-level QC metrics per dataset (dot = trial, bar = median; log10 where marked). "
    "n trials: KUL-AV-GC 99, DTU 1,080, KUL2016 320, KUL-UHD 120, USTC 360.")
FIG("a2_psd_median_iqr", "Figure A2. Median-channel Welch PSD (4-s Hann, 50% overlap), median over trials with IQR band.")
t = pre.reset_index()[["ds", "inferred_highpass", "inferred_lowpass", "inferred_notch", "inferred_reference"]]
t["ds"] = t.ds.map(LABELS)
TAB_(t, "Table 3. Inferred pre-filtering history (from RMS/SD, sub-1 Hz power ratio, aperiodic-fit roll-off and the 50 Hz line ratio; "
     "the reference check uses the SD of the across-channel mean relative to the channel SD).")
P("Interpretation. The stored units differ by an order of magnitude and three datasets carry DC offsets of thousands of units, "
  "so a causal high-pass with state initialisation and a causal running z-score are required before any pooling. KUL-AV-GC has "
  "almost no power below 1 Hz (sub-1 Hz ratio "
  f"{f(qc.loc['AVGC','sub1_ratio'])}), which makes slow EOG/drift information unavailable in that dataset only. None of the datasets is "
  "stored average-referenced. The 50 Hz line in KUL-UHD and USTC is real but "
  f"{f(min(weaker),2)}-{f(max(weaker),2)}x weaker (median over subjects) than the example-trial values suggested.")
FIG("a3_bad_channel_topography", "Figure A3. Share of trials in which each channel is flagged bad (KUL-UHD shown on its 253-channel layout).")
FIG("a4_edge_transients", "Figure A4. Share of trials with an edge transient, split by trial start and end.")

# ---------------------------------------------------------------------------
BREAK()
H2("6. Phase B: labels, streams and design confounds")
t = lab.reset_index()[["ds", "trials", "speaker_switches", "direction_switches", "frac_direction_samples_label_wrong", "col0_is_cnd_stream1"]].copy()
t["ds"] = t.ds.map(LABELS)
t["frac_direction_samples_label_wrong"] = t.frac_direction_samples_label_wrong.map(lambda v: pct(v, 0))
t["col0_is_cnd_stream1"] = t.col0_is_cnd_stream1.map(lambda v: pct(v, 0))
t.columns = ["dataset", "trials", "within-trial speaker switches", "within-trial direction switches",
             "direction samples mislabelled by trial label", "column 0 = CND stream 1"]
TAB_(t, "Table 4. Ground-truth audit from the CND per-sample attendedStream / attendedAzimuth fields (per-trial detail in "
     "tables/label_audit.csv). SuperHuge column 0 equals the majority-attended stream in every trial (r = 1.000).")
xs = xh[xh.w.isin([1, 10, 60])].copy()
xs["acc"] = [ci(r.median_acc, r.ci_lo, r.ci_hi) for r in xs.itertuples()]
xs = xs.pivot(index="w", columns="hypothesis", values="acc").reset_index()
xs.columns = ["window s", "A: speaker switches at 5 min", "B: same speaker all trial"]
TAB_(xs, "Table 5. H6 cross-half test on all 99 KUL-AV-GC trials (13 subjects): backward decoder (0-500 ms, ridge) trained on one "
     "half and tested on the other; median subject accuracy % [95% CI] under each hypothesis.")
P("The KUL-AV-GC 5-min event is a change of attended direction with the same attended talker (the two talkers swap sides). For a "
  "stimulus-reconstruction decoder there is no switch at all; for a spatial decoder the correct per-sample label flips at 300 s and "
  "the trial-level label is wrong for the second half of every trial.")
t = asym.reset_index()[["ds", "n_trials", "share_col0_larger_sd", "binom_p", "wilcoxon_subject_p", "n_distinct_ratio_levels"]].copy()
t["loud-column classifier LOSO %"] = [ci(lk.loc[d, "median_acc"], lk.loc[d, "ci_lo"], lk.loc[d, "ci_hi"]) for d in t.ds]
t["ds"] = t.ds.map(LABELS)
t["share_col0_larger_sd"] = t.share_col0_larger_sd.map(pct)
for c in ("binom_p", "wilcoxon_subject_p"):
    t[c] = t[c].map(lambda v: f(v, 2))
t.columns = ["dataset", "trials", "col0 SD > col1 SD", "binomial p", "subject Wilcoxon p", "distinct SD-ratio levels",
             "loud-column classifier LOSO %"]
TAB_(t, "Table 6. H7 envelope asymmetry and the 'loud column' shortcut (a logistic classifier seeing only envelope statistics of the "
     "two columns in random order).")
FIG("b4_env_sd_ratio", "Figure B1. log2 SD ratio of column 0 (attended) to column 1 per trial.")
dl = drift.pivot_table(index="ds", columns="scheme", values="median_acc")
t = pd.DataFrame({"dataset": [LABELS[d] for d in DS_KEYS],
                  "label vs trial parity agreement": [pct(par.loc[d, "agree_odd_is_left"]) for d in DS_KEYS],
                  "subjects fully parity-locked": [f"{int(par.loc[d,'subjects_fully_parity_locked'])}/{int(par.loc[d,'n_subjects'])}" for d in DS_KEYS],
                  "drift-only classifier, within subject": [pct(dl.loc[d, "LOTO"]) for d in DS_KEYS],
                  "drift-only classifier, LOSO": [pct(dl.loc[d, "LOSO"]) for d in DS_KEYS]})
TAB_(t, "Table 7. H8 design confounds. The drift-only classifier uses per-channel DC, drift slope and sub-1 Hz power (no trial index); "
     "within-subject evaluation is balanced leave-pair-out because plain leave-one-trial-out is biased below 50% with balanced labels.")
t = ident.reset_index()[["ds", "n_envelopes", "n_names", "n_identity_clusters", "clusters_with_several_names", "max_subjects_one_audio"]].copy()
t["ds"] = t.ds.map(LABELS)
t.columns = ["dataset", "envelopes", "streamWav names", "distinct audio (r > 0.99)", "audio clusters with several names", "max subjects per audio"]
TAB_(t, "Table 8. Stimulus reuse from envelope identity (zero-lag correlation of the 8 Hz envelopes, first 40 s). All 240 KUL-UHD "
     "envelopes also occur in KUL2016 (4 shared audio clusters).")
P("Envelope character: no dataset stores per-trial z-scored envelopes; all are signed/mean-removed (about half the samples are negative), "
  "and inter-stream correlation is near zero (median r "
  + ", ".join(f"{LABELS[d]} {f(envc.loc[d,'r_streams_median'],2)}" for d in DS_KEYS)
  + "). KUL-AV-GC envelopes are sharply high-passed at about 1 Hz; USTC envelopes show a 4-5 Hz (syllable-rate) bump and a platykurtic "
  f"distribution (kurtosis {f(envc.loc['USTC','kurt'],2)}), i.e. a different envelope extraction. Match the envelope front end across "
  "datasets before pooling.")
FIG("b7_env_modspec", "Figure B2. Envelope modulation spectrum (column 0, median over trials).")
u = h9.set_index(["scheme", "ds"])
t = pd.DataFrame({"dataset": [LABELS[d] for d in DS_KEYS],
                  "col1 wins, LOSO": [pct(u.loc[("loso", d), "share_col1_wins"]) for d in DS_KEYS],
                  "col1 wins, LODO": [pct(u.loc[("lodo_pool", d), "share_col1_wins"]) for d in DS_KEYS],
                  "median r col0 / col1 (LOSO)": [f"{f(u.loc[('loso',d),'median_r_col0'],2)} / {f(u.loc[('loso',d),'median_r_col1'],2)}" for d in DS_KEYS]})
TAB_(t, f"Table 9. H9 stream-order audit (whole-trial correlation of a held-out decoder with each column). Subjects with a column-1 "
     f"majority at FDR q < 0.05: {int((h9s.q < 0.05).sum())} of {h9s.subj.nunique()}.")

# ---------------------------------------------------------------------------
BREAK()
H2("7. Phase C: neural tracking, decoders and the SNR law")
P("Causal pipeline used for every decoding result unless stated: 1-s warm-up and trim at both edges; causal Butterworth high-pass 0.5 Hz "
  "(sosfilt, sosfilt_zi initialised); common-average reference over the montage; causal band-pass 1-9 Hz; causal anti-alias 12 Hz and "
  "decimation to 32 Hz; causal running robust z-score (tau 30 s, clip +-5). The same filters are applied to the envelopes. Backward "
  "ridge decoders use EEG lags 0-250 or 0-500 ms after the envelope sample; lambda is chosen by inner cross-validation on training "
  "groups only.")
t = xc.reset_index()[["ds", "n_subjects", "peak_lag_ms", "peak_lag_ms_ci", "peak_rms_att", "rms_ign", "diff", "diff_ci", "wilcoxon_att_vs_ign_p"]].copy()
t["ds"] = t.ds.map(LABELS)
for c in ("peak_rms_att", "rms_ign", "diff"):
    t[c] = t[c].map(lambda v: f(v, 3))
t["wilcoxon_att_vs_ign_p"] = t.wilcoxon_att_vs_ign_p.map(lambda v: f(v, 2))
t.columns = ["dataset", "subjects", "peak lag ms", "peak lag 95% CI", "RMS r attended", "RMS r ignored", "att - ign", "att - ign 95% CI", "Wilcoxon p"]
TAB_(t, "Table 10. Envelope-EEG cross-correlation (RMS over 57 channels, subject means of trials) at the attended peak within 0-500 ms. "
     "A per-trial circular-shift null (100 shifts, 40 trials per dataset) is in tables/xcorr_null_trials.csv.")
FIG("c1_tracking_curves", "Figure C1. Tracking curves (median over subjects, IQR band); solid = attended, dashed = ignored.")
FIG("c1_topographies", "Figure C2. Topographies at the dataset median peak lag (attended, ignored, difference).")
FIG("c1_forward_trf_gfp", "Figure C3. Forward TRF global field power (own ridge implementation; MNE is not installed).")
a = accw[accw.lag == "0-500ms"].copy()
a["v"] = [ci(r.median_acc, r.ci_lo, r.ci_hi) for r in a.itertuples()]
rows = []
for sc_, nm in (("loto", "within-subject LOTO"), ("loso", "LOSO"), ("lodo_pool", "LODO")):
    for w in (1, 10, 60):
        g = a[(a.scheme == sc_) & (a.w == w)].set_index("ds")
        rows.append([nm, w] + [g.v.get(d, "n/a") for d in DS_KEYS])
TAB_(pd.DataFrame(rows, columns=["scheme", "window s"] + [LABELS[d] for d in DS_KEYS]),
     "Table 11. Accuracy (%) of the backward decoder by window length, median over subjects [95% CI] (lags 0-500 ms, 57 channels, "
     "non-overlapping windows; DTU trials are 48 s after trimming, so no 60-s windows exist). All values: tables/decoder_accuracy_vs_window.csv.")
FIG("c4_accuracy_vs_window", "Figure C4. Accuracy vs window length per scheme (n = 13/18/16/30/18 subjects).")
s = snr5.reset_index()
s = s[s.scheme.isin(["loto", "loso", "lodo_pool", "lodo_avgdec", "lodo_raw"])]
s["SNR1 [95% CI]"] = [f"{f(r.snr1_median)} [{f(r.snr1_ci_lo)}, {f(r.snr1_ci_hi)}]" for r in s.itertuples()]
t = s.pivot(index="scheme", columns="ds", values="SNR1 [95% CI]").reindex(["loto", "loso", "lodo_pool", "lodo_raw", "lodo_avgdec"]).reset_index()
t.columns = ["scheme"] + [LABELS[d] for d in t.columns[1:]]
TAB_(t, "Table 12. 1-s evidence SNR1 = mean(d)/SD(d), d = r(att) - r(ign), per subject (lags 0-500 ms). LODO variants: pool = dataset-"
     "equal, subject-equal pooled covariance; raw = sample-weighted pooled covariance; avgdec = average of per-subject decoders. The "
     "official baseline's 53.94% at 1 s implies SNR1 = 0.0989.")
kk = snr5.k
P(f"SNR law: fitting accuracy(w) = Phi(k * SNR1 * sqrt(w)) over subjects and windows gives k = {f(kk.min(),2)}-{f(kk.max(),2)} (median "
  f"{f(kk.median(),2)}). k < 1 means consecutive 1-s windows are positively correlated, so averaging buys a little less than sqrt(w). "
  f"Within-subject SNR1 is {f(snr_ratio.min(),2)}-{f(snr_ratio.max(),2)}x the LODO SNR1 (per dataset), which is the main cost of cross-dataset transfer. The three LODO aggregations "
  "(dataset-equal pooled covariance, sample-weighted pooled covariance, averaged per-subject decoders) differ by <= 0.3 pp at 1 s.")
FIG("c4_snr_law", "Figure C5. Measured vs predicted accuracy under the SNR law (dot = subject x window length).")
pcs = pc[(pc.scheme == "lodo_pool") & (pc.ds == "ALL")].copy()
names = {"c19-common57-car": "causal 1-9 Hz, CAR, 57 ch (reference)", "z19-common57-car": "zero-phase 1-9 Hz",
         "sup-common57-car": "supplied 32 Hz preprocessed data", "cwide-common57-car": "causal 0.5-30 Hz (64 Hz)",
         "c19-common57-nocar": "no re-reference", "c19-b64ustc58-car": "58-ch montage", "c19-b64uhd62-car": "62-ch montage (USTC zero-filled)"}
rows = []
for cfg, nm in names.items():
    r = []
    for lag in ("0-250ms", "0-500ms"):
        for w in (1, 10):
            g = pcs[(pcs.cfg == cfg) & (pcs.lag == lag) & (pcs.w == w)]
            if not len(g):
                r.append("n/a")
                continue
            g = g.iloc[0]
            r.append(f"{g.median_acc*100:.1f}" + ("" if cfg == MAIN else f" ({g.median_delta_acc_vs_main*100:+.2f}; p={f(g.wilcoxon_p,2)})"))
    rows.append([nm] + r)
TAB_(pd.DataFrame(rows, columns=["pipeline", "0-250 ms, 1 s", "0-250 ms, 10 s", "0-500 ms, 1 s", "0-500 ms, 10 s"]),
     "Table 13. Pipeline comparison under LODO, all 95 subjects: median accuracy % (paired median difference vs the reference in pp; "
     "Wilcoxon p across subjects).")
P("H5 verdict: causal filtering costs nothing. Zero-phase filtering is not better; where the paired test is significant, it is slightly "
  f"worse. The supplied 32 Hz preprocessed data are not better either, and are worse for KUL-AV-GC at 1 s ({supav.median_delta_acc_vs_main*100:+.2f} pp, "
  f"p = {f(supav.wilcoxon_p,2)}). Dropping CAR lowers accuracy and SNR1. The causal 0.5-30 Hz variant (64 Hz) is the only one ahead of the "
  f"reference: {cw10.median_delta_acc_vs_main*100:+.2f} pp at 10 s (p = {f(cw10.wilcoxon_p,2)}, uncorrected for the {int(len(pcsel)/4)} comparisons) "
  f"and {cw1.median_delta_acc_vs_main*100:+.2f} pp at 1 s (p = {f(cw1.wilcoxon_p,2)}); worth a follow-up, not yet a conclusion.")

# ---------------------------------------------------------------------------
BREAK()
H2("8. Phase D: domain shift and spatial shortcuts")
g = fp[fp.features.str.startswith("cov")]
rows = []
for al, nm in (("none", "none (raw scale)"), ("trace", "none, trace-normalised"), ("ea", "EA per recording"),
               ("running_ea", "causal running EA")):
    d = g[(g.alignment == al) & (g.task == "dataset")].iloc[0]
    sj = g[(g.alignment == al) & (g.task == "subject")].set_index("scope")
    rows.append([nm, pct(d.acc), pct(d.bal_acc)] + [pct(sj.loc[x, "acc"]) for x in DS_KEYS])
am = fp[fp.features.str.startswith("amplitude")]
for r in am.itertuples():
    rows.append([r.features, pct(r.acc), pct(r.bal_acc)] + ["-"] * 5)
TAB_(pd.DataFrame(rows, columns=["features / alignment", "dataset ID acc", "balanced acc"] + [f"subject ID {LABELS[d]}" for d in DS_KEYS]),
     f"Table 14. H10 fingerprints: 5-s epochs (n = 30,936 from 1,979 trials), 1-9 Hz and 8-13 Hz covariances (57 -> 56-dim zero-sum "
     f"projection, log-Euclidean tangent space), PCA(100) + logistic regression, 5-fold CV grouped by trial. Dataset-ID chance: "
     f"{pct(fpd.loc['none','chance_majority'])} (majority), 20% (uniform).")
FIG("d1_embedding", "Figure D1. Tangent-space PCA of 5-s covariances before and after alignment (8,000 random epochs).")
rows = []
for w in ("5", "1"):
    q = sp[sp.window_s == w].pivot_table(index=["model", "ds"], columns="scheme", values="median_acc")
    for (m, d), r in q.iterrows():
        rows.append([f"{w} s", m, LABELS[d], pct(r["within_trial"]), pct(r["LOTO"]), pct(r["LOSO"]), pct(r["LODO"]),
                     pct(sp[(sp.window_s == w) & (sp.scheme == "trialID_within") & (sp.ds == d)].median_acc.iloc[0]) if m == "riemann" else "-"])
TAB_(pd.DataFrame(rows, columns=["window", "model", "dataset", "within-trial split", "LOTO*", "LOSO", "LODO", "trial-ID"]),
     "Table 15. H11 attended-side decoding (filter bank 1-4/4-8/8-13/13-30 Hz; FBCSP-LDA and Riemannian tangent-space logistic "
     "regression), median subject accuracy. *KUL-AV-GC: leave-one-trial-out (each trial holds both sides); other datasets: balanced "
     "leave-pair-out. Trial-ID chance = 1/trials per subject (12.5%, 1.7%, 5%, 25%, 5%). Windows capped at 24 (5 s) / 15 (1 s) per trial.")
P(f"Spatial decoders look good only when windows of the same trial appear in training and test data: the median within-trial-split "
  f"minus held-out-trial gap is {f(gap5.median()*100)} pp at 5 s (up to {f(gap5.max()*100)} pp, KUL-UHD FBCSP "
  f"{pct(q5.loc[('fbcsp','UHD'),'within_trial'])} -> {pct(q5.loc[('fbcsp','UHD'),'LOTO'])}). The same features identify the trial. "
  "In USTC and KUL-UHD held-out-trial accuracy is significantly BELOW 50%: labels alternate by trial parity, so the trials nearest in "
  "time (most similar drift state) carry the opposite label. Across datasets (LODO) nothing transfers.")
cc = physc.copy()
t = phys[phys.feature.isin(["ali", "heog", "eog0"])].copy()
t["ds"] = t.ds.map(LABELS)
t["d [95% CI]"] = [f"{f(r.median_d,2)} [{f(r.ci_lo,2)}, {f(r.ci_hi,2)}]" for r in t.itertuples()]
t = t[["ds", "feature", "n_subjects", "d [95% CI]", "share_positive", "wilcoxon_p", "fdr_q"]]
t["share_positive"] = t.share_positive.map(pct)
t["wilcoxon_p"] = t.wilcoxon_p.map(lambda v: f(v, 2))
t["fdr_q"] = t.fdr_q.map(lambda v: f(v, 2))
TAB_(t, "Table 16. H12 physiology vs attended side: per-subject Cohen's d (right minus left, 10-s bins), across-subject Wilcoxon, "
     "FDR over all tests. ALI = (R - L)/(R + L) parieto-occipital 8-13 Hz power; heog = mean(AF7,F7,FT7) - mean(AF8,F8,FT8) below 1 Hz; "
     "eog0 = first recorded external channel (USTC: HEO).")
t = pd.DataFrame({"signal": physw.signal, "subjects": physw.n_subjects, "switches": physw.n_switches,
                  "post - pre (median [95% CI])": [f"{m:.3g} [{lo:.3g}, {hi:.3g}]"
                                                   for m, lo, hi in zip(physw.post_minus_pre, physw.ci_lo, physw.ci_hi)],
                  "Wilcoxon p": [f"{p_:.2g}" for p_ in physw.wilcoxon_p]})
TAB_(t, "Table 17. KUL-AV-GC switch-locked averages (+-60 s around each of the 99 genuine direction switches, sign-aligned).")
FIG("d4_switch_locked", "Figure D2. KUL-AV-GC switch-locked ALI, hEOG proxy and EOG channels (median over subjects, 95% bootstrap band).")
P("There is no alpha-lateralisation or EOG step at the KUL-AV-GC switch. The KUL-AV-GC recordings are high-passed near 1 Hz, "
  "so a sustained gaze-related EOG level cannot survive in them; the proxy is uninformative by construction there and in the "
  "mean-removed KUL2016 data. The one robust side marker is USTC's recorded HEO channel. Condition-wise ALI effects in KUL-AV-GC "
  "(FixedVideo d = " + f(cc[(cc.cond == 'FixedVideo') & (cc.feature == 'ali')].median_d.iloc[0], 2) + ", MovingVideo d = "
  + f(cc[(cc.cond == 'MovingVideo') & (cc.feature == 'ali')].median_d.iloc[0], 2)
  + ") have opposite signs and are not FDR-corrected across the 8 condition tests; treat them as exploratory.")

# ---------------------------------------------------------------------------
BREAK()
H2("9. Phase E: switch detection and the accuracy-latency trade-off")
P(f"Scorer: MATLAB/Octave are not installed, so computeSwitchLatency.m and scorePredictions.m were ported line by line (scripts/scorer.py). "
  f"Equivalence: {int(sc_tests.passed.sum())}/{len(sc_tests)} hand-derived cases pass, including 3,000 random sequences with zero mismatches "
  "against an independent brute-force implementation of the documented split search, plus 300 random subjects for the compiled "
  "version. No MATLAB-scored outputs are shipped (scoring_result.zip is empty), so no direct comparison with MATLAB was possible.")
UL([
    "Two switches within 100 s: the search window of the first switch contains the second. If the label reverts, the 'old label until "
    "the end of the window' split can outscore the true split; it then fails the 0.5-s sustain check, the search resumes past it, and the "
    "first switch is scored undetected (SDT = Inf). A perfect decoder is detected only if the next reverting switch is >= 50 s later "
    f"(cases O in tables/scorer_equivalence_tests.csv). Under the default synthetic schedule (gaps U(30, 90) s) this hits {n_or_miss}/{n_or} "
    "switches for an oracle decoder; its L still reads 1.00 because L is the median over switches.",
    "The sustain check is not clipped to the trial: a switch in the last 0.5 s of a trial can be confirmed by the next trial's labels.",
])
t = budget.copy()
t.columns = ["component", "lookahead ms"]
TAB_(t, "Table 18. Lookahead budget of the evaluated configurations (decoder lags 0-500 ms). With 0-250 ms lags the stamping advance "
     "is 750 ms. Causal filter group delay is lag, not lookahead.")
P(f"Lookahead unit test (tables/lookahead_test.csv): large perturbations of all inputs (EEG and both envelopes) after t + 1 s leave every "
  f"label up to t unchanged, for 3 integrators x 7 values of t ({int(legal.passed.sum())}/{len(legal)} pass). Two negative controls are "
  "flagged as violations: a 2-s budget, and zero-phase filtering. A first 1.25-s control was not flagged (the running z-score clips small "
  "leaks), so the test has limited sensitivity to leaks shorter than about 0.5 s.")
rows = []
for d in DS_KEYS:
    r, n, o = bt.loc[d], bn.loc[d], orc.loc[d]
    rows.append([LABELS[d], int(r.nSwitches), f"{r.Acc:.1f}", f(r.SDT, 3), f(r.L), f(r.H), pct(r.miss_rate), f"{n.Acc:.1f}", f(n.L), f(n.H),
                 f"{int(o.nUndetected)}/{int(o.nSwitches)}"])
TAB_(pd.DataFrame(rows, columns=["held-out dataset", "SYNTHETIC switches", "Acc %", "SDT s", "L", "H", "miss rate",
                                 "null Acc %", "null L", "null H", "oracle misses"]),
     f"Table 19. SYNTHETIC switches (generateSyntheticSwitches.m schedule; label and evidence columns swapped together), LODO "
     f"evidence (1-s windows, 0.25-s hop, lags 0-500 ms), best integrator on the median held-out dataset = {best}. Null = sign-randomised "
     "evidence with the same integrator.")
fam = real5.assign(fam=real5.integrator.str.extract(r"^(argmax|ma|hmmz|hmm|ladder)")[0]).groupby(["fam", "test_ds"]).H.max().unstack()
fam = fam[DS_KEYS].round(3).reset_index()
fam.columns = ["integrator family (best member)"] + [LABELS[d] for d in DS_KEYS]
TAB_(fam, "Table 20. Best H per integrator family and held-out dataset (SYNTHETIC; 0-500 ms lags). Families: argmax; moving average "
     "1-40 s; 2-state HMM (p_stay grid, emissions fitted on the training datasets' out-of-fold evidence); HMM on running-SD-normalised "
     "evidence with temperature; N-state ladder (MESD-style, N = 3-9).")
FIG("e1_tradeoff_c19-common57-car_lodo_pool_0-500ms", "Figure E1. Acc-L trade-off per held-out dataset (SYNTHETIC switches; colour = "
    "real evidence, grey = sign-randomised null; lines = iso-H).")
b2_ = sw2[(~sw2.null) & (sw2.switches == "syn") & (sw2.integrator == best)].set_index("test_ds")
P("With 0-250 ms lags (750 ms stamping advance) the same integrator gives H = " + ", ".join(f"{LABELS[d]} {f(b2_.loc[d,'H'])}" for d in DS_KEYS)
  + ", essentially the same trade-off.")
P(f"Genuine switches. The 99 KUL-AV-GC direction switches are invisible to a speaker decoder. Scored with direction evidence from "
  f"spatial decoders trained on the other four datasets, the best configuration ({sbest.model}, {sbest.integrator}) reaches "
  f"Acc = {f(sbest.Acc,3)}%, SDT = {f(sbest.SDT,3)} s, L = {f(sbest.L)} and H = {f(sbest.H)}, against a null L of {f(snull)}. Sample accuracy "
  "is at chance and L is only modestly above the null, so direction is essentially not decodable across datasets with these features. Mapping the speaker decoder to a direction through the known stream azimuths gives "
  f"an apparently high H ({f(dirv.H)}, {dirv.integrator}), but that number is INVALID. Column 0 is the attended speaker for the whole "
  "KUL-AV-GC trial by construction, so any sticky integrator that locks onto column 0 turns into a perfect direction track. It also "
  "assumes stream positions are known at test time.")

# ---------------------------------------------------------------------------
BREAK()
H2("10. Hypothesis verdicts (H1-H12)")
P("What the hypotheses are. An earlier exploratory analysis looked at a single example trial from each dataset and proposed twelve "
  "claims (H1-H12) about the data. A single trial cannot show whether an effect is general, so each claim is stated in full below "
  "with the example-trial value that motivated it, why it matters for the challenge, and how it was tested here on the full corpus.")
HYPO = [
    ("H1", "Amplitude scale and DC offsets",
     "The five datasets store EEG on very different amplitude scales (median channel SD about 16x apart), and DTU, KUL-UHD and USTC "
     "carry large constant (DC) offsets because they were never high-pass filtered.",
     "Pooling data with different scales and offsets lets a model tell datasets apart by amplitude alone and breaks fixed "
     "normalisation constants (like the official HMM's).",
     "Per channel and per trial: mean, SD, robust SD, RMS/SD and drift for all 149,336 channel-trials; subject medians with bootstrap CIs."),
    ("H2", "Pre-filtering history",
     "The datasets were filtered differently before release: KUL-AV-GC low-passed near 40 Hz and high-passed below 1 Hz; KUL-UHD and "
     "USTC contain strong 50 Hz mains noise.",
     "Different band limits change what frequency content a model can rely on; a model trained on one filtering may not transfer.",
     "Welch spectra of every trial: 1/f fit, spectral roll-off, power below 1 Hz, 50 Hz line ratio; inference table per dataset."),
    ("H3", "Edge transients and bad channels",
     "Trials in USTC and KUL-UHD begin and end with large electrical jumps (thousands of units at t = 0), and some channels are bad "
     "(e.g. KUL-UHD P7 with SD 2,381 vs 71 at Cz).",
     "Filters ring on such jumps and one bad channel can dominate a common-average reference, corrupting the first seconds of every trial.",
     "Largest first-difference jump near each edge (> 20 robust SD), bad/flat channel flags against dataset medians, share per dataset."),
    ("H4", "The SNR law",
     "Decoding accuracy for a window of w seconds is predicted by the 1-s evidence signal-to-noise ratio: accuracy = Phi(SNR1 * sqrt(w)). "
     "Within subject, KUL-AV-GC SNR1 is about 0.16; the official baseline (53.94% at 1 s) implies about 0.10.",
     "If true, one number (SNR1) predicts accuracy at every window length and tells how much a better decoder is worth.",
     "SNR1 = mean/SD of r(attended) - r(ignored) over 1-s windows per subject; fit of k in Phi(k * SNR1 * sqrt(w)) for w = 1-60 s "
     "under within-subject, cross-subject and cross-dataset validation."),
    ("H5", "Causal vs zero-phase filtering",
     "Real-time (causal) filtering, which the challenge requires, performs no worse than offline zero-phase filtering.",
     "The 1-s lookahead rule forbids zero-phase filters; if they were clearly better, the rule would cost accuracy.",
     "The same cross-dataset decoder run on causal and zero-phase versions of the data (and on the supplied 32 Hz data), compared per "
     "subject with a paired Wilcoxon test."),
    ("H6", "What the KUL-AV-GC 5-minute switch is",
     "In KUL-AV-GC the change at 5 minutes switches the attended direction (the talker moves to the other side), not the attended "
     "talker.",
     "It decides whether the only genuine within-trial switches in the training data can be used to train a speaker-switch detector.",
     "Per-sample CND labels (attendedStream, attendedAzimuth) for all 99 trials, plus a cross-half decoding test: train on one half, "
     "test on the other under 'switch' and 'no switch' assumptions."),
    ("H7", "The attended stream is louder",
     "In KUL2016 and KUL-AV-GC the attended audio envelope has a larger amplitude than the ignored one (65% and 59% of trials).",
     "A model could pick the louder stream without using the EEG at all, which would not work on test data.",
     "SD ratio of the two envelopes in every trial, binomial and Wilcoxon tests, and a classifier that sees only envelope statistics."),
    ("H8", "The label follows trial order",
     "In KUL-UHD and USTC the attended side (left/right) alternates strictly with trial number: odd trials one side, even trials the other.",
     "Anything correlated with trial order (drift, fatigue, electrode settling) then predicts the label, a shortcut that fails on "
     "unseen subjects.",
     "Cross-tabulation of label vs trial parity and order, and a 'drift-only' classifier using slow features (DC, drift, sub-1 Hz power)."),
    ("H9", "USTC stream columns may be swapped",
     "In one USTC example, a decoder that never saw the trial correlated more with the stream marked 'ignored' (r = 0.083 vs 0.026), "
     "suggesting the attended/ignored columns are swapped.",
     "Swapped labels would make USTC poison both training and evaluation.",
     "Decoders trained without the subject (LOSO) or without the dataset (LODO); whole-trial correlation with each column in all 360 "
     "USTC trials; per-subject binomial tests with FDR correction."),
    ("H10", "Covariance fingerprints the dataset",
     "The spatial covariance of the EEG identifies which dataset a recording came from almost perfectly (99.7%), and Euclidean "
     "alignment (EA) removes only part of this (to 76%).",
     "A strong dataset fingerprint means models can learn recording setup instead of attention, and cross-dataset transfer suffers.",
     "Classifiers predicting dataset and subject from 30,936 5-s covariance epochs, with no alignment, EA, and causal running EA, "
     "cross-validated so no trial is split."),
    ("H11", "Spatial decoders exploit trial fingerprints",
     "Spatial (CSP / Riemannian) decoders of the attended side look good only when windows of the same trial are in training and test "
     "data; they collapse when whole trials are held out (literature: trial ID ~100%, held-out trials 41-45% on KUL-AV-GC).",
     "Direction decoding is what the eye-gaze-controlled test sets require; if it only memorises trials it will fail there.",
     "FB-CSP and Riemannian decoders under random within-trial splits, held-out trials, held-out subjects and held-out datasets, plus "
     "predicting the trial ID from the same features."),
    ("H12", "No physiological marker at the switch",
     "At the KUL-AV-GC side switch there is no change in alpha-band lateralisation or horizontal eye movements (example: ALI "
     "0.040 -> 0.045, p = 0.77).",
     "Alpha lateralisation and gaze are the classic markers of spatial attention; if absent, direction must be inferred another way.",
     "Parieto-occipital alpha lateralisation index and EOG signals vs the attended side in all datasets, and time-locked to all 99 "
     "genuine switches (+-60 s)."),
]
TAB_(pd.DataFrame(HYPO, columns=["ID", "short name", "the hypothesis in full (from the example-trial EDA)", "why it matters",
                                 "how it was tested on the full corpus"]),
     "Table 21. The twelve hypotheses: what each claims, why it matters and how it was tested.",
     widths=[0.04, 0.10, 0.34, 0.24, 0.28])
vc = verd.verdict.str.split(":").str[0].str.split(" ").str[0].value_counts()
n_conf, n_part, n_ref = int(vc.get("confirmed", 0)), int(vc.get("partly", 0)), int(vc.get("refuted", 0))
B.append(("verdict_key", [
    ("confirmed", "The full-corpus data support the claim: the effect is present, in the stated direction, across subjects "
                  "(95% CI excluding 'no effect' where a test applies), not just in the example trial."),
    ("partly", "Part of the claim holds and part does not (for example it holds for one dataset but not another, or the effect is "
               "real but much smaller than the example trial suggested)."),
    ("refuted", "The full-corpus data contradict the claim: the effect is absent or points the other way."),
]))
P(f"Result: {n_conf} of 12 hypotheses confirmed, {n_part} partly confirmed, {n_ref} refuted. H7 is counted as confirmed because it holds "
  "fully for KUL2016, but for KUL-AV-GC it only partly holds.")
vi = verd.set_index("id")
av = q5.loc[("fbcsp", "AVGC")]
PLAIN = {
    "H1": ("Datasets are stored on very different amplitude scales, and three carry large DC offsets.",
           f"Yes. Typical channel SD differs {f(qc.median_sd.max() / qc.median_sd.min(), 3)}x between datasets, and DTU, KUL-UHD and USTC "
           "sit on offsets of thousands of units. Every model needs per-channel normalisation (a causal running z-score) before datasets "
           "can be pooled."),
    "H2": ("Datasets were filtered differently before release.",
           "Partly. KUL-AV-GC is clearly band-limited (about 1-41 Hz) and notched at 50 Hz. KUL-UHD and USTC do have a 50 Hz line, but "
           f"it is {f(min(weaker),2)}-{f(max(weaker),2)}x weaker than the example trial suggested. The other datasets are not high-passed."),
    "H3": ("Trials start and end with electrical jumps in USTC and KUL-UHD, and some channels are bad.",
           f"Yes. Every USTC and KUL-UHD trial has a large jump near an edge ({pct(qc.loc['UHD','share_edge_transient_trials'],0)}), "
           f"against 3-5% elsewhere. {pct(qc.loc['UHD','share_bad_channels'])} of KUL-UHD channels are bad. Edges must be trimmed or "
           "the filters warmed up."),
    "H4": ("Decoding accuracy grows with window length in a predictable way, set by the 1-s signal-to-noise ratio.",
           f"Yes. Accuracy follows Phi(k * SNR1 * sqrt(w)) with k = {f(snr5.k.min(),2)}-{f(snr5.k.max(),2)} in every dataset and scheme. "
           f"For KUL-AV-GC, SNR1 is {f(snr5.loc[('loto','AVGC'),'snr1_median'])} within subject and "
           f"{f(snr5.loc[('lodo_pool','AVGC'),'snr1_median'])} across datasets, close to the 0.099 implied by the official baseline."),
    "H5": ("Real-time (causal) filtering loses nothing compared with offline zero-phase filtering.",
           "Yes. Across all 95 subjects, causal filtering is never worse; zero-phase filtering is slightly worse where the difference "
           "is significant. The challenge's causality rule therefore costs nothing at the filtering stage."),
    "H6": ("The KUL-AV-GC 5-minute event changes where the listener attends, not whom they listen to.",
           "Yes. The CND labels show no speaker switch and 99 side switches, and a decoder trained on one half of the trials still "
           f"tracks the same talker in the other half ({pct(xb60.median_acc)} at 60 s vs {pct(xa60.median_acc)} if the talker had changed)."),
    "H7": ("The attended audio stream is systematically louder in KUL2016 and KUL-AV-GC.",
           f"Confirmed for KUL2016 ({pct(asym.loc['KUL','share_col0_larger_sd'],0)} of trials; an envelope-only classifier gets "
           f"{pct(lk.loc['KUL','median_acc'])}). Only partly for KUL-AV-GC ({pct(asym.loc['AVGC','share_col0_larger_sd'],0)}, not significant "
           "per trial, and useless to a classifier). This is a shortcut a model could exploit."),
    "H8": ("In KUL-UHD and USTC the attended side is fixed by whether the trial number is odd or even.",
           "Yes, in 100% of trials and every subject. Slow-drift features alone predict the label only weakly (at most "
           f"{pct(dl_max)}), but any model that sees trial order can learn the label without using the EEG."),
    "H9": ("The USTC audio columns may be swapped (the ignored stream stored as the attended one).",
           f"No. A held-out decoder prefers column 0 in {pct(1 - usv.loc[('loso','USTC'),'share_col1_wins'])} of USTC trials, and no "
           "subject shows the reverse. USTC is just harder to decode."),
    "H10": ("EEG covariance reveals which dataset a recording came from, and alignment removes only part of that.",
            f"Yes. Dataset identity is predicted at {pct(fpd.loc['none','acc'])} from covariance, still {pct(fpd.loc['ea','acc'])} "
            f"after Euclidean alignment and {pct(fpd.loc['running_ea','acc'])} after the causal version (chance "
            f"{pct(fpd.loc['none','chance_majority'])}). Recording setup is a strong confound for pooled training."),
    "H11": ("Spatial (direction) decoders look good only because they memorise trials.",
            f"Yes. The same features identify the trial at up to {pct(tid5.median_acc.max(),0)}, accuracy drops by a median "
            f"{f(gap5.median()*100)} pp when whole trials are held out, and it is at chance across datasets. For KUL-AV-GC: "
            f"{pct(av['within_trial'])} within trial, {pct(av['LOTO'])} on held-out trials, {pct(av['LODO'])} across datasets."),
    "H12": ("Brain or eye signals of spatial attention do not change at the KUL-AV-GC side switch.",
            "Confirmed: neither alpha lateralisation nor eye movements change at the 99 switches (all p >= 0.08). But the KUL-AV-GC "
            "data are high-passed near 1 Hz, which removes slow eye-movement signals, so this is weak evidence of absence. USTC's "
            "recorded eye channel does separate left from right trials."),
}
rows = [[h, PLAIN[h][0], vi.loc[h, "verdict"].split(":")[0], PLAIN[h][1]] for h in vi.index]
TAB_(pd.DataFrame(rows, columns=["ID", "claim tested", "verdict", "what the full corpus shows"]),
     "Table 22. Verdicts in plain language: what was claimed, the verdict and what the full corpus shows.", widths=[0.05, 0.27, 0.12, 0.56])
v = verd[["id", "previous", "full_corpus", "n", "verdict"]].copy()
v.columns = ["ID", "previous estimate (n = 1 trial/dataset)", "full-corpus estimate (with CIs)", "n", "verdict"]
TAB_(v, "Table 23. Verdicts with the numbers behind them (also tables/hypotheses_verdicts.csv, which lists the evidence files).",
     widths=[0.05, 0.17, 0.52, 0.12, 0.14])

# ---------------------------------------------------------------------------
H2("11. What this means for modelling")
UL([
    "Front end: use the causal chain above (state-initialised high-pass, CAR over the 57 common channels matched by name, causal "
    "band-pass, running robust z-score with clipping). It is never worse than zero-phase filtering or the supplied 32 Hz data "
    "(Table 13), it is causal, and it removes the DC offsets and scale differences of Table 2. Add explicit edge handling, because "
    "KUL-UHD and USTC have transients in every trial.",
    "Labels: train speaker decoders on the per-sample CND attendedStream. For direction targets use the per-sample azimuth, never the "
    "trial label (wrong for 50% of KUL-AV-GC samples). Do not interpret SuperHuge column 0 as 'attended' at test time.",
    f"Validation: report LODO with KUL-AV-GC as the proxy fold, aggregate per subject, and group folds by envelope identity (KUL2016 "
    "and KUL-UHD share all of their audio; KUL-AV-GC names are unreliable). Never score windows from training trials: spatial "
    f"decoders gain up to {f(gap5.max()*100)} pp from trial fingerprints (Table 15).",
    f"Shortcuts to neutralise: parity-locked labels (KUL-UHD, USTC) make any slow-drift or order feature a label proxy. The KUL2016 "
    f"'loud column' lets an envelope-only model reach {pct(lk.loc['KUL','median_acc'])}; use envelope-symmetric model inputs or equalise the envelope scale per "
    f"trial. The dataset fingerprint survives Euclidean alignment ({pct(fpd.loc['ea','acc'])} with EA, {pct(fpd.loc['running_ea','acc'])} with causal running EA).",
    f"Integrator: a 10-20 s moving average or a variance-normalised HMM with p_stay 0.98-0.999 per 0.25-s step is near the frontier "
    f"(Table 20). Integrator choice is worth {f(integ_gain.min(),2)}-{f(integ_gain.max(),2)} H over argmax; raising SNR1 matters more (accuracy ~ Phi(0.9 * SNR1 * sqrt(w))). "
    f"Choose on the median held-out dataset, and check the switch spacing against the scorer's 50-s property.",
    "Direction decoding: spatial/EOG cues do not transfer across datasets here. Unless the blind sets provide stream positions, direction "
    "labels must come from speaker decoding plus position metadata; confirm with the organisers what is available at test time.",
])

H2("12. Limitations")
UL([
    "MATLAB/Octave unavailable: the scorer is a verified Python port, not the official binary run; the synthetic-switch generator is also a "
    "port (same schedule, independent random stream), so SYNTHETIC numbers are not seed-identical to the MATLAB baseline.",
    "MNE, statsmodels and UMAP are not installed: TRFs and topographies use own implementations; embeddings use PCA; subject-level "
    "Wilcoxon tests replace mixed models.",
    "The published baseline's hold-out split and its synthetic-switch settings are not reproduced exactly, so Table 19 is not directly "
    "comparable with 'H 0.7002'.",
    "Spatial decoding used capped window counts (<= 24 5-s and <= 15 1-s windows per trial) to fit in memory; continuous windows were "
    "computed only for the KUL-AV-GC genuine-switch evaluation. The optional CCA decoder and a fixed-lag smoother were not run (the "
    "lookahead budget is fully used by the decision-stamping advance).",
    "Leave-pair-out replaces leave-one-trial-out for single-label datasets in classification analyses. With 4 trials per KUL-UHD "
    "subject it trains on 2 trials, so those numbers are noisy.",
    "The dry-run gate was applied to extraction, QC, caching and the spatial cache (one subject per dataset). Decoders were checked on "
    "the first subjects' outputs during the full run rather than in a separate dry run.",
    "Several scripts were edited by another session during the run (checkpointing and window capping in d3_spatial, the FFT null in "
    "c1_xcorr, figure titles). All affected steps were rerun, and the Phase E results reproduced exactly.",
    "The lookahead test has limited sensitivity to leaks shorter than about 0.5 s (see Phase E).",
])

H2("13. Reproducibility")
P("Environment: .venv (Python 3.12.13); exact package versions in reports/eda_full/requirements.txt; every parameter in "
  "reports/eda_full/config.yaml (seed 20270101). Command: cd reports/eda_full && bash scripts/run_all.sh (every step is resumable "
  "from cache/). Hardware: 8 logical CPUs and 23 GB RAM, shared with other users (load average 5-15); at most 4 workers x 2 BLAS "
  "threads. Wall-clock time of this run, including writing and debugging the scripts: about 4 h (03:14-07:15 UTC, 2026-09-24); per-step "
  "timings are in logs/. Outputs: tables/ (all CSVs), figures/ (PNG at 150 dpi, each with its "
  "underlying CSV), logs/, cache/ (36 GB of intermediate files; data/ was never modified).")


# ===========================================================================
# Markdown
def howto_for_table(cap):
    m = re.match(r"Table (\d+)\.", cap)
    return TAB_HOWTO.get(int(m.group(1))) if m else None


def md_table(df):
    cols = [str(c) for c in df.columns]
    out = ["| " + " | ".join(cols) + " |", "|" + "---|" * len(cols)]
    for r in df.itertuples(index=False):
        out.append("| " + " | ".join(str(x).replace("|", "/").replace("\n", " ") for x in r) + " |")
    return "\n".join(out)


md = []
for k, p in B:
    if k == "h1":
        md.append(f"# {p}\n")
    elif k == "h2":
        md.append(f"## {p}\n")
    elif k == "p":
        md.append(p + "\n")
    elif k == "ul":
        md.append("\n".join(f"- {x}" for x in p) + "\n")
    elif k == "table":
        df, cap, _ = p
        md.append(f"*{cap}*\n\n" + md_table(df) + "\n")
        h = howto_for_table(cap)
        if h:
            md.append(f"> **How to read this:** {h}\n")
    elif k == "fig":
        name, cap = p
        md.append(f"![{cap}](figures/{name}.png)\n\n*{cap}*\n")
        if name in FIG_HOWTO:
            md.append(f"> **How to read this:** {FIG_HOWTO[name]}\n")
    elif k == "finding":
        title, found, why = p
        md.append(f"**{title}**\n\n{found}\n\n*Why it matters:* {why}\n")
    elif k == "verdict_key":
        md.append("How to read the verdicts:\n\n" + "\n".join(f"- **{a}**: {b}" for a, b in p) + "\n")
with open(os.path.join(OUT, "README.md"), "w") as fh:
    fh.write("\n".join(md))

# ===========================================================================
# PDF
from reportlab.lib import colors  # noqa: E402
from reportlab.lib.enums import TA_JUSTIFY  # noqa: E402
from reportlab.lib.pagesizes import A4  # noqa: E402
from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet  # noqa: E402
from reportlab.lib.units import cm  # noqa: E402
from reportlab.pdfbase import pdfmetrics  # noqa: E402
from reportlab.pdfbase.ttfonts import TTFont  # noqa: E402
from reportlab.platypus import (Image, KeepTogether, ListFlowable, ListItem, PageBreak, Paragraph,  # noqa: E402
                                SimpleDocTemplate, Spacer, Table, TableStyle)
from xml.sax.saxutils import escape  # noqa: E402

FD = "/usr/share/fonts/truetype/dejavu/"
pdfmetrics.registerFont(TTFont("DV", FD + "DejaVuSans.ttf"))
pdfmetrics.registerFont(TTFont("DVB", FD + "DejaVuSans-Bold.ttf"))
pdfmetrics.registerFont(TTFont("DVI", FD + "DejaVuSans-Oblique.ttf"))
pdfmetrics.registerFontFamily("DV", normal="DV", bold="DVB", italic="DVI", boldItalic="DVB")
ss = getSampleStyleSheet()
st_body = ParagraphStyle("b", parent=ss["Normal"], fontName="DV", fontSize=9, leading=12.2, alignment=TA_JUSTIFY, spaceAfter=5)
st_h1 = ParagraphStyle("h1", parent=ss["Title"], fontName="DVB", fontSize=16, leading=20, spaceAfter=8)
st_h2 = ParagraphStyle("h2", parent=ss["Heading2"], fontName="DVB", fontSize=12.5, leading=16, spaceBefore=8, spaceAfter=5,
                       textColor=colors.HexColor("#1f3a5f"))
st_cap = ParagraphStyle("cap", parent=st_body, fontName="DVI", fontSize=7.8, leading=10, textColor=colors.HexColor("#444444"),
                        alignment=0, spaceAfter=8)
st_cell = ParagraphStyle("cell", parent=st_body, fontSize=6.8, leading=8.3, alignment=0, spaceAfter=0)
st_head = ParagraphStyle("head", parent=st_cell, fontName="DVB")
st_li = ParagraphStyle("li", parent=st_body, spaceAfter=2)
st_ftitle = ParagraphStyle("ft", parent=st_body, fontName="DVB", fontSize=9.5, leading=12.5, spaceAfter=1,
                           textColor=colors.HexColor("#1f3a5f"), alignment=0)
st_how = ParagraphStyle("how", parent=st_body, fontSize=8, leading=10.4, spaceAfter=0, alignment=0)
st_fbody = ParagraphStyle("fb", parent=st_body, fontSize=8.8, leading=11.6, spaceAfter=0)

PW = A4[0] - 3.2 * cm


def col_widths(df):
    """Every column at least as wide as its longest word; the remaining width is shared by content length."""
    sw = pdfmetrics.stringWidth
    mins, prefs = [], []
    for j, c in enumerate(df.columns):
        cells = [(str(c), "DVB")] + [(str(v), "DV") for v in df.iloc[:, j]]
        mins.append(min(max(sw(w, fn, 6.8) for t, fn in cells for w in (t.split() or [""])) + 7, 0.3 * PW))
        prefs.append(min(max(sw(t, fn, 6.8) for t, fn in cells) + 7, 0.5 * PW))
    mins, prefs = np.array(mins), np.maximum(np.array(prefs), mins)
    if prefs.sum() <= PW:
        w = prefs * PW / prefs.sum()
    elif mins.sum() >= PW:
        w = mins * PW / mins.sum()
    else:
        extra = prefs - mins
        w = mins + (PW - mins.sum()) * extra / extra.sum()
    return list(w / PW)


def howto_box(text):
    b = Table([[Paragraph("<b>How to read this:</b> " + escape(text), st_how)]], colWidths=[PW])
    b.setStyle(TableStyle([("BACKGROUND", (0, 0), (-1, -1), colors.HexColor("#fff8e6")),
                           ("BOX", (0, 0), (-1, -1), 0.4, colors.HexColor("#e0c27a")),
                           ("LEFTPADDING", (0, 0), (-1, -1), 6), ("RIGHTPADDING", (0, 0), (-1, -1), 6),
                           ("TOPPADDING", (0, 0), (-1, -1), 3), ("BOTTOMPADDING", (0, 0), (-1, -1), 4)]))
    return b


def para(t, s=st_body):
    return Paragraph(escape(str(t)), s)


def footer(canvas, doc):
    canvas.saveState()
    canvas.setFont("DV", 7.5)
    canvas.setFillColor(colors.HexColor("#666666"))
    canvas.drawString(1.6 * cm, 1.0 * cm, "EEG-sAAD Grand Challenge: full-corpus signal-processing EDA")
    canvas.drawRightString(A4[0] - 1.6 * cm, 1.0 * cm, f"page {doc.page}")
    canvas.restoreState()


story = []
for k, p in B:
    if k == "h1":
        story.append(para(p, st_h1))
        story.append(Paragraph(escape("reports/eda_full, generated from the result tables by scripts/f2_report.py, 2026-09-24"), st_cap))
    elif k == "h2":
        story.append(para(p, st_h2))
    elif k == "p":
        story.append(para(p))
    elif k == "ul":
        story.append(ListFlowable([ListItem(para(x, st_li), leftIndent=10, value="•") for x in p], bulletType="bullet",
                                  start="•", leftIndent=12, bulletFontName="DV", bulletFontSize=8))
        story.append(Spacer(1, 4))
    elif k == "table":
        df, cap, widths = p
        data = [[para(c, st_head) for c in df.columns]] + [[para(x, st_cell) for x in r] for r in df.itertuples(index=False)]
        if widths is None:
            widths = col_widths(df)
        tb = Table(data, colWidths=[w * PW for w in widths], repeatRows=1)
        tb.setStyle(TableStyle([("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#e8eef5")),
                                ("GRID", (0, 0), (-1, -1), 0.3, colors.HexColor("#b0b8c4")),
                                ("VALIGN", (0, 0), (-1, -1), "TOP"),
                                ("ROWBACKGROUNDS", (0, 1), (-1, -1), [colors.white, colors.HexColor("#f7f9fb")]),
                                ("LEFTPADDING", (0, 0), (-1, -1), 3), ("RIGHTPADDING", (0, 0), (-1, -1), 3),
                                ("TOPPADDING", (0, 0), (-1, -1), 2), ("BOTTOMPADDING", (0, 0), (-1, -1), 2)]))
        capp = Paragraph(escape(cap), st_cap)
        h = howto_for_table(cap)
        tail = [Spacer(1, 3), howto_box(h), Spacer(1, 9)] if h else [Spacer(1, 8)]
        if len(df) <= 14:
            story.append(KeepTogether([capp, tb] + tail))
        else:
            story += [capp, tb] + tail
    elif k == "fig":
        name, cap = p
        path = os.path.join(OUT, "figures", f"{name}.png")
        from PIL import Image as PImage
        w, h = PImage.open(path).size
        W = PW
        H_ = W * h / w
        if H_ > 11 * cm:
            H_ = 11 * cm
            W = H_ * w / h
        parts = [Image(path, width=W, height=H_), Paragraph(escape(cap), st_cap)]
        if name in FIG_HOWTO:
            parts += [howto_box(FIG_HOWTO[name]), Spacer(1, 9)]
        story.append(KeepTogether(parts))
    elif k == "break":
        story.append(PageBreak())
    elif k == "finding":
        title, found, why = p
        box = Table([[Paragraph(escape(title), st_ftitle)], [para(found, st_fbody)],
                     [Paragraph("<b>Why it matters:</b> " + escape(why), st_fbody)]], colWidths=[PW])
        box.setStyle(TableStyle([("BACKGROUND", (0, 0), (-1, -1), colors.HexColor("#f4f7fb")),
                                 ("LINEBEFORE", (0, 0), (0, -1), 2.5, colors.HexColor("#1f3a5f")),
                                 ("LEFTPADDING", (0, 0), (-1, -1), 8), ("RIGHTPADDING", (0, 0), (-1, -1), 6),
                                 ("TOPPADDING", (0, 0), (-1, -1), 2), ("BOTTOMPADDING", (0, 0), (-1, -1), 3)]))
        story.append(KeepTogether([box, Spacer(1, 6)]))
    elif k == "verdict_key":
        col = {"confirmed": "#2e7d32", "partly": "#b26a00", "refuted": "#c62828"}
        data = [[Paragraph(f'<font color="{col[a]}"><b>{a}</b></font>', st_cell), para(b, st_cell)] for a, b in p]
        tb = Table(data, colWidths=[0.14 * PW, 0.86 * PW])
        tb.setStyle(TableStyle([("GRID", (0, 0), (-1, -1), 0.3, colors.HexColor("#b0b8c4")), ("VALIGN", (0, 0), (-1, -1), "TOP")]))
        story.append(KeepTogether([para("How to read the verdicts:"), tb, Spacer(1, 6)]))

pdf = os.path.join(OUT, "EEG-sAAD_full_corpus_EDA_report.pdf")
doc = SimpleDocTemplate(pdf, pagesize=A4, leftMargin=1.6 * cm, rightMargin=1.6 * cm, topMargin=1.5 * cm, bottomMargin=1.6 * cm,
                        title="EEG-sAAD full-corpus signal-processing EDA", author="reports/eda_full")
doc.build(story, onFirstPage=footer, onLaterPages=footer)
print("wrote", pdf, "and README.md")
