#!/usr/bin/env python3
"""Full-corpus EDA for the SuperHuge raw EEG/envelope representation.

Streams trials from .npy memmaps so the 26-GB corpus does not need to fit in RAM.
Outputs CSV tables, PNG figures and a Markdown report beside this script.
"""

from __future__ import annotations

import csv
import pickle
from collections import Counter, defaultdict
from pathlib import Path

import matplotlib

matplotlib.use("Agg")
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd


ROOT = Path("/root/disk_3tb/EEG-sAAD-Grand-Challenge-Training-Dataset")
RAW = ROOT / "data/superhuge/raw"
OUT = ROOT / "reports/eda_raw"
RNG = np.random.default_rng(20260924)
CHUNK = 8192
TRACE_SECONDS = 10


def channel_names(meta: dict) -> list[str]:
    info = meta.get("channel_infos") or {}
    return [str(info[k].get("name", f"ch{k}")) for k in sorted(info)]


def finite_summary(x: np.ndarray) -> dict[str, float | int]:
    finite = np.asarray(x)[np.isfinite(x)]
    if finite.size == 0:
        return {"n_finite": 0, "mean": np.nan, "std": np.nan, "min": np.nan,
                "q01": np.nan, "median": np.nan, "q99": np.nan, "max": np.nan}
    q = np.quantile(finite, [0.01, 0.5, 0.99])
    return {"n_finite": int(finite.size), "mean": float(finite.mean()),
            "std": float(finite.std()), "min": float(finite.min()),
            "q01": float(q[0]), "median": float(q[1]), "q99": float(q[2]),
            "max": float(finite.max())}


def savefig(fig: plt.Figure, name: str) -> None:
    fig.savefig(OUT / name, dpi=160, bbox_inches="tight")
    plt.close(fig)


