"""Reading guides for every figure and table of the report, plus a glossary (used by f2_report.py)."""

GLOSSARY = [
    ("Trial", "One continuous recording (50 s to 10 min) in which a listener hears two talkers and attends to one."),
    ("Column 0 / column 1", "The two envelope streams stored per trial. Column 0 is the stream attended for most of the trial "
     "(converter convention); column 1 is the other one."),
    ("Envelope", "The slow loudness contour of a talker's speech (roughly 1-9 Hz). The decoder tries to reconstruct it from EEG."),
    ("Backward decoder", "A linear filter that maps the last 0-500 ms of EEG after each moment onto the speech envelope at that moment. "
     "The talker whose envelope correlates better with the reconstruction is predicted as attended."),
    ("r(att), r(ign), d", "Correlation of the reconstruction with the attended and ignored envelope over a window; d = r(att) - r(ign). "
     "d > 0 means the window was decoded correctly."),
    ("SNR1", "mean(d) / SD(d) over 1-s windows: how strong the 1-s evidence is compared with its noise. Accuracy follows "
     "Phi(k * SNR1 * sqrt(window)) (the SNR law, H4)."),
    ("LOTO", "Leave-one-trial-out within a subject: train on the subject's other trials, test on the held-out trial."),
    ("LOSO", "Leave-one-subject-out within a dataset: train on the other subjects of the same dataset."),
    ("LODO", "Leave-one-dataset-out: train on four datasets, test on the fifth. This is the closest proxy for the blind test sets "
     "(new subjects, new recording setup). KUL-AV-GC is the main proxy fold."),
    ("Within-trial split", "Random windows split into train/test with windows of the same trial on both sides. Leaky; shown only to "
     "measure how much a decoder memorises trials."),
    ("Median [95% CI]", "The median over subjects, with a 95% bootstrap confidence interval (2,000 resamples of subjects). If two CIs do "
     "not overlap, the difference is very unlikely to be chance."),
    ("p, q", "p = Wilcoxon signed-rank test across subjects (or binomial test across trials). q = p corrected for many tests (Benjamini-"
     "Hochberg FDR). Below 0.05 is conventionally 'significant'."),
    ("Cohen's d", "Effect size: difference of means divided by the pooled SD. About 0.2 is small, 0.5 medium, 0.8 large."),
    ("Acc, SDT, L, H", "The official metrics. Acc = % of 128 Hz samples labelled correctly. SDT = switch detection time in s (Inf = missed). "
     "L = median over switches of exp(-SDT/60), averaged over subjects (1 = instant, 0 = missed). H = harmonic mean of Acc and L; the "
     "headline score (official baseline H = 0.70)."),
    ("SYNTHETIC switch", "A switch imposed on a fixed-attention trial by swapping which stream counts as attended from a random time on "
     "(same rule as the official generateSyntheticSwitches.m). It measures reaction speed on data where no real switch happened."),
    ("Integrator", "A causal post-processor that turns the noisy 1-s evidence into stable labels: argmax (none), moving average, HMM or "
     "a state ladder. More smoothing = higher Acc but later switch detection."),
    ("Null (sign-randomised)", "The same pipeline fed with evidence whose sign is randomised: what a decoder with zero information scores."),
    ("CAR", "Common average reference: subtracting the mean of all channels at each sample."),
    ("EA / running EA", "Euclidean alignment: whitening each recording by its own mean covariance so recordings look alike. Running EA uses "
     "only the past (usable at test time)."),
    ("Causal / zero-phase", "Causal filters use only past samples (required by the 1-s lookahead rule); zero-phase filters also use "
     "future samples (not allowed at test time)."),
    ("Montage 57 / 58 / 62", "Channel sets matched by name: 57 common to all five datasets, 58 = BioSemi-64 ∩ USTC, 62 = BioSemi-64 ∩ KUL-UHD."),
]

CONVENTIONS = (
    "Colours: every figure uses one fixed colour per dataset - KUL-AV-GC red, DTU blue, KUL2016 green, KUL-UHD purple, USTC orange. "
    "Grey marks a baseline or null. Numbers are summarised per subject first and then across subjects, so a subject with many trials "
    "counts once. Unless stated otherwise, accuracies are medians over subjects with 95% bootstrap CIs in brackets, and n (subjects, "
    "trials or windows) is given in every caption. Chance level is 50% for every two-way decision. Each figure's plotted values are "
    "also saved as a CSV next to the PNG in figures/.")

