eegdash 0.3.6.dev182011805__py3-none-any.whl → 0.3.7.dev104__py3-none-any.whl

eegdash/__init__.py

@@ -1,10 +1,11 @@
 from .api import EEGDash, EEGDashDataset
 from .dataset import EEGChallengeDataset
+from .hbn import preprocessing  # noqa: F401
 from .utils import __init__mongo_client
 
 __init__mongo_client()
 
 
-__all__ = ["EEGDash", "EEGDashDataset", "EEGChallengeDataset"]
+__all__ = ["EEGDash", "EEGDashDataset", "EEGChallengeDataset", "preprocessing"]
 
-__version__ = "0.3.6.dev182011805"
+__version__ = "0.3.7.dev104"

eegdash/api.py

@@ -6,15 +6,18 @@ from typing import Any, Mapping
 
 import mne
 import numpy as np
+import platformdirs
 import xarray as xr
 from dotenv import load_dotenv
 from joblib import Parallel, delayed
+from mne.utils import warn
 from mne_bids import get_bids_path_from_fname, read_raw_bids
 from pymongo import InsertOne, UpdateOne
 from s3fs import S3FileSystem
 
 from braindecode.datasets import BaseConcatDataset
 
+from .const import RELEASE_TO_OPENNEURO_DATASET_MAP
 from .data_config import config as data_config
 from .data_utils import EEGBIDSDataset, EEGDashBaseDataset
 from .mongodb import MongoConnectionManager
@@ -693,9 +696,8 @@ class EEGDash:
 class EEGDashDataset(BaseConcatDataset):
     def __init__(
         self,
-        query: dict | None = None,
-        cache_dir: str = "~/eegdash_cache",
-        dataset: str | list[str] | None = None,
+        cache_dir: str | Path,
+        query: dict[str, Any] = None,
         description_fields: list[str] = [
             "subject",
             "session",
@@ -706,9 +708,10 @@ class EEGDashDataset(BaseConcatDataset):
             "sex",
         ],
         s3_bucket: str | None = None,
-        data_dir: str | None = None,
         eeg_dash_instance=None,
         records: list[dict] | None = None,
+        offline_mode: bool = False,
+        n_jobs: int = -1,
         **kwargs,
     ):
         """Create a new EEGDashDataset from a given query or local BIDS dataset directory
@@ -754,35 +757,54 @@ class EEGDashDataset(BaseConcatDataset):
         records : list[dict] | None
             Optional list of pre-fetched metadata records. If provided, the dataset is
             constructed directly from these records without querying MongoDB.
+        offline_mode : bool
+            If True, do not attempt to query MongoDB at all. This is useful if you want to
+            work with a local cache only, or if you are offline.
+        n_jobs : int
+            The number of jobs to run in parallel (default is -1, meaning using all processors).
         kwargs : dict
             Additional keyword arguments to be passed to the EEGDashBaseDataset
             constructor.
 
         """
-        self.cache_dir = cache_dir
+        self.cache_dir = Path(cache_dir or platformdirs.user_cache_dir("EEGDash"))
+        if not self.cache_dir.exists():
+            warn(f"Cache directory does not exist, creating it: {self.cache_dir}")
+            self.cache_dir.mkdir(exist_ok=True, parents=True)
         self.s3_bucket = s3_bucket
         self.eeg_dash = eeg_dash_instance
+
+        # Separate query kwargs from other kwargs passed to the BaseDataset constructor
+        self.query = query or {}
+        self.query.update(
+            {k: v for k, v in kwargs.items() if k in EEGDash._ALLOWED_QUERY_FIELDS}
+        )
+        base_dataset_kwargs = {k: v for k, v in kwargs.items() if k not in self.query}
+        if "dataset" not in self.query:
+            raise ValueError("You must provide a 'dataset' argument")
+
+        self.data_dir = self.cache_dir / self.query["dataset"]
+        if self.query["dataset"] in RELEASE_TO_OPENNEURO_DATASET_MAP.values():
+            warn(
+                "If you are not participating in the competition, you can ignore this warning!"
+                "\n\n"
+                "EEG 2025 Competition Data Notice:\n"
+                "---------------------------------\n"
+                " You are loading the dataset that is used in the EEG 2025 Competition:\n"
+                "IMPORTANT: The data accessed via `EEGDashDataset` is NOT identical to what you get from `EEGChallengeDataset` object directly.\n"
+                "and it is not what you will use for the competition. Downsampling and filtering were applied to the data"
+                "to allow more people to participate.\n"
+                "\n"
+                "If you are participating in the competition, always use `EEGChallengeDataset` to ensure consistency with the challenge data.\n"
+                "\n",
+                UserWarning,
+                module="eegdash",
+            )
         _owns_client = False
         if self.eeg_dash is None and records is None:
             self.eeg_dash = EEGDash()
             _owns_client = True
 
