Add Schrag2026Pediatric SSVEP dataset (n=47, ages 5-18)

[bruAristimunha]

Summary

Adds Schrag2026Pediatric — pediatric SSVEP-BCI dataset from Schrag et al. (2026) hosted on Zenodo (CC-BY-ND-4.0). 47 children (ages 5–18, 40.4% female) recorded at 256 Hz on 16 channels with the g.tec g.GAMMAsys + g.USBamp + g.GAMMAcap system, ground Fpz, earlobe reference.

Each subject contributes:

• Personalization (T1) — 12 visual stimuli (4 contrasts × 3 sizes), all flickering at 10 Hz, used by the original authors to pick a per-child personalized stimulus.
• SSVEP game (T2 + T3) — 4-target online game at 6.25 / 10 / 11.11 / 14.28 Hz, played twice (once with each subject's personal stimulus, once with a high-contrast standard) across two themed maps.

By default the loader exposes the SSVEP game runs only — two sessions per subject ("0standard", "1personal"), 5 s trials at four target frequencies. include_personalization=True also loads T1 as a third session ("2personalization"); all its trials carry the "10" event since every personalization stimulus flickers at 10 Hz.

Important caveat (also in the class docstring): trial labels for the game sessions come from the recorded fbCCA classifier output (the Selected SPO column of the per-game movement CSV) — i.e. the frequency the system identified during the live game, which then drove avatar movement. They are not ground-truth target frequencies. Treating y as such biases benchmarks toward fbCCA's behaviour. Trial-vs-CSV count drift is min-truncated when small (≤ 10 percent), otherwise the run's labels are dropped to avoid silent shifts.

Files

• moabb/datasets/schrag2026.py — new dataset class + helpers
• moabb/datasets/__init__.py — registration
• moabb/datasets/summary_ssvep.csv — summary row
• docs/source/api.rst — autosummary entry under SSVEP datasets
• docs/source/whats_new.rst — changelog entry

Implementation notes

• XDF + Unity markers via pyxdf (soft-imported). Modelled after aguilera_rodriguez2025.py (XDF) and kumar2024.py (single-zip Zenodo). Marker stream is selected by name (UnityMarkerStream) — each XDF also carries an empty gUSBamp-1Markers stream that wins a type-based match in some files.
• Single 1.2 GB DatasetData.zip is downloaded once and extracted per-subject on demand via safe_extract_zip(... members=...) so first-use latency stays in seconds for one-subject runs. Extraction is staged into a sibling temp dir then os.replace-d into place — race-safe under concurrent pytest workers.
• Demographics (_AGES, _SEXES) hardcoded from Participant_Demographic_Info.csv in the deposit; verified to match byte-for-byte.
• License set to CC-BY-ND-4.0 per the live Zenodo deposit (the preprint PDF says CC-BY-4.0; Zenodo metadata is authoritative for the data — comment in the source explains the discrepancy).

Cross-checks performed

• 31/31 metadata fields verified against (a) preprint PDF, (b) Participant_Demographic_Info.csv, (c) live Zenodo API.
• Loaded subjects 1, 2, 10, 20, 30, 40, 47 end-to-end. Trial counts 33–87 per session, all 4 SSVEP classes represented in each clean run.
• SSVEP paradigm round-trip on 5 clean subjects: X.shape=(428, 16, 1281), balanced classes {6.25: 119, 10: 116, 11.11: 95, 14.28: 98}.
• Post 7–45 Hz bandpass channel std ~15–34 µV (sane for pediatric EEG).
• Atomic _extract_subject verified idempotent; no temp leftovers after concurrent extraction races.
• P001 personal session has 15% trial-vs-CSV drift; the safeguard correctly drops labels with a clear log.error rather than silently shift them.

Style note

The class follows MOABB's existing BaseDataset shape but its module-level helpers (_load_xdf_streams, _read_unity_markers, _build_raw, _load_game_run, _load_personalization_run, _match_freq, _extract_subject) are deliberately flat / procedural and use the variable names (marker_ts, markers, eeg_stream, …) from the upstream Schrag / Comaduran reference notebooks (epoching-example.ipynb in the Zenodo deposit), so the original authors can read it top-to-bottom.

Test plan

• Lint clean (ruff check + ruff format)
• Module imports without side effects
• Schrag2026Pediatric() instantiates with 47 subjects, 4 events
• dataset_search(paradigm="ssvep", events=["10"]) finds it
• SSVEP paradigm round-trip on multiple subjects
• include_personalization=True loads T1 (40 trials per subject)
• sessions=["personal"] and sessions=["0standard"] filter correctly
• Atomic extraction is idempotent and race-safe
• CI: pytest, doc build (will be triggered by this PR)
• Authors confirm CC-BY-ND-4.0 vs CC-BY-4.0 license discrepancy

References

• Preprint: Schrag, E., Comaduran Marquez, D., Kirton, A., & Kinney-Lang, E. (2026). A steady-state visual evoked potential-based brain-computer interface dataset in children and adolescents. Research Square. https://doi.org/10.21203/rs.3.rs-9347306/v1
• Data: https://doi.org/10.5281/zenodo.19440997
• Original code: https://github.com/kirtonBCIlab/ES_Masters

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1446b3ff31

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve the downloader cache filename

Because the Zenodo API URL ends in /content, data_dl caches this archive at a path named content; renaming it to content.zip removes the exact file that data_dl checks on the next call. Since data_path() calls data_dl() before checking whether the subject was already extracted, any later access to an already-extracted subject will still re-download the full ~1.2 GB archive every time. Keep the cached path intact or download/cache under the final zip filename instead.

Useful? React with 👍 / 👎.