FIG_HOWTO = {
    "a1_qc_metric_distributions":
        "Each small panel is one quality metric; its title says which, and 'log10' means the axis is logarithmic (each unit = 10x). "
        "Each column of dots is a dataset (one dot per trial); the shaded shape (violin) shows where trials cluster and the black bar is "
        "the median. Look for datasets whose cloud sits far from the others: e.g. median_rms_sd near 0 (log10 of 1) for KUL-AV-GC and "
        "KUL2016 means no DC offset, while DTU, KUL-UHD and USTC sit at 50-200x; median_abs_dc tells the same story.",
    "a2_psd_median_iqr":
        "Power spectrum of the raw EEG: x = frequency (Hz), y = power, both on log scales. The line is the median trial of a dataset and "
        "the shaded band covers the middle 50% of trials. What to see: the red line (KUL-AV-GC) collapses below 1 Hz and above ~40 Hz "
        "(it was filtered before release); the bump near 10 Hz is the alpha rhythm (strongest in KUL2016); the sharp spike at 50 Hz is "
        "mains noise (KUL-UHD, USTC); the other datasets keep large power below 1 Hz because they were never high-passed.",
    "a3_bad_channel_topography":
        "Each disc is a head seen from above (nose at the top, left ear on the left); dots are electrodes. The colour shows in what "
        "share of trials that electrode was flagged bad (white = never, dark red = often). Each panel has its own colour scale "
        "(see its colour bar), so compare patterns rather than colours across panels. KUL-UHD is drawn as dots on its 253-channel layout. "
        "Clusters at the edge (e.g. frontal USTC, temporal DTU) point to poor electrode contact.",
    "a4_edge_transients":
        "Bars give the share of trials with a large jump (> 20 robust SD) within 0.5 s of the trial start (solid) or end (faded). "
        "A value of 1.0 means every trial. KUL-UHD and USTC reach 100%: every one of their trials needs the edges trimmed or the filters "
        "warmed up before use.",
    "b4_env_sd_ratio":
        "Each dot is one trial: the loudness (SD) of the attended envelope divided by that of the ignored one, on a log2 scale. 0 = equally "
        "loud, +1 = attended twice as loud, -1 = half as loud. The black bar is the median. A cloud shifted above 0 (KUL2016) means the "
        "attended talker is systematically louder - a shortcut. Dots lined up in horizontal rows are the same stimulus pair reused across "
        "subjects (KUL2016 has only 12 distinct rows).",
    "b7_env_modspec":
        "How fast the speech loudness fluctuates: x = modulation frequency (Hz), y = relative power, log scales. Curves on top of each "
        "other mean the envelopes were extracted the same way. KUL-AV-GC (red) drops sharply below 1 Hz (its envelopes were high-passed); "
        "USTC (orange) has a bump at 4-5 Hz, the syllable rate of Mandarin, and a different shape - a different envelope extraction.",
    "c1_tracking_curves":
        "How strongly the EEG follows the speech envelope at each delay. x = delay in ms (positive = EEG after the sound), y = correlation "
        "strength averaged over the 57 channels (RMS). Solid = attended talker, dashed = ignored talker; the band covers the middle 50% of "
        "subjects. A peak at 100-200 ms is the brain's response to the speech; the gap between solid and dashed at the peak is the "
        "attention effect every decoder relies on. It is visible in all five datasets but small (correlations around 0.01-0.02).",
    "c1_topographies":
        "Head maps (nose up) of the envelope-EEG correlation at each dataset's peak delay. Rows: attended talker, ignored talker, and their "
        "difference. Red = positive, blue = negative correlation; within a column the three maps share one colour scale. Where the "
        "attended map is stronger than the ignored one (strong colour in the bottom row) is where attention information lives - mostly "
        "central/frontal and temporal electrodes.",
    "c1_forward_trf_gfp":
        "The forward model (temporal response function): how the EEG responds over time to the speech envelope. x = delay (ms), y = response "
        "strength summed over channels (global field power). Solid = attended, dashed = ignored. Peaks between roughly 100 and 250 ms are "
        "the auditory response; a higher solid curve means attended speech drives the brain more strongly.",
    "c4_accuracy_vs_window":
        "Decoding accuracy (y) against the length of the decision window in seconds (x, log scale), for three validation schemes: within "
        "subject (left), new subject from the same dataset (middle) and new dataset (right). Points are the median over subjects, bars the "
        "95% CI; the grey line is chance (0.5). All curves rise with window length (more data per decision = fewer errors). The right "
        "panel is the realistic one for the challenge: about 53-56% at 1 s and 56-67% at 10 s. DTU has no 60-s point because its trials "
        "are only 48 s long after trimming.",
    "c4_snr_law":
        "Test of the SNR law. Each dot is one subject at one window length; x = the accuracy predicted from that subject's 1-s SNR alone, "
        "y = the accuracy actually measured. Dots on the dashed diagonal mean the prediction is exact. The legend gives the fitted k per "
        "dataset (1 = consecutive seconds independent; below 1 = they are correlated, so longer windows help slightly less than ideal).",
    "d1_embedding":
        "Each dot is one 5-s EEG segment, placed by the two main directions of variation of its spatial covariance (axes have no units). "
        "Colour = dataset. Four panels: no alignment, scale-normalised, Euclidean alignment, causal running alignment; the title gives how "
        "accurately a classifier can tell the dataset. Separate coloured islands mean each dataset has its own 'fingerprint'; the more the "
        "colours mix after alignment, the more the alignment removed it. They mix only partly (84-87% still identifiable).",
    "d4_switch_locked":
        "Signals averaged around the 99 real KUL-AV-GC side switches: x = time from the switch (s; 0 = switch), y = signal level, flipped "
        "so that a left-to-right switch would push the curve upward. Left: alpha lateralisation; middle: eye-movement proxy from frontal "
        "electrodes; right: the recorded EOG channels. A physiological marker of the switch would appear as a step at 0. The curves stay "
        "flat (the band is the 95% CI), so no marker was found.",
    "e1_tradeoff_c19-common57-car_lodo_pool_0-500ms":
        "The accuracy-versus-reaction trade-off, one panel per held-out dataset. x = Acc (% of samples correct), y = L (switch-detection "
        "score, 1 = instant). Each coloured marker is one integrator setting (marker shape = family: circle argmax, square moving average, "
        "triangles HMM, diamond ladder); grey markers are the same settings fed with random evidence (the null). The curved grey lines "
        "are iso-H lines: every point on a line has the same headline score H, labelled on the line. Better = up and to the right. "
        "The coloured cloud sits clearly above the grey null, but far below the dotted oracle line - there is room to improve.",
}

