eegdash 0.3.6.dev183416654__tar.gz → 0.3.7.dev104__tar.gz

{eegdash-0.3.6.dev183416654/eegdash.egg-info → eegdash-0.3.7.dev104}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.3.6.dev183416654
+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

eegdash-0.3.7.dev104/eegdash/__init__.py

@@ -0,0 +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", "preprocessing"]
+
+__version__ = "0.3.7.dev104"

{eegdash-0.3.6.dev183416654 → eegdash-0.3.7.dev104}/eegdash/api.py

@@ -17,6 +17,7 @@ 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
@@ -710,6 +711,7 @@ class EEGDashDataset(BaseConcatDataset):
         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
@@ -758,6 +760,8 @@ class EEGDashDataset(BaseConcatDataset):
         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.
@@ -780,7 +784,22 @@ class EEGDashDataset(BaseConcatDataset):
             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()
@@ -801,11 +820,12 @@ class EEGDashDataset(BaseConcatDataset):
             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_dataset(
+                    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:
@@ -898,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
@@ -912,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-0.3.6.dev183416654/eegdash/dataset.py → eegdash-0.3.7.dev104/eegdash/const.py

@@ -1,8 +1,3 @@
-from pathlib import Path
-
-from .api import EEGDashDataset
-from .registry import register_openneuro_datasets
-
 RELEASE_TO_OPENNEURO_DATASET_MAP = {
     "R11": "ds005516",
     "R10": "ds005515",
@@ -261,93 +256,3 @@ SUBJECT_MINI_RELEASE_MAP = {
         "NDARFW972KFQ",
     ],
 }
-
-
-class EEGChallengeDataset(EEGDashDataset):
-    def __init__(
-        self,
-        release: str,
-        cache_dir: str,
-        mini: bool = True,
-        query: dict | None = None,
-        s3_bucket: str | None = "s3://nmdatasets/NeurIPS25",
-        **kwargs,
-    ):
-        """Create a new EEGDashDataset from a given query or local BIDS dataset directory
-        and dataset name. An EEGDashDataset is pooled collection of EEGDashBaseDataset
-        instances (individual recordings) and is a subclass of braindecode's BaseConcatDataset.
-
-        Parameters
-        ----------
-        release: str
-            Release name. Can be one of ["R1", ..., "R11"]
-        mini: bool, default True
-            Whether to use the mini-release version of the dataset. It is recommended
-            to use the mini version for faster training and evaluation.
-        query : dict | None
-            Optionally a dictionary that specifies a query to be executed,
-            in addition to the dataset (automatically inferred from the release argument).
-            See EEGDash.find() for details on the query format.
-        cache_dir : str
-            A directory where the dataset will be cached locally.
-        s3_bucket : str | None
-            An optional S3 bucket URI to use instead of the
-            default OpenNeuro bucket for loading data files.
-        kwargs : dict
-            Additional keyword arguments to be passed to the EEGDashDataset
-            constructor.
-
-        """
-        self.release = release
-        self.mini = mini
-
-        if release not in RELEASE_TO_OPENNEURO_DATASET_MAP:
-            raise ValueError(
-                f"Unknown release: {release}, expected one of {list(RELEASE_TO_OPENNEURO_DATASET_MAP.keys())}"
-            )
-
-        dataset_parameters = []
-        if isinstance(release, str):
-            dataset_parameters.append(RELEASE_TO_OPENNEURO_DATASET_MAP[release])
-        else:
-            raise ValueError(
-                f"Unknown release type: {type(release)}, the expected type is str."
-            )
-
-        if query and "dataset" in query:
-            raise ValueError(
-                "Query using the parameters `dataset` with the class EEGChallengeDataset is not possible."
-                "Please use the release argument instead, or the object EEGDashDataset instead."
-            )
-
-        if self.mini:
-            # Disallow mixing subject selection with mini=True since mini already
-            # applies a predefined subject subset.
-            if (query and "subject" in query) or ("subject" in kwargs):
-                raise ValueError(
-                    "Query using the parameters `subject` with the class EEGChallengeDataset and `mini==True` is not possible."
-                    "Please don't use the `subject` selection twice."
-                    "Set `mini=False` to use the `subject` selection."
-                )
-            kwargs["subject"] = SUBJECT_MINI_RELEASE_MAP[release]
-            s3_bucket = f"{s3_bucket}/{release}_mini_L100_bdf"
-        else:
-            s3_bucket = f"{s3_bucket}/{release}_L100_bdf"
-
-        super().__init__(
-            dataset=RELEASE_TO_OPENNEURO_DATASET_MAP[release],
-            query=query,
-            cache_dir=cache_dir,
-            s3_bucket=s3_bucket,
-            **kwargs,
-        )
-
-
-registered_classes = register_openneuro_datasets(
-    summary_file=Path(__file__).with_name("dataset_summary.csv"),
-    base_class=EEGDashDataset,
-    namespace=globals(),
-)
-
-
-__all__ = ["EEGChallengeDataset"] + list(registered_classes.keys())

eegdash-0.3.7.dev104/eegdash/dataset.py

@@ -0,0 +1,118 @@
+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
+
+logger = logging.getLogger("eegdash")
+
+
+class EEGChallengeDataset(EEGDashDataset):
+    def __init__(
+        self,
+        release: str,
+        cache_dir: str,
+        mini: bool = True,
+        query: dict | None = None,
+        s3_bucket: str | None = "s3://nmdatasets/NeurIPS25",
+        **kwargs,
+    ):
+        """Create a new EEGDashDataset from a given query or local BIDS dataset directory
+        and dataset name. An EEGDashDataset is pooled collection of EEGDashBaseDataset
+        instances (individual recordings) and is a subclass of braindecode's BaseConcatDataset.
+
+        Parameters
+        ----------
+        release: str
+            Release name. Can be one of ["R1", ..., "R11"]
+        mini: bool, default True
+            Whether to use the mini-release version of the dataset. It is recommended
+            to use the mini version for faster training and evaluation.
+        query : dict | None
+            Optionally a dictionary that specifies a query to be executed,
+            in addition to the dataset (automatically inferred from the release argument).
+            See EEGDash.find() for details on the query format.
+        cache_dir : str
+            A directory where the dataset will be cached locally.
+        s3_bucket : str | None
+            An optional S3 bucket URI to use instead of the
+            default OpenNeuro bucket for loading data files.
+        kwargs : dict
+            Additional keyword arguments to be passed to the EEGDashDataset
+            constructor.
+
+        """
+        self.release = release
+        self.mini = mini
+
+        if release not in RELEASE_TO_OPENNEURO_DATASET_MAP:
+            raise ValueError(
+                f"Unknown release: {release}, expected one of {list(RELEASE_TO_OPENNEURO_DATASET_MAP.keys())}"
+            )
+
+        dataset_parameters = []
+        if isinstance(release, str):
+            dataset_parameters.append(RELEASE_TO_OPENNEURO_DATASET_MAP[release])
+        else:
+            raise ValueError(
+                f"Unknown release type: {type(release)}, the expected type is str."
+            )
+
+        if query and "dataset" in query:
+            raise ValueError(
+                "Query using the parameters `dataset` with the class EEGChallengeDataset is not possible."
+                "Please use the release argument instead, or the object EEGDashDataset instead."
+            )
+
+        if self.mini:
+            # Disallow mixing subject selection with mini=True since mini already
+            # applies a predefined subject subset.
+            if (query and "subject" in query) or ("subject" in kwargs):
+                raise ValueError(
+                    "Query using the parameters `subject` with the class EEGChallengeDataset and `mini==True` is not possible."
+                    "Please don't use the `subject` selection twice."
+                    "Set `mini=False` to use the `subject` selection."
+                )
+            kwargs["subject"] = SUBJECT_MINI_RELEASE_MAP[release]
+            s3_bucket = f"{s3_bucket}/{release}_mini_L100_bdf"
+        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=RELEASE_TO_OPENNEURO_DATASET_MAP[release],
+            query=query,
+            cache_dir=cache_dir,
+            s3_bucket=s3_bucket,
+            **kwargs,
+        )
+
+
+registered_classes = register_openneuro_datasets(
+    summary_file=Path(__file__).with_name("dataset_summary.csv"),
+    base_class=EEGDashDataset,
+    namespace=globals(),
+)
+
+
+__all__ = ["EEGChallengeDataset"] + list(registered_classes.keys())