def analyze() -> None:
    OUT.mkdir(parents=True, exist_ok=True)
    meta_path = RAW / "meta/metadata.pkl"
    with meta_path.open("rb") as f:
        raw_meta: dict[str, dict] = pickle.load(f)

    trial_rows: list[dict] = []
    env_rows: list[dict] = []
    channel_acc: dict[tuple[int, str], dict] = {}
    dataset_names: dict[int, str] = {}
    sampled_eeg: dict[int, list[np.ndarray]] = defaultdict(list)
    sampled_env: dict[int, list[np.ndarray]] = defaultdict(list)
    trace_candidates: dict[int, tuple[str, np.ndarray, np.ndarray, dict]] = {}
    issues: list[dict] = []

    # Parse deterministic dataset names and process trials in canonical order.
    entries = sorted(raw_meta.items())
    for entry, m in entries:
        did = int(m["dataset_id"])
        sid, tid = int(m["subject_id"]), int(m["trial_id"])
        name = str(m.get("dataset_name", f"dataset-{did:03d}"))
        dataset_names[did] = name
        fs = float(m.get("fs", np.nan))
        n_meta = int(m.get("signal_length", -1))
        eeg_path = RAW / "eeg" / f"{entry}.npy"
        env_path = RAW / "stimuli/env" / f"{entry}_env.npy"
        row = {"entry": entry, "dataset_id": did, "dataset_name": name,
               "subject_id": sid, "trial_id": tid, "fs_hz": fs,
               "signal_length_metadata": n_meta,
               "duration_seconds_metadata": n_meta / fs if fs > 0 else np.nan,
               "num_channels_metadata": int(m.get("num_channel", -1)),
               "num_speakers_metadata": int(m.get("num_speakers", -1)),
               "trial_label": m.get("label", None),
               "env_available": bool(m.get("env", 0)),
               "channel_names": "|".join(channel_names(m)),
               "eeg_file_exists": eeg_path.is_file(),
               "env_file_exists": env_path.is_file()}
        if not eeg_path.is_file() or not env_path.is_file():
            issues.append({"entry": entry, "issue": "missing EEG or envelope file"})
            trial_rows.append(row)
            continue

        eeg = np.load(eeg_path, mmap_mode="r", allow_pickle=False)
        env = np.load(env_path, mmap_mode="r", allow_pickle=False)
        row.update({"eeg_shape": str(tuple(eeg.shape)), "eeg_dtype": str(eeg.dtype),
                    "env_shape": str(tuple(env.shape)), "env_dtype": str(env.dtype),
                    "eeg_order_f": bool(eeg.flags.f_contiguous),
                    "eeg_order_c": bool(eeg.flags.c_contiguous)})
        if eeg.ndim != 2 or env.ndim != 3:
            issues.append({"entry": entry, "issue": f"unexpected dimensions EEG={eeg.shape}, env={env.shape}"})
            trial_rows.append(row)
            continue
        n, c = eeg.shape
        k = env.shape[-1]
        row["signal_length_actual"] = int(n)
        row["duration_seconds_actual"] = n / fs if fs > 0 else np.nan
        row["num_channels_actual"] = int(c)
        row["num_envelope_streams_actual"] = int(k)
        row["length_matches_metadata"] = n == n_meta
        row["channels_match_metadata"] = c == row["num_channels_metadata"]
        row["env_time_matches_eeg"] = env.shape[0] == n
        row["env_feature_axis"] = int(env.shape[1])
        if not row["length_matches_metadata"]:
            issues.append({"entry": entry, "issue": f"EEG length {n} != metadata {n_meta}"})
        if c != len(channel_names(m)):
            issues.append({"entry": entry, "issue": f"channel count {c} != channel metadata {len(channel_names(m))}"})
        if env.shape[0] != n:
            issues.append({"entry": entry, "issue": f"envelope length {env.shape[0]} != EEG length {n}"})

        names = channel_names(m)
        if len(names) != c:
            names = [f"ch{i+1:03d}" for i in range(c)]
        finite_n = np.zeros(c, dtype=np.int64)
        nan_n = np.zeros(c, dtype=np.int64)
        sums = np.zeros(c, dtype=np.float64)
        sums_sq = np.zeros(c, dtype=np.float64)
        minv = np.full(c, np.inf)
        maxv = np.full(c, -np.inf)
        absmax = np.zeros(c, dtype=np.float64)
        # Reservoir-like deterministic sampling: select up to 64 random rows/trial.
        take = min(64, n)
        sample_idx = np.sort(RNG.choice(n, size=take, replace=False))
        sampled_eeg[did].append(np.asarray(eeg[sample_idx], dtype=np.float32).ravel())
        env_flat_sample = np.asarray(env[sample_idx, 0, :], dtype=np.float32).ravel()
        sampled_env[did].append(env_flat_sample)

        # Whole-trial EEG/channel stats; memmap slices cap peak working memory.
        for start in range(0, n, CHUNK):
            block = np.asarray(eeg[start:start + CHUNK], dtype=np.float64)
            finite = np.isfinite(block)
            finite_n += finite.sum(axis=0)
            nan_n += (~finite).sum(axis=0)
            safe = np.where(finite, block, 0.0)
            sums += safe.sum(axis=0)
            sums_sq += np.square(safe).sum(axis=0)
            minv = np.minimum(minv, np.where(finite, block, np.inf).min(axis=0))
            maxv = np.maximum(maxv, np.where(finite, block, -np.inf).max(axis=0))
            absmax = np.maximum(absmax, np.where(finite, np.abs(block), 0.0).max(axis=0))
        denom = np.maximum(finite_n, 1)
        means = sums / denom
        stds = np.sqrt(np.maximum(sums_sq / denom - means * means, 0))
        for ci, ch in enumerate(names):
            key = (did, ch)
            a = channel_acc.setdefault(key, {"sum": 0.0, "sums_sq": 0.0, "n": 0,
                                             "min": np.inf, "max": -np.inf,
                                             "absmax": 0.0, "nan": 0})
            a["sum"] += float(sums[ci]); a["sums_sq"] += float(sums_sq[ci])
            a["n"] += int(finite_n[ci]); a["nan"] += int(nan_n[ci])
            a["min"] = min(a["min"], float(minv[ci]))
            a["max"] = max(a["max"], float(maxv[ci]))
            a["absmax"] = max(a["absmax"], float(absmax[ci]))
        row["eeg_nonfinite_values"] = int(nan_n.sum())
        row["eeg_nonfinite_pct"] = float(100 * nan_n.sum() / (n * c))
        row["eeg_mean_over_channels"] = float(means.mean())
        row["eeg_median_channel_std"] = float(np.median(stds))
        row["eeg_median_channel_rms"] = float(np.median(np.sqrt(sums_sq / denom)))
        row["eeg_max_abs"] = float(absmax.max())

        e = np.asarray(env, dtype=np.float64)  # at most two streams, still memmap-backed input
        env_nonfinite = int((~np.isfinite(e)).sum())
        row["env_nonfinite_values"] = env_nonfinite
        row["env_nonfinite_pct"] = float(100 * env_nonfinite / e.size)
        row["env_dtype"] = str(env.dtype)
        env_stream_stats = []
        for stream in range(k):
            vals = np.asarray(env[:, 0, stream], dtype=np.float64)
            st = finite_summary(vals)
            env_stream_stats.append(st)
            env_rows.append({"entry": entry, "dataset_id": did, "dataset_name": name,
                             "subject_id": sid, "trial_id": tid, "stream_index_0based": stream,
                             "convention_note": "converter places majority-attended stream in column 0",
                             "fs_hz": fs, **st})
        if k >= 2:
            x, y = np.asarray(env[:, 0, 0], dtype=np.float64), np.asarray(env[:, 0, 1], dtype=np.float64)
            ok = np.isfinite(x) & np.isfinite(y)
            corr = float(np.corrcoef(x[ok], y[ok])[0, 1]) if ok.sum() > 1 else np.nan
            row["env_stream_corr"] = corr
        else:
            row["env_stream_corr"] = np.nan
        row["env_stream0_mean"] = env_stream_stats[0]["mean"] if k else np.nan
        row["env_stream1_mean"] = env_stream_stats[1]["mean"] if k > 1 else np.nan
        if did not in trace_candidates and n >= int(fs * TRACE_SECONDS):
            trace_candidates[did] = (entry, np.asarray(eeg[:int(fs * TRACE_SECONDS), :min(c, 4)], dtype=np.float32),
                                     np.asarray(env[:int(fs * TRACE_SECONDS), 0, :], dtype=np.float32), m)
        trial_rows.append(row)

    trials = pd.DataFrame(trial_rows)
    env_table = pd.DataFrame(env_rows)
    trial_ok = trials[trials.get("eeg_file_exists", False) & trials.get("env_file_exists", False)].copy()
    trial_ok["trial_label"] = trial_ok["trial_label"].fillna("(missing)").astype(str)

    # Dataset-level descriptive summary.
    summary_rows = []
    for did, g in trial_ok.groupby("dataset_id", sort=True):
        summary_rows.append({
            "dataset_id": int(did), "dataset_name": dataset_names.get(int(did), ""),
            "subjects": int(g["subject_id"].nunique()), "trials": int(len(g)),
            "total_hours": float(g["duration_seconds_actual"].sum() / 3600),
            "sampling_rates_hz": ",".join(map(str, sorted(g["fs_hz"].dropna().unique()))),
            "channel_counts": ",".join(map(str, sorted(g["num_channels_actual"].dropna().unique()))),
            "trial_duration_s_min": float(g["duration_seconds_actual"].min()),
            "trial_duration_s_median": float(g["duration_seconds_actual"].median()),
            "trial_duration_s_max": float(g["duration_seconds_actual"].max()),
            "eeg_nonfinite_trials": int((g["eeg_nonfinite_values"] > 0).sum()),
            "env_nonfinite_trials": int((g["env_nonfinite_values"] > 0).sum()),
            "trial_labels": "; ".join(f"{k}:{v}" for k, v in g["trial_label"].value_counts(dropna=False).sort_index().items()),
            "env_stream_corr_median": float(g["env_stream_corr"].median()),
            "eeg_median_channel_std_median": float(g["eeg_median_channel_std"].median()),
            "eeg_median_channel_rms_median": float(g["eeg_median_channel_rms"].median()),
        })
    ds = pd.DataFrame(summary_rows)

    # Channel statistics pooled across every sample within dataset/channel.
    chan_rows = []
    for (did, ch), a in sorted(channel_acc.items()):
        n = max(int(a["n"]), 1)
        mean = a["sum"] / n
        std = np.sqrt(max(a["sums_sq"] / n - mean * mean, 0))
        chan_rows.append({"dataset_id": did, "dataset_name": dataset_names[did],
                          "channel": ch, "finite_samples": a["n"],
                          "nonfinite_samples": a["nan"], "mean": mean,
                          "std": std, "min": a["min"], "max": a["max"],
                          "max_abs": a["absmax"], "rms": np.sqrt(a["sums_sq"] / n)})
    channels = pd.DataFrame(chan_rows)

    # Per-subject trial and duration coverage.
    subjects = (trial_ok.groupby(["dataset_id", "dataset_name", "subject_id"], as_index=False)
                .agg(trials=("trial_id", "count"), duration_hours=("duration_seconds_actual", lambda x: x.sum()/3600),
                     trial_duration_median_s=("duration_seconds_actual", "median"),
                     eeg_nonfinite_trials=("eeg_nonfinite_values", lambda x: int((x > 0).sum()))))

    # Save machine-readable tables.
    ds.to_csv(OUT / "dataset_summary.csv", index=False)
    trials.to_csv(OUT / "trial_inventory.csv", index=False)
    subjects.to_csv(OUT / "subject_summary.csv", index=False)
    channels.to_csv(OUT / "channel_signal_summary.csv", index=False)
    env_table.to_csv(OUT / "envelope_summary_by_trial_stream.csv", index=False)
    pd.DataFrame(issues, columns=["entry", "issue"]).to_csv(OUT / "data_integrity_issues.csv", index=False)

    # Figure 1: corpus size, subjects and duration.
    fig, axes = plt.subplots(1, 3, figsize=(16, 5))
    colors = plt.cm.tab10(np.linspace(0, 1, len(ds)))
    labels = ds["dataset_name"].str.replace("_raw", "", regex=False)
    axes[0].bar(labels, ds["trials"], color=colors); axes[0].set_title("Trials"); axes[0].tick_params(axis="x", rotation=55)
    axes[1].bar(labels, ds["subjects"], color=colors); axes[1].set_title("Subjects"); axes[1].tick_params(axis="x", rotation=55)
    axes[2].bar(labels, ds["total_hours"], color=colors); axes[2].set_title("Total recording hours"); axes[2].tick_params(axis="x", rotation=55)
    fig.suptitle("Raw SuperHuge corpus overview")
    savefig(fig, "01_corpus_overview.png")

    # Figure 2: distribution of trial duration by dataset.
    fig, ax = plt.subplots(figsize=(10, 5))
    order = [dataset_names[k].replace("_raw", "") for k in sorted(dataset_names)]
    data = [trial_ok.loc[trial_ok.dataset_id == did, "duration_seconds_actual"].to_numpy() for did in sorted(dataset_names)]
    ax.boxplot(data, labels=order, showfliers=False); ax.set_ylabel("Trial duration (seconds)"); ax.set_title("Trial duration by dataset")
    ax.tick_params(axis="x", rotation=25); ax.grid(axis="y", alpha=.25)
    savefig(fig, "02_trial_duration.png")

    # Figure 3: random sample amplitude distributions for EEG and envelopes.
    fig, axes = plt.subplots(1, 2, figsize=(14, 5))
    for did in sorted(dataset_names):
        eegv = np.concatenate(sampled_eeg[did]) if sampled_eeg[did] else np.array([])
        envv = np.concatenate(sampled_env[did]) if sampled_env[did] else np.array([])
        axes[0].hist(eegv[np.isfinite(eegv)], bins=100, density=True, histtype="step", linewidth=1.4, label=dataset_names[did].replace("_raw", ""))
        axes[1].hist(envv[np.isfinite(envv)], bins=100, density=True, histtype="step", linewidth=1.4, label=dataset_names[did].replace("_raw", ""))
    axes[0].set_title("EEG amplitude (uniform random time samples)"); axes[0].set_xlabel("Stored numeric value"); axes[0].set_ylabel("Density")
    axes[1].set_title("Envelope amplitude (both streams)"); axes[1].set_xlabel("Stored numeric value"); axes[1].set_ylabel("Density")
    for ax in axes: ax.legend(fontsize=8); ax.grid(alpha=.2)
    savefig(fig, "03_signal_distributions.png")

    # Figure 4: trial-level label balance.
    label_counts = trial_ok.groupby(["dataset_name", "trial_label"]).size().unstack(fill_value=0)
    label_counts = label_counts.reindex(sorted(dataset_names.values()))
    fig, ax = plt.subplots(figsize=(10, 5))
    label_counts.plot(kind="bar", stacked=True, ax=ax, colormap="Set2")
    ax.set_title("Trial-level metadata label counts"); ax.set_ylabel("Trials"); ax.set_xlabel(""); ax.tick_params(axis="x", rotation=25)
    ax.legend(title="label"); ax.grid(axis="y", alpha=.2)
    savefig(fig, "04_trial_label_counts.png")

    # Figure 5: per-dataset/channel RMS. Missing channels stay blank.
    pivot = channels.pivot(index="channel", columns="dataset_name", values="rms")
    fig, ax = plt.subplots(figsize=(12, max(7, 0.18 * len(pivot))))
    im = ax.imshow(np.log10(pivot.to_numpy()), aspect="auto", interpolation="nearest", cmap="magma")
    ax.set_yticks(np.arange(len(pivot))); ax.set_yticklabels(pivot.index, fontsize=6)
    ax.set_xticks(np.arange(len(pivot.columns))); ax.set_xticklabels([x.replace("_raw", "") for x in pivot.columns], rotation=30, ha="right")
    ax.set_title("log10 pooled EEG RMS by channel and dataset")
    fig.colorbar(im, ax=ax, label="log10 RMS (source numeric units)")
    savefig(fig, "05_channel_rms_heatmap.png")

    # Figure 6: example 10-s raw traces for each dataset, first 3 EEG channels + envelopes.
    fig, axes = plt.subplots(len(trace_candidates), 1, figsize=(14, 3.1 * len(trace_candidates)), squeeze=False)
    for ax, did in zip(axes[:, 0], sorted(trace_candidates)):
        entry, e_trace, v_trace, m = trace_candidates[did]
        fs = float(m["fs"]); t = np.arange(e_trace.shape[0]) / fs
        # Robust scale independently only for visualization; raw files stay untouched.
        for ci in range(min(3, e_trace.shape[1])):
            sig = e_trace[:, ci]
            med, mad = np.median(sig), np.median(np.abs(sig - np.median(sig))) + 1e-9
            ax.plot(t, (sig - med) / (1.4826 * mad), lw=.55, label=f"EEG {channel_names(m)[ci]}")
        for si in range(v_trace.shape[1]):
            sig = v_trace[:, si]
            sd = np.std(sig) + 1e-9
            ax.plot(t, (sig - np.mean(sig)) / sd, lw=.7, alpha=.8, label=f"env stream {si}")
        ax.set_title(f"{dataset_names[did]} | {entry} | first {TRACE_SECONDS}s (each trace standardized for display)")
        ax.set_ylabel("within-trace z-score"); ax.grid(alpha=.2); ax.legend(ncol=5, fontsize=7, loc="upper right")
    axes[-1, 0].set_xlabel("Time (s)")
    savefig(fig, "06_example_raw_traces.png")

    # Cohort-level diagnostic values for report.
    overall_hours = trial_ok["duration_seconds_actual"].sum() / 3600
    fs_values = sorted(trial_ok["fs_hz"].dropna().unique().tolist())
    ch_values = sorted(trial_ok["num_channels_actual"].dropna().unique().tolist())
    mismatches = int((~trial_ok["length_matches_metadata"].astype(bool)).sum())
    env_len_bad = int((~trial_ok["env_time_matches_eeg"].astype(bool)).sum())
    missing_files = int((~trials["eeg_file_exists"] | ~trials["env_file_exists"]).sum())
    bad_eeg = int((trial_ok["eeg_nonfinite_values"] > 0).sum())
    bad_env = int((trial_ok["env_nonfinite_values"] > 0).sum())
    labels = trial_ok["trial_label"].value_counts(dropna=False).to_dict()
    report = f'''# Raw EEG-sAAD dataset EDA

Generated from `{RAW}` on 2026-09-24 by `run_eda_raw.py`.

## Scope and method

This analysis scans the complete SuperHuge `raw` stage: metadata and all paired EEG/envelope `.npy` files. Signals are read by memory map in chunks; the analysis does not modify source data. Trial inventory and descriptive metrics are exact where calculated over all samples. Distribution plots use 64 reproducible random time points per trial. Example traces show the first 10 seconds of the first eligible trial per dataset and are standardized only for display.

## Corpus overview

- Metadata entries: **{len(raw_meta):,}**; paired usable trials: **{len(trial_ok):,}**.
- Subjects across dataset-specific IDs: **{trial_ok.groupby('dataset_id').apply(lambda x: x.subject_id.nunique()).sum():,}**.
- Total recording duration: **{overall_hours:,.1f} hours**.
- Sampling rates found: **{', '.join(f'{x:g} Hz' for x in fs_values)}**.
- Channel-count groups found: **{', '.join(map(str, ch_values))}**.
- Dataset trial-level labels: `{labels}`. These are metadata labels, not continuous attention-switch labels.

![Corpus overview](01_corpus_overview.png)

| Dataset | Subjects | Trials | Hours | Channels | fs | Trial duration median (s) | Label counts |
|---|---:|---:|---:|---|---|---:|---|
'''
    for _, r in ds.iterrows():
        report += (f"| {r.dataset_name} | {r.subjects} | {r.trials} | {r.total_hours:.1f} | "
                   f"{r.channel_counts} | {r.sampling_rates_hz} | {r.trial_duration_s_median:.1f} | {r.trial_labels} |\n")
    report += f'''
## Sampling, duration, and montage

![Trial duration](02_trial_duration.png)

The raw stage is already represented on its stored sample grid. The converter documents 128 Hz as the target for raw data; original recordings with another rate may have been resampled during CND preparation. This EDA reports actual metadata rates instead of assuming a common rate. EEG channel montage differs: the 64-channel datasets and the high-density dataset have separate channel-count groups. Channel names are preserved in metadata; compare `channel_signal_summary.csv` before pooling/mapping channels.

![Channel RMS](05_channel_rms_heatmap.png)

## Signal distributions and examples

![Signal distributions](03_signal_distributions.png)

EEG values are stored in the source numeric scale (the converter writes NumPy arrays from CND; this report does not infer physical units unless calibration metadata establishes them). Histograms are based on reproducible random samples across trials. Per-channel full-corpus mean, standard deviation, RMS and extrema are in `channel_signal_summary.csv`.

![Example traces](06_example_raw_traces.png)

The trace figure standardizes each displayed channel/envelope separately to show temporal shape. Use the CSV summaries for scale comparisons. Envelope files have time × feature × stream layout; inspect `envelope_summary_by_trial_stream.csv`. Per-trial correlation between the two envelopes is in `trial_inventory.csv`.

## Labels and task interpretation

The SuperHuge metadata `label` field is a trial-level category where available (often a direction/azimuth-derived left/right label). It does not provide a time-varying attention-switch sequence. The envelope tensor contains two concurrent streams; the converter convention places the majority-attended stream in column 0 and preserves the competing stream in column 1. For switch trials, that convention is trial-level and must not be mistaken for per-sample switch ground truth. Dataset/subject/trial IDs are organization keys and should not be used as predictive inputs in the blind evaluation.

![Trial metadata label counts](04_trial_label_counts.png)

## Integrity checks

- Missing paired EEG/envelope files: **{missing_files}**.
- EEG length differs from metadata: **{mismatches}**.
- Envelope time length differs from EEG: **{env_len_bad}**.
- Trials with any nonfinite EEG values: **{bad_eeg}**.
- Trials with any nonfinite envelope values: **{bad_env}**.
- Additional structural issues recorded: **{len(issues)}**.

See `data_integrity_issues.csv` for any flagged entries, and `trial_inventory.csv` for every trial's shape, duration, storage dtype/order, file pairing, finite-value counts and signal summaries.

## Files in this EDA folder

- `dataset_summary.csv`: dataset-level counts, durations, labels and signal summaries.
- `subject_summary.csv`: per-dataset/per-subject recording coverage.
- `trial_inventory.csv`: one row per trial with metadata, shape, quality and signal statistics.
- `channel_signal_summary.csv`: exact pooled channel statistics across samples.
- `envelope_summary_by_trial_stream.csv`: per-trial/per-stream envelope statistics.
- `data_integrity_issues.csv`: missing or structurally inconsistent data.
- `01_...png` through `06_...png`: overview, distributions and example plots.
- `run_eda_raw.py`: reproducible analysis script.

## Interpretation caveats

1. Numeric amplitude units and reference montage are not inferred from values alone; use each source dataset's acquisition documentation for physical interpretation.
2. Dataset IDs and subject IDs are assigned by the unified conversion and need not match original releases.
3. The trial-level `label` and envelope column ordering do not replace time-varying attended-speaker or attended-direction ground truth for switch detection.
4. This is a descriptive EDA, not a validation that the attention labels are behaviorally correct.
'''
    (OUT / "README.md").write_text(report, encoding="utf-8")
    print(f"EDA saved to {OUT}")
    print(ds.to_string(index=False))
    print(f"integrity: missing={missing_files}, length_mismatch={mismatches}, env_mismatch={env_len_bad}, nonfinite_eeg_trials={bad_eeg}, nonfinite_env_trials={bad_env}, issues={len(issues)}")


if __name__ == "__main__":
    analyze()