-        # Separate query kwargs from other kwargs passed to the BaseDataset constructor
-        query_kwargs = {
-            k: v for k, v in kwargs.items() if k in EEGDash._ALLOWED_QUERY_FIELDS
-        }
-        base_dataset_kwargs = {k: v for k, v in kwargs.items() if k not in query_kwargs}
-
-        # If user provided a dataset name via the dedicated parameter (and we're not
-        # loading from a local directory), treat it as a query filter. Accept str or list.
-        if data_dir is None and dataset is not None:
-            # Allow callers to pass a single dataset id (str) or a list of them.
-            # If list is provided, let _build_query_from_kwargs turn it into $in later.
-            query_kwargs.setdefault("dataset", dataset)
-
-        # Allow mixing raw DB query with additional keyword filters. Both will be
-        # merged by EEGDash.find() (logical AND), so we do not raise here.
-
         try:
             if records is not None:
                 self.records = records
@@ -795,42 +817,26 @@ class EEGDashDataset(BaseConcatDataset):
                     )
                     for record in self.records
                 ]
-            elif data_dir:
-                # This path loads from a local directory and is not affected by DB query logic
-                if isinstance(data_dir, (str, Path)):
-                    datasets = self.load_bids_dataset(
-                        dataset=dataset
-                        if isinstance(dataset, str)
-                        else (dataset[0] if dataset else None),
-                        data_dir=data_dir,
+            elif offline_mode:  # only assume local data is complete if in offline mode
+                if self.data_dir.exists():
+                    # This path loads from a local directory and is not affected by DB query logic
+                    datasets = self.load_bids_daxtaset(
+                        dataset=self.query["dataset"],
+                        data_dir=self.data_dir,
                         description_fields=description_fields,
                         s3_bucket=s3_bucket,
+                        n_jobs=n_jobs,
                         **base_dataset_kwargs,
                     )
                 else:
-                    assert dataset is not None, (
-                        "dataset must be provided when passing multiple data_dir"
-                    )
-                    assert len(data_dir) == len(dataset), (
-                        "Number of datasets and directories must match"
+                    raise ValueError(
+                        f"Offline mode is enabled, but local data_dir {self.data_dir} does not exist."
                     )
-                    datasets = []
-                    for i, _ in enumerate(data_dir):
-                        datasets.extend(
-                            self.load_bids_dataset(
-                                dataset=dataset[i],
-                                data_dir=data_dir[i],
-                                description_fields=description_fields,
-                                s3_bucket=s3_bucket,
-                                **base_dataset_kwargs,
-                            )
-                        )
-            elif query is not None or query_kwargs:
+            elif self.query:
                 # This is the DB query path that we are improving
-                datasets = self.find_datasets(
-                    query=query,
+                datasets = self._find_datasets(
+                    query=self.eeg_dash._build_query_from_kwargs(**self.query),
                     description_fields=description_fields,
-                    query_kwargs=query_kwargs,
                     base_dataset_kwargs=base_dataset_kwargs,
                 )
                 # We only need filesystem if we need to access S3
@@ -860,11 +866,10 @@ class EEGDashDataset(BaseConcatDataset):
                     return result
         return None
 
-    def find_datasets(
+    def _find_datasets(
         self,
         query: dict[str, Any] | None,
         description_fields: list[str],
-        query_kwargs: dict,
         base_dataset_kwargs: dict,
     ) -> list[EEGDashBaseDataset]:
         """Helper method to find datasets in the MongoDB collection that satisfy the
@@ -888,11 +893,7 @@ class EEGDashDataset(BaseConcatDataset):
         """
         datasets: list[EEGDashBaseDataset] = []
 
-        # Build records using either a raw query OR keyword filters, but not both.
-        # Note: callers may accidentally pass an empty dict for `query` along with
-        # kwargs. In that case, treat it as if no query was provided and rely on kwargs.
-        # Always delegate merging of raw query + kwargs to EEGDash.find
-        self.records = self.eeg_dash.find(query, **query_kwargs)
+        self.records = self.eeg_dash.find(query)
 
         for record in self.records:
             description = {}
@@ -903,8 +904,8 @@ class EEGDashDataset(BaseConcatDataset):
             datasets.append(
                 EEGDashBaseDataset(
                     record,
-                    self.cache_dir,
-                    self.s3_bucket,
+                    cache_dir=self.cache_dir,
+                    s3_bucket=self.s3_bucket,
                     description=description,
                     **base_dataset_kwargs,
                 )
@@ -917,6 +918,7 @@ class EEGDashDataset(BaseConcatDataset):
         data_dir: str | Path,
         description_fields: list[str],
         s3_bucket: str | None = None,
+        n_jobs: int = -1,
         **kwargs,
     ):
         """Helper method to load a single local BIDS dataset and return it as a list of
@@ -931,13 +933,17 @@ class EEGDashDataset(BaseConcatDataset):
         description_fields : list[str]
             A list of fields to be extracted from the dataset records
             and included in the returned dataset description(s).
+        s3_bucket : str | None
+            The S3 bucket to upload the dataset files to (if any).
+        n_jobs : int
+            The number of jobs to run in parallel (default is -1, meaning using all processors).
 
         """
         bids_dataset = EEGBIDSDataset(
             data_dir=data_dir,
             dataset=dataset,
         )
-        datasets = Parallel(n_jobs=-1, prefer="threads", verbose=1)(
+        datasets = Parallel(n_jobs=n_jobs, prefer="threads", verbose=1)(
             delayed(self.get_base_dataset_from_bids_file)(
                 bids_dataset=bids_dataset,
                 bids_file=bids_file,

eegdash/const.py

@@ -0,0 +1,258 @@
+RELEASE_TO_OPENNEURO_DATASET_MAP = {
+    "R11": "ds005516",
+    "R10": "ds005515",
+    "R9": "ds005514",
+    "R8": "ds005512",
+    "R7": "ds005511",
+    "R6": "ds005510",
+    "R4": "ds005508",
+    "R5": "ds005509",
+    "R3": "ds005507",
+    "R2": "ds005506",
+    "R1": "ds005505",
+}
+
+SUBJECT_MINI_RELEASE_MAP = {
+    "R11": [
+        "NDARAB678VYW",
+        "NDARAG788YV9",
+        "NDARAM946HJE",
+        "NDARAY977BZT",
+        "NDARAZ532KK0",
+        "NDARCE912ZXW",
+        "NDARCM214WFE",
+        "NDARDL033XRG",
+        "NDARDT889RT9",
+        "NDARDZ794ZVP",
+        "NDAREV869CPW",
+        "NDARFN221WW5",
+        "NDARFV289RKB",
+        "NDARFY623ZTE",
+        "NDARGA890MKA",
+        "NDARHN206XY3",
+        "NDARHP518FUR",
+        "NDARJL292RYV",
+        "NDARKM199DXW",
+        "NDARKW236TN7",
+    ],
+    "R10": [
+        "NDARAR935TGZ",
+        "NDARAV474ADJ",
+        "NDARCB869VM8",
+        "NDARCJ667UPL",
+        "NDARCM677TC1",
+        "NDARET671FTC",
+        "NDARKM061NHZ",
+        "NDARLD501HDK",
+        "NDARLL176DJR",
+        "NDARMT791WDH",
+        "NDARMW299ZAB",
+        "NDARNC405WJA",
+        "NDARNP962TJK",
+        "NDARPB967KU7",
+        "NDARRU560AGK",
+        "NDARTB173LY2",
+        "NDARUW377KAE",
+        "NDARVH565FX9",
+        "NDARVP799KGY",
+        "NDARVY962GB5",
+    ],
+    "R9": [
+        "NDARAC589YMB",
+        "NDARAC853CR6",
+        "NDARAH239PGG",
+        "NDARAL897CYV",
+        "NDARAN160GUF",
+        "NDARAP049KXJ",
+        "NDARAP457WB5",
+        "NDARAW216PM7",
+        "NDARBA004KBT",
+        "NDARBD328NUQ",
+        "NDARBF042LDM",
+        "NDARBH019KPD",
+        "NDARBH728DFK",
+        "NDARBM370JCB",
+        "NDARBU183TDJ",
+        "NDARBW971DCW",
+        "NDARBZ444ZHK",
+        "NDARCC620ZFT",
+        "NDARCD182XT1",
+        "NDARCK113CJM",
+    ],
+    "R8": [
+        "NDARAB514MAJ",
+        "NDARAD571FLB",
+        "NDARAF003VCL",
+        "NDARAG191AE8",
+        "NDARAJ977PRJ",
+        "NDARAP912JK3",
+        "NDARAV454VF0",
+        "NDARAY298THW",
+        "NDARBJ375VP4",
+        "NDARBT436PMT",
+        "NDARBV630BK6",
+        "NDARCB627KDN",
+        "NDARCC059WTH",
+        "NDARCM953HKD",
+        "NDARCN681CXW",
+        "NDARCT889DMB",
+        "NDARDJ204EPU",
+        "NDARDJ544BU5",
+        "NDARDP292DVC",
+        "NDARDW178AC6",
+    ],
+    "R7": [
+        "NDARAY475AKD",
+        "NDARBW026UGE",
+        "NDARCK162REX",
+        "NDARCK481KRH",
+        "NDARCV378MMX",
+        "NDARCX462NVA",
+        "NDARDJ970ELG",
+        "NDARDU617ZW1",
+        "NDAREM609ZXW",
+        "NDAREW074ZM2",
+        "NDARFE555KXB",
+        "NDARFT176NJP",
+        "NDARGK442YHH",
+        "NDARGM439FZD",
+        "NDARGT634DUJ",
+        "NDARHE283KZN",
+        "NDARHG260BM9",
+        "NDARHL684WYU",
+        "NDARHN224TPA",
+        "NDARHP841RMR",
+    ],
+    "R6": [
+        "NDARAD224CRB",
+        "NDARAE301XTM",
+        "NDARAT680GJA",
+        "NDARCA578CEB",
+        "NDARDZ147ETZ",
+        "NDARFL793LDE",
+        "NDARFX710UZA",
+        "NDARGE994BMX",
+        "NDARGP191YHN",
+        "NDARGV436PFT",
+        "NDARHF545HFW",
+        "NDARHP039DBU",
+        "NDARHT774ZK1",
+        "NDARJA830BYV",
+        "NDARKB614KGY",
+        "NDARKM250ET5",
+        "NDARKZ085UKQ",
+        "NDARLB581AXF",
+        "NDARNJ899HW7",
+        "NDARRZ606EDP",
+    ],
+    "R4": [
+        "NDARAC350BZ0",
+        "NDARAD615WLJ",
+        "NDARAG584XLU",
+        "NDARAH503YG1",
+        "NDARAX272ZJL",
+        "NDARAY461TZZ",
+        "NDARBC734UVY",
+        "NDARBL444FBA",
+        "NDARBT640EBN",
+        "NDARBU098PJT",
+        "NDARBU928LV0",
+        "NDARBV059CGE",
+        "NDARCG037CX4",
+        "NDARCG947ZC0",
+        "NDARCH001CN2",
+        "NDARCU001ZN7",
+        "NDARCW497XW2",
+        "NDARCX053GU5",
+        "NDARDF568GL5",
+        "NDARDJ092YKH",
+    ],
+    "R5": [
+        "NDARAH793FBF",
+        "NDARAJ689BVN",
+        "NDARAP785CTE",
+        "NDARAU708TL8",
+        "NDARBE091BGD",
+        "NDARBE103DHM",
+        "NDARBF851NH6",
+        "NDARBH228RDW",
+        "NDARBJ674TVU",
+        "NDARBM433VER",
+        "NDARCA740UC8",
+        "NDARCU633GCZ",
+        "NDARCU736GZ1",
+        "NDARCU744XWL",
+        "NDARDC843HHM",
+        "NDARDH086ZKK",
+        "NDARDL305BT8",
+        "NDARDU853XZ6",
+        "NDARDV245WJG",
+        "NDAREC480KFA",
+    ],
+    "R3": [
+        "NDARAA948VFH",
+        "NDARAD774HAZ",
+        "NDARAE828CML",
+        "NDARAG340ERT",
+        "NDARBA839HLG",
+        "NDARBE641DGZ",
+        "NDARBG574KF4",
+        "NDARBM642JFT",
+        "NDARCL016NHB",
+        "NDARCV944JA6",
+        "NDARCY178KJP",
+        "NDARDY150ZP9",
+        "NDAREC542MH3",
+        "NDAREK549XUQ",
+        "NDAREM887YY8",
+        "NDARFA815FXE",
+        "NDARFF644ZGD",
+        "NDARFV557XAA",
+        "NDARFV780ABD",
+        "NDARGB102NWJ",
+    ],
+    "R2": [
+        "NDARAB793GL3",
+        "NDARAM675UR8",
+        "NDARBM839WR5",
+        "NDARBU730PN8",
+        "NDARCT974NAJ",
+        "NDARCW933FD5",
+        "NDARCZ770BRG",
+        "NDARDW741HCF",
+        "NDARDZ058NZN",
+        "NDAREC377AU2",
+        "NDAREM500WWH",
+        "NDAREV527ZRF",
+        "NDAREV601CE7",
+        "NDARFF070XHV",
+        "NDARFR108JNB",
+        "NDARFT305CG1",
+        "NDARGA056TMW",
+        "NDARGH775KF5",
+        "NDARGJ878ZP4",
+        "NDARHA387FPM",
+    ],
+    "R1": [
+        "NDARAC904DMU",
+        "NDARAM704GKZ",
+        "NDARAP359UM6",
+        "NDARBD879MBX",
+        "NDARBH024NH2",
+        "NDARBK082PDD",
+        "NDARCA153NKE",
+        "NDARCE721YB5",
+        "NDARCJ594BWQ",
+        "NDARCN669XPR",
+        "NDARCW094JCG",
+        "NDARCZ947WU5",
+        "NDARDH670PXH",
+        "NDARDL511UND",
+        "NDARDU986RBM",
+        "NDAREM731BYM",
+        "NDAREN519BLJ",
+        "NDARFK610GY5",
+        "NDARFT581ZW5",
+        "NDARFW972KFQ",
+    ],
+}

eegdash/dataset.py

@@ -1,266 +1,13 @@
+import logging
 from pathlib import Path
 
+from mne.utils import warn
+
 from .api import EEGDashDataset
+from .const import RELEASE_TO_OPENNEURO_DATASET_MAP, SUBJECT_MINI_RELEASE_MAP
 from .registry import register_openneuro_datasets
 
-RELEASE_TO_OPENNEURO_DATASET_MAP = {
-    "R11": "ds005516",
-    "R10": "ds005515",
-    "R9": "ds005514",
-    "R8": "ds005512",
-    "R7": "ds005511",
-    "R6": "ds005510",
-    "R4": "ds005508",
-    "R5": "ds005509",
-    "R3": "ds005507",
-    "R2": "ds005506",
-    "R1": "ds005505",
-}
-
-SUBJECT_MINI_RELEASE_MAP = {
-    "R11": [
-        "NDARAB678VYW",
-        "NDARAG788YV9",
-        "NDARAM946HJE",
-        "NDARAY977BZT",
-        "NDARAZ532KK0",
-        "NDARCE912ZXW",
-        "NDARCM214WFE",
-        "NDARDL033XRG",
-        "NDARDT889RT9",
-        "NDARDZ794ZVP",
-        "NDAREV869CPW",
-        "NDARFN221WW5",
-        "NDARFV289RKB",
-        "NDARFY623ZTE",
-        "NDARGA890MKA",
-        "NDARHN206XY3",
-        "NDARHP518FUR",
-        "NDARJL292RYV",
-        "NDARKM199DXW",
-        "NDARKW236TN7",
-    ],
-    "R10": [
-        "NDARAR935TGZ",
-        "NDARAV474ADJ",
-        "NDARCB869VM8",
-        "NDARCJ667UPL",
-        "NDARCM677TC1",
-        "NDARET671FTC",
-        "NDARKM061NHZ",
-        "NDARLD501HDK",
-        "NDARLL176DJR",
-        "NDARMT791WDH",
-        "NDARMW299ZAB",
-        "NDARNC405WJA",
-        "NDARNP962TJK",
-        "NDARPB967KU7",
-        "NDARRU560AGK",
-        "NDARTB173LY2",
-        "NDARUW377KAE",
-        "NDARVH565FX9",
-        "NDARVP799KGY",
-        "NDARVY962GB5",
-    ],
-    "R9": [
-        "NDARAC589YMB",
-        "NDARAC853CR6",
-        "NDARAH239PGG",
-        "NDARAL897CYV",
-        "NDARAN160GUF",
-        "NDARAP049KXJ",
-        "NDARAP457WB5",
-        "NDARAW216PM7",
-        "NDARBA004KBT",
-        "NDARBD328NUQ",
-        "NDARBF042LDM",
-        "NDARBH019KPD",
-        "NDARBH728DFK",
-        "NDARBM370JCB",
-        "NDARBU183TDJ",
-        "NDARBW971DCW",
-        "NDARBZ444ZHK",
-        "NDARCC620ZFT",
-        "NDARCD182XT1",
-        "NDARCK113CJM",
-    ],
-    "R8": [
-        "NDARAB514MAJ",
-        "NDARAD571FLB",
-        "NDARAF003VCL",
-        "NDARAG191AE8",
-        "NDARAJ977PRJ",
-        "NDARAP912JK3",
-        "NDARAV454VF0",
-        "NDARAY298THW",
-        "NDARBJ375VP4",
-        "NDARBT436PMT",
-        "NDARBV630BK6",
-        "NDARCB627KDN",
-        "NDARCC059WTH",
-        "NDARCM953HKD",
-        "NDARCN681CXW",
-        "NDARCT889DMB",
-        "NDARDJ204EPU",
-        "NDARDJ544BU5",
-        "NDARDP292DVC",
-        "NDARDW178AC6",
-    ],
-    "R7": [
-        "NDARAY475AKD",
-        "NDARBW026UGE",
-        "NDARCK162REX",
-        "NDARCK481KRH",
-        "NDARCV378MMX",
-        "NDARCX462NVA",
-        "NDARDJ970ELG",
-        "NDARDU617ZW1",
-        "NDAREM609ZXW",
-        "NDAREW074ZM2",
-        "NDARFE555KXB",
-        "NDARFT176NJP",
-        "NDARGK442YHH",
-        "NDARGM439FZD",
-        "NDARGT634DUJ",
-        "NDARHE283KZN",
-        "NDARHG260BM9",
-        "NDARHL684WYU",
-        "NDARHN224TPA",
-        "NDARHP841RMR",
-    ],
-    "R6": [
-        "NDARAD224CRB",
-        "NDARAE301XTM",
-        "NDARAT680GJA",
-        "NDARCA578CEB",
-        "NDARDZ147ETZ",
-        "NDARFL793LDE",
-        "NDARFX710UZA",
-        "NDARGE994BMX",
-        "NDARGP191YHN",
-        "NDARGV436PFT",
-        "NDARHF545HFW",
-        "NDARHP039DBU",
-        "NDARHT774ZK1",
-        "NDARJA830BYV",
-        "NDARKB614KGY",
-        "NDARKM250ET5",
-        "NDARKZ085UKQ",
-        "NDARLB581AXF",
-        "NDARNJ899HW7",
-        "NDARRZ606EDP",
-    ],
-    "R4": [
-        "NDARAC350BZ0",
-        "NDARAD615WLJ",
-        "NDARAG584XLU",
-        "NDARAH503YG1",
-        "NDARAX272ZJL",
-        "NDARAY461TZZ",
-        "NDARBC734UVY",
-        "NDARBL444FBA",
-        "NDARBT640EBN",
-        "NDARBU098PJT",
-        "NDARBU928LV0",
-        "NDARBV059CGE",
-        "NDARCG037CX4",
-        "NDARCG947ZC0",
-        "NDARCH001CN2",
-        "NDARCU001ZN7",
-        "NDARCW497XW2",
-        "NDARCX053GU5",
-        "NDARDF568GL5",
-        "NDARDJ092YKH",
-    ],
-    "R5": [
-        "NDARAH793FBF",
-        "NDARAJ689BVN",
-        "NDARAP785CTE",
-        "NDARAU708TL8",
-        "NDARBE091BGD",
-        "NDARBE103DHM",
-        "NDARBF851NH6",
-        "NDARBH228RDW",
-        "NDARBJ674TVU",
-        "NDARBM433VER",
-        "NDARCA740UC8",
-        "NDARCU633GCZ",
-        "NDARCU736GZ1",
-        "NDARCU744XWL",
-        "NDARDC843HHM",
-        "NDARDH086ZKK",
-        "NDARDL305BT8",
-        "NDARDU853XZ6",
-        "NDARDV245WJG",
-        "NDAREC480KFA",
-    ],
-    "R3": [
-        "NDARAA948VFH",
-        "NDARAD774HAZ",
-        "NDARAE828CML",
-        "NDARAG340ERT",
-        "NDARBA839HLG",
-        "NDARBE641DGZ",
-        "NDARBG574KF4",
-        "NDARBM642JFT",
-        "NDARCL016NHB",
-        "NDARCV944JA6",
-        "NDARCY178KJP",
-        "NDARDY150ZP9",
-        "NDAREC542MH3",
-        "NDAREK549XUQ",
-        "NDAREM887YY8",
-        "NDARFA815FXE",
-        "NDARFF644ZGD",
-        "NDARFV557XAA",
-        "NDARFV780ABD",
-        "NDARGB102NWJ",
-    ],
-    "R2": [
-        "NDARAB793GL3",
-        "NDARAM675UR8",
-        "NDARBM839WR5",
-        "NDARBU730PN8",
-        "NDARCT974NAJ",
-        "NDARCW933FD5",
-        "NDARCZ770BRG",
-        "NDARDW741HCF",
-        "NDARDZ058NZN",
-        "NDAREC377AU2",
-        "NDAREM500WWH",
-        "NDAREV527ZRF",
-        "NDAREV601CE7",
-        "NDARFF070XHV",
-        "NDARFR108JNB",
-        "NDARFT305CG1",
-        "NDARGA056TMW",
-        "NDARGH775KF5",
-        "NDARGJ878ZP4",
-        "NDARHA387FPM",
-    ],
-    "R1": [
-        "NDARAC904DMU",
-        "NDARAM704GKZ",
-        "NDARAP359UM6",
-        "NDARBD879MBX",
-        "NDARBH024NH2",
-        "NDARBK082PDD",
-        "NDARCA153NKE",
-        "NDARCE721YB5",
-        "NDARCJ594BWQ",
-        "NDARCN669XPR",
-        "NDARCW094JCG",
-        "NDARCZ947WU5",
-        "NDARDH670PXH",
-        "NDARDL511UND",
-        "NDARDU986RBM",
-        "NDAREM731BYM",
-        "NDAREN519BLJ",
-        "NDARFK610GY5",
-        "NDARFT581ZW5",
-        "NDARFW972KFQ",
-    ],
-}
+logger = logging.getLogger("eegdash")
 
 
 class EEGChallengeDataset(EEGDashDataset):
@@ -334,8 +81,26 @@ class EEGChallengeDataset(EEGDashDataset):
         else:
             s3_bucket = f"{s3_bucket}/{release}_L100_bdf"
 
+        warn(
+            "\n\n"
+            "[EEGChallengeDataset] EEG 2025 Competition Data Notice:\n"
+            "-------------------------------------------------------\n"
+            "This object loads the HBN dataset that has been preprocessed for the EEG Challenge:\n"
+            "  - Downsampled from 500Hz to 100Hz\n"
+            "  - Bandpass filtered (0.5–50 Hz)\n"
+            "\n"
+            "For full preprocessing details, see:\n"
+            "  https://github.com/eeg2025/downsample-datasets\n"
+            "\n"
+            "IMPORTANT: The data accessed via `EEGChallengeDataset` is NOT identical to what you get from `EEGDashDataset` directly.\n"
+            "If you are participating in the competition, always use `EEGChallengeDataset` to ensure consistency with the challenge data.\n"
+            "\n",
+            UserWarning,
+            module="eegdash",
+        )
+
         super().__init__(
-            dataset=dataset_parameters,
+            dataset=RELEASE_TO_OPENNEURO_DATASET_MAP[release],
             query=query,
             cache_dir=cache_dir,
             s3_bucket=s3_bucket,

eegdash/registry.py

@@ -57,7 +57,7 @@ def register_openneuro_datasets(
 
         init = make_init(dataset_id)
 
-        doc = f"""Create an instance for OpenNeuro dataset ``{dataset_id}``.
+        doc = f"""OpenNeuro dataset ``{dataset_id}``.
 
         {markdown_table(row_series)}
 
@@ -69,11 +69,15 @@ def register_openneuro_datasets(
             Extra Mongo query merged with ``{{'dataset': '{dataset_id}'}}``.
         s3_bucket : str | None
             Optional S3 bucket name.
+        subject : str | None
+            Optional subject identifier.
+        task : str | None
+            Optional task identifier.
         **kwargs
             Passed through to {base_class.__name__}.
         """
 
-        init.__doc__ = doc
+        # init.__doc__ = doc
 
         cls = type(
             class_name,
@@ -101,6 +105,7 @@ def markdown_table(row_series: pd.Series) -> str:
     """Create a reStructuredText grid table from a pandas Series."""
     if row_series.empty:
         return ""
+    dataset_id = row_series["dataset"]
 
     # Prepare the dataframe with user's suggested logic
     df = (
@@ -112,6 +117,7 @@ def markdown_table(row_series: pd.Series) -> str:
                 "n_tasks": "#Classes",
                 "sampling_freqs": "Freq(Hz)",
                 "duration_hours_total": "Duration(H)",
+                "size": "Size",
             }
         )
         .reindex(
@@ -122,6 +128,7 @@ def markdown_table(row_series: pd.Series) -> str:
                 "#Classes",
                 "Freq(Hz)",
                 "Duration(H)",
+                "Size",
             ]
         )
         .infer_objects(copy=False)
@@ -131,6 +138,9 @@ def markdown_table(row_series: pd.Series) -> str:
     # Use tabulate for the final rst formatting
     table = tabulate(df, headers="keys", tablefmt="rst", showindex=False)
 
+    # Add a caption for the table
+    caption = f"Short overview of dataset {dataset_id} more details in the `Nemar documentation <https://nemar.org/dataexplorer/detail?dataset_id={dataset_id}>`_."
+    # adding caption below the table
     # Indent the table to fit within the admonition block
     indented_table = "\n".join("    " + line for line in table.split("\n"))
-    return f"\n\n{indented_table}"
+    return f"\n\n{indented_table}\n\n{caption}"

{eegdash-0.3.6.dev182011805.dist-info → eegdash-0.3.7.dev104.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.3.6.dev182011805
+Version: 0.3.7.dev104
 Summary: EEG data for machine learning
 Author-email: Young Truong <dt.young112@gmail.com>, Arnaud Delorme <adelorme@gmail.com>, Aviv Dotan <avivd220@gmail.com>, Oren Shriki <oren70@gmail.com>, Bruno Aristimunha <b.aristimunha@gmail.com>
 License-Expression: GPL-3.0-only
@@ -48,6 +48,7 @@ Requires-Dist: pytest_cases; extra == "tests"
 Requires-Dist: pytest-benchmark; extra == "tests"
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ipykernel; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: sphinx_design; extra == "docs"
@@ -55,10 +56,12 @@ Requires-Dist: sphinx_gallery; extra == "docs"
 Requires-Dist: sphinx_rtd_theme; extra == "docs"
 Requires-Dist: pydata-sphinx-theme; extra == "docs"
 Requires-Dist: sphinx-autobuild; extra == "docs"
+Requires-Dist: sphinx-sitemap; extra == "docs"
 Requires-Dist: numpydoc; extra == "docs"
 Requires-Dist: memory_profiler; extra == "docs"
 Requires-Dist: ipython; extra == "docs"
 Requires-Dist: lightgbm; extra == "docs"
+Requires-Dist: plotly; extra == "docs"
 Provides-Extra: all
 Requires-Dist: eegdash[docs]; extra == "all"
 Requires-Dist: eegdash[dev]; extra == "all"

{eegdash-0.3.6.dev182011805.dist-info → eegdash-0.3.7.dev104.dist-info}/RECORD

@@ -1,12 +1,12 @@
-eegdash/__init__.py,sha256=NLvINqQgb9EuPvIl_VMrEupLgfbk5827M_Wgbl_pX2g,247
-eegdash/api.py,sha256=yotN4vqurZAxVA4q_DK4z0mhh9P8sbpxKzvyxuRSkcQ,38538
+eegdash/__init__.py,sha256=A70xhDRmnPwJULFWRxt9Nx-AbZRTh13WJoBDyzviKHQ,303
+eegdash/api.py,sha256=7QTComMkbOdHumlzdOrNV2kqHy9R9HG2Gefo_eLBy-U,38948
+eegdash/const.py,sha256=syrXxcqFyl4dxAetOuhPyCYZ2xgilsLunJRVzx9TCeA,5806
 eegdash/data_config.py,sha256=OS6ERO-jHrnEOfMJUehY7ieABdsRw_qWzOKJ4pzSfqw,1323
 eegdash/data_utils.py,sha256=mi9pscui-BPpRH9ovRtGWiSwHG5QN6K_IvJdYaING2I,27679
-eegdash/dataset.py,sha256=iGi7m2FNhLgJxxwSsB9JIy01p4tmdlJIPzdL5CDAJU4,9446
+eegdash/dataset.py,sha256=6Tgj_1j4DNoaPoMnhtancDtPG6bxODnbPlXkDzGjtrQ,4716
 eegdash/dataset_summary.csv,sha256=9Rw9PawiQ9a_OBRJYKarrzb4UFSGpkGULhYB0MYUieE,14740
 eegdash/mongodb.py,sha256=GD3WgA253oFgpzOHrYaj4P1mRjNtDMT5Oj4kVvHswjI,2006
-eegdash/preprocessing.py,sha256=7S_TTRKPKEk47tTnh2D6WExBt4cctAMxUxGDjJqq5lU,2221
-eegdash/registry.py,sha256=cxqX53GYyDvg5DkiqJkvjqHDPI72JTPlI4qVh2sILu8,3873
+eegdash/registry.py,sha256=jBR2tGE4YJL4yhbZcn2CN4jaC-ttyVN0wmsCR1uWzoU,4329
 eegdash/utils.py,sha256=wU9CBQZLW_LIQIBwhgQm5bU4X-rSsVNPdeF2iE4QGJ4,410
 eegdash/features/__init__.py,sha256=BXNhjvL4_SSFAY1lcP9nyGpkbJNtoOMH4AHlF6OyABo,4078
 eegdash/features/datasets.py,sha256=kU1DO70ArSIy-LF1hHD2NN4iT-kJrI0mVpSkyV_OSeI,18301
@@ -23,8 +23,8 @@ eegdash/features/feature_bank/dimensionality.py,sha256=j_Ds71Y1AbV2uLFQj8EuXQ4kz
 eegdash/features/feature_bank/signal.py,sha256=3Tb8z9gX7iZipxQJ9DSyy30JfdmW58kgvimSyZX74p8,3404
 eegdash/features/feature_bank/spectral.py,sha256=bNB7skusePs1gX7NOU6yRlw_Gr4UOCkO_ylkCgybzug,3319
 eegdash/features/feature_bank/utils.py,sha256=DGh-Q7-XFIittP7iBBxvsJaZrlVvuY5mw-G7q6C-PCI,1237
-eegdash-0.3.6.dev182011805.dist-info/licenses/LICENSE,sha256=asisR-xupy_NrQBFXnx6yqXeZcYWLvbAaiETl25iXT0,931
-eegdash-0.3.6.dev182011805.dist-info/METADATA,sha256=jBWyMgXrjtrbTGvALa7gKU0TpsUcVQoByszJ8xS-TdQ,9932
-eegdash-0.3.6.dev182011805.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-eegdash-0.3.6.dev182011805.dist-info/top_level.txt,sha256=zavO69HQ6MyZM0aQMR2zUS6TAFc7bnN5GEpDpOpFZzU,8
-eegdash-0.3.6.dev182011805.dist-info/RECORD,,
+eegdash-0.3.7.dev104.dist-info/licenses/LICENSE,sha256=asisR-xupy_NrQBFXnx6yqXeZcYWLvbAaiETl25iXT0,931
+eegdash-0.3.7.dev104.dist-info/METADATA,sha256=vFsNOyHy0Bq1XBvV_aDoNLSdtuK4H4hzpvU67tfnRJE,10053
+eegdash-0.3.7.dev104.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+eegdash-0.3.7.dev104.dist-info/top_level.txt,sha256=zavO69HQ6MyZM0aQMR2zUS6TAFc7bnN5GEpDpOpFZzU,8
+eegdash-0.3.7.dev104.dist-info/RECORD,,

eegdash/preprocessing.py

@@ -1,63 +0,0 @@
-import logging
-
-import mne
-import numpy as np
-
-from braindecode.preprocessing import Preprocessor
-
-logger = logging.getLogger("eegdash")
-
-
-class hbn_ec_ec_reannotation(Preprocessor):
-    """Preprocessor to reannotate the raw data for eyes open and eyes closed events.
-
-    This processor is designed for HBN datasets.
-
-    """
-
-    def __init__(self):
-        super().__init__(fn=self.transform, apply_on_array=False)
-
-    def transform(self, raw):
-        """Reannotate the raw data to create new events for eyes open and eyes closed
-
-        This function modifies the raw MNE object by creating new events based on
-        the existing annotations for "instructed_toCloseEyes" and "instructed_toOpenEyes".
-        It generates new events every 2 seconds within specified time ranges after
-        the original events, and replaces the existing annotations with these new events.
-
-        Parameters
-        ----------
-        raw : mne.io.Raw
-            The raw MNE object containing EEG data and annotations.
-
-        """
-        events, event_id = mne.events_from_annotations(raw)
-
-        logger.info("Original events found with ids: %s", event_id)
-
-        # Create new events array for 2-second segments
-        new_events = []
-        sfreq = raw.info["sfreq"]
-        for event in events[events[:, 2] == event_id["instructed_toCloseEyes"]]:
-            # For each original event, create events every 2 seconds from 15s to 29s after
-            start_times = event[0] + np.arange(15, 29, 2) * sfreq
-            new_events.extend([[int(t), 0, 1] for t in start_times])
-
-        for event in events[events[:, 2] == event_id["instructed_toOpenEyes"]]:
-            # For each original event, create events every 2 seconds from 5s to 19s after
-            start_times = event[0] + np.arange(5, 19, 2) * sfreq
-            new_events.extend([[int(t), 0, 2] for t in start_times])
-
-        # replace events in raw
-        new_events = np.array(new_events)
-
-        annot_from_events = mne.annotations_from_events(
-            events=new_events,
-            event_desc={1: "eyes_closed", 2: "eyes_open"},
-            sfreq=raw.info["sfreq"],
-        )
-
-        raw.set_annotations(annot_from_events)
-
-        return raw