{eegdash-0.3.6.dev183416654 → eegdash-0.3.7.dev104/eegdash.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.3.6.dev183416654
+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

{eegdash-0.3.6.dev183416654 → eegdash-0.3.7.dev104}/eegdash.egg-info/SOURCES.txt

@@ -12,12 +12,12 @@ docs/source/install/install_pip.rst
 docs/source/install/install_source.rst
 eegdash/__init__.py
 eegdash/api.py
+eegdash/const.py
 eegdash/data_config.py
 eegdash/data_utils.py
 eegdash/dataset.py
 eegdash/dataset_summary.csv
 eegdash/mongodb.py
-eegdash/preprocessing.py
 eegdash/registry.py
 eegdash/utils.py
 eegdash.egg-info/PKG-INFO
@@ -43,7 +43,6 @@ eegdash/features/feature_bank/utils.py
 tests/test_api.py
 tests/test_challenge_kwargs.py
 tests/test_correctness.py
-tests/test_database.py
 tests/test_dataset.py
 tests/test_dataset_registration.py
 tests/test_eegdash.py

{eegdash-0.3.6.dev183416654 → eegdash-0.3.7.dev104}/tests/test_correctness.py

@@ -22,7 +22,7 @@ from braindecode.preprocessing import (
 )
 from braindecode.util import set_random_seeds
 from eegdash import EEGDashDataset
-from eegdash.preprocessing import hbn_ec_ec_reannotation
+from eegdash.hbn.preprocessing import hbn_ec_ec_reannotation
 
 cache_folder = get_config("MNE_DATA")
 if cache_folder is None:

{eegdash-0.3.6.dev183416654 → eegdash-0.3.7.dev104}/tests/test_dataset.py

@@ -3,7 +3,7 @@ from pathlib import Path
 
 import pytest
 
-from eegdash.api import EEGDash
+from eegdash.api import EEGDash, EEGDashDataset
 from eegdash.dataset import EEGChallengeDataset
 
 RELEASES = ["R1", "R2", "R3", "R4", "R5", "R6", "R7", "R8", "R9", "R10", "R11"]
@@ -117,3 +117,36 @@ def test_eeg_dash_integration(eeg_dash_instance, release="R5", mini=True):
     )
     raw = dataset_obj.datasets[0].raw
     assert raw is not None
