Honor the download-flag contract across all datasets and harden the NEMAR sourcedata path

[bruAristimunha]

What

Two related fix-sets, landed together because they share the same download layer (datasets/base.py, datasets/download.py):

1. The download-flag contract — enforced for every dataset

An AST audit of every data_path implementation found flags accepted but silently ignored across the catalogue:

• CacheConfig.overwrite_* was a no-op with the default use=False — get_data(cache_config=dict(overwrite_raw=True)) erased nothing. The docstring also claimed save_* was ignored in that case while the code honored it. Overwrite now always erases; docs match behavior.
• CompoundDataset.data_path dropped all four flags when delegating to the wrapped dataset.
• 22 dataset data_path implementations ignored path and/or force_update (full list in the commit message) — including every recent dataset that resolved its storage dir via get_dataset_path(SIGN, None) with the user's path hardcoded away.
• Kojima2024a/b narrowed the data_path signature to (subject, path), so BaseDataset.download() raised TypeError: unexpected keyword argument 'force_update'.
• force_update now also re-extracts stale archives; download_if_missing gains a force_update parameter as the choke point for the manifest-based datasets (dreyer2023, erpcore2021, kojima2024a/b, mainsah2025).
• update_path is left as documented-deprecated (download.py: "Unused, kept for compatibility purpose").

Guard rails: a new AST regression test fails CI if any dataset's data_path ever ignores path or force_update again (exempt: the abstract base and FakeDataset), and a new cache test proves overwrite_raw=True, use=False actually erases.