TAB_HOWTO = {
    1: "One row per dataset. 'Distinct audio' counts different speech recordings found by comparing envelopes, not file names - a small "
       "number means the same stories are reused across trials and subjects. 'EOG channels' says whether eye-movement electrodes were stored.",
    2: "One row per dataset; values are medians over subjects. Compare a column down the rows: SD and |DC| show the amplitude scale and "
       "offset (large = raw, unfiltered data); RMS/SD = 1 means no offset; 50 Hz ratio > 1 means mains noise, < 1 a notch filter; "
       "sub-1 Hz ratio < 1 means the data were high-passed; the last three columns are the share of problematic trials or channels.",
    3: "The processing each dataset most likely received before release, inferred from the spectra. Read across a row to get one "
       "dataset's history; datasets with different rows need harmonised preprocessing before pooling.",
    4: "Counts from the per-sample ground-truth labels. 'Within-trial speaker switches' is 0 everywhere; only KUL-AV-GC has direction "
       "switches. 'Direction samples mislabelled' is the share of samples where the single trial-level label is wrong (50% in KUL-AV-GC "
       "because the side changes half way).",
    5: "Two competing explanations of the KUL-AV-GC 5-min event, tested by decoding. Each cell is the accuracy expected if that "
       "explanation were true. The 'same speaker all trial' column rises with window length (84% at 60 s) while the other falls far "
       "below 50%, so the speaker did not change.",
    6: "'col0 SD > col1 SD' is the share of trials where the attended envelope is louder (50% = no bias). The p-values test whether "
       "that share differs from 50%. The last column shows how well a classifier picks the attended talker from loudness statistics "
       "alone - anything clearly above 50% is a shortcut (KUL2016: 82.5%).",
    7: "'Label vs trial parity agreement' of 100% means the attended side can be read off whether the trial number is odd or even. The "
       "two classifier columns show how well slow drift alone predicts the label (50% = no information).",
    8: "How many different recordings of speech exist per dataset, found from the envelopes themselves. 'Audio clusters with several "
       "names' > 0 means one recording appears under different file names - so file names cannot be trusted to build story-disjoint "
       "folds.",
    9: "For each dataset, how often a decoder that never saw the trial prefers column 1 (the stream marked 'ignored'). Well below 50% "
       "means the columns are labelled correctly; a swap would push it above 50%.",
    10: "Size and timing of neural tracking per dataset: the delay of the peak (ms), the correlation strength for attended and ignored "
        "speech, their difference with CI, and a p-value testing that attended > ignored across subjects. All p-values are small, so "
        "the attention effect is present everywhere.",
    11: "Accuracy (%) for the three validation schemes (rows) at 1, 10 and 60-s windows, per dataset (columns). Compare down a column to "
        "see the cost of generalising: within subject > new subject > new dataset. Brackets are 95% CIs over subjects.",
    12: "SNR1 per scheme (rows) and dataset (columns). Higher = stronger evidence per second. The three 'lodo' rows are different ways of "
        "pooling training data; they are almost identical. Compare with 0.099, the value implied by the official baseline.",
    13: "Each row is one change to the preprocessing, compared with the first row (reference). The number is the median accuracy; in "
        "brackets the median change vs the reference in percentage points and its p-value. Negative changes mean the variant is worse. "
        "Nothing beats the causal reference with a significant margin except, marginally, the 0.5-30 Hz variant at 10 s.",
    14: "How well a classifier can tell which dataset (or which subject) a 5-s EEG segment came from. Rows: without and with alignment. "
        "Chance for dataset ID is 31% (always guessing the largest dataset). Values near 100% mean a strong fingerprint; alignment lowers "
        "it only to 84-87%.",
    15: "Direction (left/right) decoding with spatial filters. Read along a row from left to right: the leaky within-trial split is "
        "highest, then accuracy falls as training and test data get further apart (held-out trial, new subject, new dataset). The "
        "last column shows the same features identifying the trial itself - far above chance - which is what inflates the first column.",
    16: "Does brain or eye activity differ between attending right and left? d is the effect size per subject (median, 95% CI); "
        "'share positive' is the share of subjects with d > 0; q is the p-value corrected for all tests in the table. Only USTC's eye "
        "channel (eog0) shows a clear effect.",
    17: "The change from 60 s before to 60 s after each real KUL-AV-GC switch (median over subjects, 95% CI) and its p-value. Values "
        "near 0 with large p mean nothing changes at the switch.",
    18: "How the allowed 1-s lookahead is spent: the decoder looks 500 ms into the future of each sample, and decisions are used 500 ms "
        "earlier than the end of their window. The total must not exceed 1,000 ms.",
    19: "Switch-detection scores per held-out dataset for the best integrator. Acc, SDT (seconds to detect), L and H are the official "
        "metrics; 'miss rate' = share of switches never detected. The 'null' columns are the same pipeline with random evidence, i.e. "
        "the floor. 'Oracle misses' counts switches that even a perfect decoder loses because of the scorer's 50-s property.",
    20: "The best H each integrator family reaches on each held-out dataset. Compare down a column: smoothing integrators (moving "
        "average, HMM) beat plain argmax by 0.02-0.07 H.",
    21: "One row per hypothesis: what it claims, why it matters for the challenge and how it was tested here.",
    22: "One row per hypothesis: the claim, the verdict (colour-coded in the key above) and a plain-language summary of the evidence.",
    23: "The same verdicts with the full numbers: the previous (single-trial) estimate next to the full-corpus estimate, and the sample "
        "size n behind it.",
}