+
+
+def test_eeg_dash_integration_warning():
+    """Test that EEGChallengeDataset emits the expected UserWarning on init."""
+    release = "R5"
+    mini = True
+    with pytest.warns(UserWarning) as record:
+        _ = EEGChallengeDataset(
+            release=release,
+            task="RestingState",
+            cache_dir=CACHE_DIR,
+            mini=mini,
+        )
+    # There may be multiple warnings, check that at least one matches expected text
+    found = any("EEG 2025 Competition Data Notice" in str(w.message) for w in record)
+    assert found, (
+        "Expected competition warning not found in warnings emitted by EEGChallengeDataset"
+    )
+
+
+def test_eeg_dashdataset():
+    """Test that EEGDashDataset emits the expected UserWarning on init."""
+    with pytest.warns(UserWarning) as record:
+        _ = EEGDashDataset(
+            dataset="ds005505",
+            task="RestingState",
+            cache_dir=CACHE_DIR,
+        )
+    # There may be multiple warnings, check that at least one matches expected text
+    found = any("EEG 2025 Competition Data Notice" in str(w.message) for w in record)
+    assert found, (
+        "Expected competition warning not found in warnings emitted by EEGChallengeDataset"
+    )

eegdash-0.3.6.dev183416654/eegdash/__init__.py

@@ -1,10 +0,0 @@
-from .api import EEGDash, EEGDashDataset
-from .dataset import EEGChallengeDataset
-from .utils import __init__mongo_client
-
-__init__mongo_client()
-
-
-__all__ = ["EEGDash", "EEGDashDataset", "EEGChallengeDataset"]
-
-__version__ = "0.3.6.dev183416654"

eegdash-0.3.6.dev183416654/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