2. NEMAR sourcedata hardening (follow-ups to #1139)

• Per-subject upstream fallback: one failing subject no longer discards the whole NEMAR batch — only the failed subjects fall back to data_path, keeping what NEMAR already served. The now-unused batch helper _download_nemar_sourcedata is removed.
• sourcedata_path resolves subjects through nemar_subject_template, matching the sibling BIDS path (_download_nemar). Datasets like ErpCore2021 ({subject:03d}) previously sent the raw int to the provenance matcher.
• Honest error taxonomy: only SelectionError maps to "deposit publishes no sourcedata"; transport/verification/S3 failures now report as download failures with the original error text.
• Glob safety: manifest filenames are glob.escaped before being used as nemar include patterns and local verification globs, so upstream names containing [ ] * ? still match.
• Docs: the changelog's nemar_sourcedata_include attribute (never implemented) is replaced with the real provenance mechanism; nemar_dl/nemar_sourcedata_dl are registered in api.rst; docstrings no longer promise a NemarDownloadError for a missing nemar-py (that raises ImportError at import time).
• Direct tests for set_download_provider/get_download_provider (previously only exercised through monkeypatched seams): validation, case normalization, None reset, env-var precedence, unknown-value fallback — using the isolated MNE config fixture so nothing touches the real ~/.mne config.

Not in scope (deliberate, candidates for follow-ups)

• A per-call provider= override / context manager instead of the persisted global (set_download_provider still writes the MNE config).
• Lazy import nemar (today import moabb requires nemar-py even with provider="upstream").
• Wiring the NEMAR sourcedata cache into data_path/get_data so a prefetch warms the evaluation path — needs a design decision on cache-location mapping.
• verbose in the pooch-based downloaders (progress bars are hardcoded; no slot to honor it).

Test plan

• pytest moabb/tests/test_download.py moabb/tests/test_datasets.py -k 'not doi' → 1464 passed
• pytest moabb/tests/test_paradigms.py → 102 passed; pytest moabb/tests/test_evaluations.py → 93 passed
• AST audit sweep → every dataset honors path + force_update
• pre-commit run --all-files → clean

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[bruAristimunha]

Follow-up push (bd7c95c) after verifying against live NEMAR deposits:

• Fetched the real sourcedata_provenance.json for nm000266 (Sosulski2019) and nm000221 (Cattan2019/alphawaves): both key subjects by the raw MOABB id ("1", "10", …). nm000132 (ErpCore2021) publishes no sourcedata at all, and on004362 (PhysionetMI) has no provenance manifest — so neither templated dataset can exercise the sourcedata path today.
• Consequence: sourcedata_path no longer bets on one convention. It now passes the raw id and the nemar_subject_template label as aliases, and _sourcedata_files_for_subject matches either. Works with today's raw-id manifests and with template-labelled ones if enrichment ever produces them.
• Also fixed while in there: a missing sourcedata_provenance.json (SelectionError) is now reported as "publishes no sourcedata manifest" instead of the generic "could not read", transport failures fetching the manifest carry the original error text, and manifest entries without a file key are skipped instead of raising KeyError.
• New tests: alias matching against both manifest conventions (including a glob-metachar filename), and the template-alias plumbing through sourcedata_path.

Still deliberately open (needs a design decision): wiring the NEMAR sourcedata cache into data_path/get_data, per-call provider= override, lazy import nemar.

[bruAristimunha]

Third commit (3627d8d): ERP CORE combined-layout fix.

The reader was built for the original distribution where every component was its own standalone BIDS dataset (seven MNE-erpcore{task}2021-data roots, each with its own MNE config sign keyed by the task name). ERP CORE is one BIDS dataset whose components are separated by the task- entity — the same shape the NEMAR deposit nm000132 publishes (tasks=[MMN,N170,N2pc,N400,P3,flankers]).

• All seven classes now share a single MNE-erpcore2021-data root under one ERPCORE2021 sign; BIDSPath(task=...) already selected per component, so the load path is unchanged apart from reading the shared root. Per-component filenames carry their task, so nothing collides when the trees merge.
• A pre-existing download in the legacy separated layout is detected per subject and read as-is — no forced re-download for anyone who already has the seven folders.
• Two offline tests pin it: both components resolve to the same root with the component prefix stripped, and the legacy fallback triggers without fetching.

A side benefit: the local layout now mirrors nm000132's combined BIDS tree one-to-one, which makes eventually wiring the NEMAR BIDS copy into this reader a root-swap rather than a restructure.

[bruAristimunha]

Fourth commit (833afc5): the layout audit found one more family with ERP CORE's disease — Dreyer2023.

Systematic sweep: grouped every dataset class by NEMAR deposit and scanned every multi-class module for per-self.code storage of a single source. Two families shared one deposit across classes: nm000132 (ErpCore2021 ×7, fixed in the previous commit) and nm000250 (Dreyer2023 A/B/C + combined) — four classes reading one globally numbered dataset (one OSF manifest keyed by sub-NN.zip) but each storing into its own MNE-Dreyer2023{X}-data folder, i.e. up to four copies of the same files.

• All four classes now share MNE-dreyer2023-data under one Dreyer2023 sign; A/B/C just select their subject ranges (sub-01..60 / 61..81 / 82..87), which coexist in one root with no collisions.
• Legacy per-class downloads are detected per subject and read as-is — no forced re-fetch.
• get_subject_info (performance.csv) moves to the shared root as well.
• Tests: A and B resolve to the same root with real zip extraction exercised; the legacy fallback triggers without downloading.

Everything else checked clean: Shin2017, BEETL and Huebner already share a root; Lee2019, Kojima2024, MAMEM and BrainInvaders classes fetch genuinely distinct deposits, so their per-code folders are correct. Full suites: 1470 passed, pre-commit clean.

[bruAristimunha]

Coverage verification, per class rather than per file, since most of MOABB's 167 registered dataset classes (161 regular + 6 compound) inherit a shared data_path:

• Resolved every registered class to the actual data_path definition it executes (96 distinct definitions) and audited each for path/force_update usage.
• On this branch: 165 compliant + 2 exempt (FakeDataset variants) = 0 violations.
• Same audit against the pre-PR state: 64 violating classes (the per-implementation fixes fan out — e.g. one mainsah2025.py fix covers its 21 registered classes, the compound-dataset fix covers all *_Il classes).

The file-based AST regression test in test_datasets.py subsumes the per-class view (every definition a class can resolve to lives in the swept files), so this stays enforced.

On "why not all datasets" for the NEMAR side: 73 of 161 classes declare a nemar_id today. The remaining ones have no public NEMAR deposit to point at — that is a data-publication task on the NEMAR side (as in #1145, which flipped 15 datasets the moment their deposits went public), not a code change this PR can make.

[bruAristimunha]

Correction to my previous comment: the "73 of 161 classes declare a nemar_id" figure was wrong — that grep only matched nm-prefixed, single-line declarations in top-level dataset files.

Counted properly at class level (resolved cls.nemar_id for every registered class, base default is None): 156 of 161 classes declare a nemar_id (prefixes nm, on, ds). The only ones without: FakeDataset / FakeVirtualRealityDataset (nothing to download) and three 2026 additions whose deposits aren't up yet (Lenaig2026, Schrag2026Pediatric, Wang2026).

This changes the weight of the open wiring question: NEMAR coverage is nearly universal, so set_download_provider only affecting download() (and never get_data) is a gap for essentially the whole catalog, not half of it. Worth prioritizing in the NeuroAI discussion.