eegdash 0.2.0__py3-none-any.whl → 0.2.1.dev178237806__py3-none-any.whl

eegdash/__init__.py

@@ -5,4 +5,4 @@ from .utils import __init__mongo_client
 __init__mongo_client()
 
 __all__ = ["EEGDash", "EEGDashDataset", "EEGChallengeDataset"]
-__version__ = "0.2.0"
+__version__ = "0.2.1.dev178237806"

eegdash/api.py

@@ -9,13 +9,14 @@ import numpy as np
 import xarray as xr
 from dotenv import load_dotenv
 from joblib import Parallel, delayed
-from pymongo import InsertOne, MongoClient, UpdateOne
+from pymongo import InsertOne, UpdateOne
 from s3fs import S3FileSystem
 
 from braindecode.datasets import BaseConcatDataset
 
 from .data_config import config as data_config
 from .data_utils import EEGBIDSDataset, EEGDashBaseDataset
+from .mongodb import MongoConnectionManager
 
 logger = logging.getLogger("eegdash")
 
@@ -55,6 +56,7 @@ class EEGDash:
         """
         self.config = data_config
         self.is_public = is_public
+        self.is_staging = is_staging
 
         if self.is_public:
             DB_CONNECTION_STRING = mne.utils.get_config("EEGDASH_DB_URI")
@@ -62,31 +64,15 @@ class EEGDash:
             load_dotenv()
             DB_CONNECTION_STRING = os.getenv("DB_CONNECTION_STRING")
 
-        self.__client = MongoClient(DB_CONNECTION_STRING)
-        self.__db = (
-            self.__client["eegdash"]
-            if not is_staging
-            else self.__client["eegdashstaging"]
+        # Use singleton to get MongoDB client, database, and collection
+        self.__client, self.__db, self.__collection = MongoConnectionManager.get_client(
+            DB_CONNECTION_STRING, is_staging
         )
-        self.__collection = self.__db["records"]
 
         self.filesystem = S3FileSystem(
             anon=True, client_kwargs={"region_name": "us-east-2"}
         )
 
-    # MongoDB Operations
-    # These methods provide a high-level interface to interact with the MongoDB
-    # collection, allowing users to find, add, and update EEG data records.
-    # - find:
-    # - exist:
-    # - add_request:
-    # - add:
-    # - update_request:
-    # - remove_field:
-    # - remove_field_from_db:
-    # - close: Close the MongoDB connection.
-    # - __del__: Destructor to close the MongoDB connection.
-
     def find(self, query: dict[str, Any], *args, **kwargs) -> list[Mapping[str, Any]]:
         """Find records in the MongoDB collection that satisfy the given query.
 
@@ -117,26 +103,48 @@ class EEGDash:
         return [result for result in results]
 
     def exist(self, query: dict[str, Any]) -> bool:
-        """Check if the given query matches any records in the MongoDB collection.
+        """Return True if at least one record matches the query, else False.
 
-        Note that currently only a limited set of query fields is allowed here.
+        This is a lightweight existence check that uses MongoDB's ``find_one``
+        instead of fetching all matching documents (which would be wasteful in
+        both time and memory for broad queries). Only a restricted set of
+        fields is accepted to avoid accidental full scans caused by malformed
+        or unsupported keys.
 
         Parameters
         ----------
-        query: dict
-            A dictionary that specifies the query to be executed; this is a reference
-            document that is used to match records in the MongoDB collection.
+        query : dict
+            Mapping of allowed field(s) to value(s). Allowed keys: ``data_name``
+            and ``dataset``. The query must not be empty.
 
         Returns
         -------
-        bool:
-            True if at least one record matches the query, False otherwise.
+        bool
+            True if at least one matching record exists; False otherwise.
+
+        Raises
+        ------
+        TypeError
+            If ``query`` is not a dict.
+        ValueError
+            If ``query`` is empty or contains unsupported field names.
 
         """
-        accepted_query_fields = ["data_name", "dataset"]
-        assert all(field in accepted_query_fields for field in query.keys())
-        sessions = self.find(query)
-        return len(sessions) > 0
+        if not isinstance(query, dict):
+            raise TypeError("query must be a dict")
+        if not query:
+            raise ValueError("query cannot be empty")
+
+        accepted_query_fields = {"data_name", "dataset"}
+        unknown = set(query.keys()) - accepted_query_fields
+        if unknown:
+            raise ValueError(
+                f"Unsupported query field(s): {', '.join(sorted(unknown))}. "
+                f"Allowed: {sorted(accepted_query_fields)}"
+            )
+
+        doc = self.__collection.find_one(query, projection={"_id": 1})
+        return doc is not None
 
     def _validate_input(self, record: dict[str, Any]) -> dict[str, Any]:
         """Internal method to validate the input record against the expected schema.
@@ -491,13 +499,24 @@ class EEGDash:
         return self.__collection
 
     def close(self):
-        """Close the MongoDB client connection."""
-        if hasattr(self, "_EEGDash__client"):
-            self.__client.close()
+        """Close the MongoDB client connection.
+
+        Note: Since MongoDB clients are now managed by a singleton,
+        this method no longer closes connections. Use close_all_connections()
+        class method to close all connections if needed.
+        """
+        # Individual instances no longer close the shared client
+        pass
+
+    @classmethod
+    def close_all_connections(cls):
+        """Close all MongoDB client connections managed by the singleton."""
+        MongoConnectionManager.close_all()
 
     def __del__(self):
         """Ensure connection is closed when object is deleted."""
-        self.close()
+        # No longer needed since we're using singleton pattern
+        pass
 
 
 class EEGDashDataset(BaseConcatDataset):
@@ -651,28 +670,6 @@ class EEGDashDataset(BaseConcatDataset):
             and included in the returned dataset description(s).
 
         """
-
-        def get_base_dataset_from_bids_file(
-            bids_dataset: EEGBIDSDataset,
-            bids_file: str,
-            eeg_dash_instance: EEGDash,
-            s3_bucket: str | None,
-        ) -> EEGDashBaseDataset:
-            """Instantiate a single EEGDashBaseDataset given a local BIDS file. Note
-            this does not actually load the data from disk, but will access the metadata.
-            """
-            record = eeg_dash_instance.load_eeg_attrs_from_bids_file(
-                bids_dataset, bids_file
-            )
-            description = {}
-            for field in description_fields:
-                value = self.find_key_in_nested_dict(record, field)
-                if value is not None:
-                    description[field] = value
-            return EEGDashBaseDataset(
-                record, self.cache_dir, s3_bucket, description=description, **kwargs
-            )
-
         bids_dataset = EEGBIDSDataset(
             data_dir=data_dir,
             dataset=dataset,
@@ -680,11 +677,41 @@ class EEGDashDataset(BaseConcatDataset):
         eeg_dash_instance = EEGDash()
         try:
             datasets = Parallel(n_jobs=-1, prefer="threads", verbose=1)(
-                delayed(get_base_dataset_from_bids_file)(
-                    bids_dataset, bids_file, eeg_dash_instance, s3_bucket
+                delayed(self.get_base_dataset_from_bids_file)(
+                    bids_dataset=bids_dataset,
+                    bids_file=bids_file,
+                    eeg_dash_instance=eeg_dash_instance,
+                    s3_bucket=s3_bucket,
+                    description_fields=description_fields,
                 )
                 for bids_file in bids_dataset.get_files()
             )
             return datasets
         finally:
             eeg_dash_instance.close()
+
+    def get_base_dataset_from_bids_file(
+        self,
+        bids_dataset: EEGBIDSDataset,
+        bids_file: str,
+        eeg_dash_instance: EEGDash,
+        s3_bucket: str | None,
+        description_fields: list[str],
+    ) -> EEGDashBaseDataset:
+        """Instantiate a single EEGDashBaseDataset given a local BIDS file. Note
+        this does not actually load the data from disk, but will access the metadata.
+        """
+        record = eeg_dash_instance.load_eeg_attrs_from_bids_file(
+            bids_dataset, bids_file
+        )
+        description = {}
+        for field in description_fields:
+            value = self.find_key_in_nested_dict(record, field)
+            if value is not None:
+                description[field] = value
+        return EEGDashBaseDataset(
+            record,
+            self.cache_dir,
+            s3_bucket,
+            description=description,
+        )

eegdash/dataset.py

@@ -5,8 +5,9 @@ class EEGChallengeDataset(EEGDashDataset):
     def __init__(
         self,
         release: str = "R5",
+        query: dict | None = None,
         cache_dir: str = ".eegdash_cache",
-        s3_bucket: str | None = "s3://nmdatasets/NeurIPS25/R5_L100",
+        s3_bucket: str | None = "s3://nmdatasets/NeurIPS25/",
         **kwargs,
     ):
         """Create a new EEGDashDataset from a given query or local BIDS dataset directory
@@ -15,27 +16,19 @@ class EEGChallengeDataset(EEGDashDataset):
 
         Parameters
         ----------
+        release: str
+            Release name. Can be one of ["R1", ..., "R11"]
         query : dict | None
-            Optionally a dictionary that specifies the query to be executed; see
-            EEGDash.find() for details on the query format.
-        data_dir : str | list[str] | None
-            Optionally a string or a list of strings specifying one or more local
-            BIDS dataset directories from which to load the EEG data files. Exactly one
-            of query or data_dir must be provided.
-        dataset : str | list[str] | None
-            If data_dir is given, a name or list of names for for the dataset(s) to be loaded.
-        description_fields : list[str]
-            A list of fields to be extracted from the dataset records
-            and included in the returned data description(s). Examples are typical
-            subject metadata fields such as "subject", "session", "run", "task", etc.;
-            see also data_config.description_fields for the default set of fields.
+            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 EEGDashBaseDataset
+            Additional keyword arguments to be passed to the EEGDashDataset
             constructor.
 
         """
@@ -52,9 +45,25 @@ class EEGChallengeDataset(EEGDashDataset):
             "R2": "ds005506",
             "R1": "ds005505",
         }
+
+        self.release = release
+        if release not in dsnumber_release_map:
+            raise ValueError(f"Unknown release: {release}")
+
+        dataset = dsnumber_release_map[release]
+        if query is None:
+            query = {"dataset": dataset}
+        elif "dataset" not in query:
+            query["dataset"] = dataset
+        elif query["dataset"] != dataset:
+            raise ValueError(
+                f"Query dataset {query['dataset']} does not match the release {release} "
+                f"which corresponds to dataset {dataset}."
+            )
+
         super().__init__(
-            query={"dataset": dsnumber_release_map[release]},
+            query=query,
             cache_dir=cache_dir,
-            s3_bucket=s3_bucket,
+            s3_bucket=f"{s3_bucket}/{release}_L100",
             **kwargs,
         )

eegdash/mongodb.py

@@ -0,0 +1,66 @@
+import threading
+
+from pymongo import MongoClient
+
+# MongoDB Operations
+# These methods provide a high-level interface to interact with the MongoDB
+# collection, allowing users to find, add, and update EEG data records.
+# - find:
+# - exist:
+# - add_request:
+# - add:
+# - update_request:
+# - remove_field:
+# - remove_field_from_db:
+# - close: Close the MongoDB connection.
+# - __del__: Destructor to close the MongoDB connection.
+
+
+class MongoConnectionManager:
+    """Singleton class to manage MongoDB client connections."""
+
+    _instances = {}
+    _lock = threading.Lock()
+
+    @classmethod
+    def get_client(cls, connection_string: str, is_staging: bool = False):
+        """Get or create a MongoDB client for the given connection string and staging flag.
+
+        Parameters
+        ----------
+        connection_string : str
+            The MongoDB connection string
+        is_staging : bool
+            Whether to use staging database
+
+        Returns
+        -------
+        tuple
+            A tuple of (client, database, collection)
+
+        """
+        # Create a unique key based on connection string and staging flag
+        key = (connection_string, is_staging)
+
+        if key not in cls._instances:
+            with cls._lock:
+                # Double-check pattern to avoid race conditions
+                if key not in cls._instances:
+                    client = MongoClient(connection_string)
+                    db_name = "eegdashstaging" if is_staging else "eegdash"
+                    db = client[db_name]
+                    collection = db["records"]
+                    cls._instances[key] = (client, db, collection)
+
+        return cls._instances[key]
+
+    @classmethod
+    def close_all(cls):
+        """Close all MongoDB client connections."""
+        with cls._lock:
+            for client, _, _ in cls._instances.values():
+                try:
+                    client.close()
+                except Exception:
+                    pass
+            cls._instances.clear()

eegdash/utils.py

@@ -1,11 +1,11 @@
-def __init__mongo_client():
-    from mne.utils import get_config, set_config
+from mne.utils import get_config, set_config, use_log_level
 
-    if get_config("EEGDASH_DB_URI") is None:
-        # Set the default MongoDB URI for EEGDash
-        # This is a placeholder and should be replaced with your actual MongoDB URI
 
-        set_config(
-            "EEGDASH_DB_URI",
-            "mongodb+srv://eegdash-user:mdzoMjQcHWTVnKDq@cluster0.vz35p.mongodb.net/?retryWrites=true&w=majority&appName=Cluster0",
-        )
+def __init__mongo_client():
+    with use_log_level("ERROR"):
+        if get_config("EEGDASH_DB_URI") is None:
+            set_config(
+                "EEGDASH_DB_URI",
+                "mongodb+srv://eegdash-user:mdzoMjQcHWTVnKDq@cluster0.vz35p.mongodb.net/?retryWrites=true&w=majority&appName=Cluster0",
+                set_env=True,
+            )

{eegdash-0.2.0.dist-info → eegdash-0.2.1.dev178237806.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.2.0
+Version: 0.2.1.dev178237806
 Summary: EEG data for machine learning
 Author-email: Young Truong <dt.young112@gmail.com>, Arnaud Delorme <adelorme@gmail.com>, Bruno Aristimunha <b.aristimunha@gmail.com>
 License: GNU General Public License
@@ -43,7 +43,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >3.10
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: braindecode>=1.0
@@ -63,6 +63,7 @@ Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
 Requires-Dist: codecov; extra == "tests"
 Requires-Dist: pytest_cases; extra == "tests"
+Requires-Dist: pytest-benchmark; extra == "tests"
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == "dev"
 Provides-Extra: docs
@@ -164,7 +165,3 @@ EEG-DaSh is a collaborative initiative between the United States and Israel, sup
 
 
 
-python3 -m pip install --upgrade build
-python3 -m build
-python3 -m pip install --upgrade twine
-python3 -m twine upload --repository eegdash dist/*

{eegdash-0.2.0.dist-info → eegdash-0.2.1.dev178237806.dist-info}/RECORD

@@ -1,10 +1,11 @@
-eegdash/__init__.py,sha256=nMBZrB4bJs79rl9TZ_x-IVPNTHYJS6V55Pus9fErB5E,232
-eegdash/api.py,sha256=1mbufz6qgujrY_9V2GWUP4Eqel_q4ns9XVrmbGcSJG0,25776
+eegdash/__init__.py,sha256=5WP-O-5EjRXkQ2BZAn_KKMPeMyWezCmWf5sYLb-dihE,245
+eegdash/api.py,sha256=IQ0c26g7TnqzXv6lqlvMB9EHlobiTrK0YpiDa7ShcrE,26786
 eegdash/data_config.py,sha256=OS6ERO-jHrnEOfMJUehY7ieABdsRw_qWzOKJ4pzSfqw,1323
 eegdash/data_utils.py,sha256=mR0TtERYIefakGQ98jwAeeRVKSNDU9eBlUoH1AY9tnc,23663
-eegdash/dataset.py,sha256=qXcE4JxxYj89VQ84sKmq7kGcunZqt1pp5wz7a62j_OQ,2460
+eegdash/dataset.py,sha256=NK5CVGtHvGNlhdbZPaRUWtyLBDxUlyiSz-ot3BrxHQE,2443
+eegdash/mongodb.py,sha256=GD3WgA253oFgpzOHrYaj4P1mRjNtDMT5Oj4kVvHswjI,2006
 eegdash/preprocessing.py,sha256=wvqAO8UgDoQQz7xjVykrl4V8AawS4tpKR4Vrr_9BovY,2230
-eegdash/utils.py,sha256=ZxVW4ll5MaSZ_ht1L5p7YJxOtYi3b0547oa5W_jbH4A,450
+eegdash/utils.py,sha256=wU9CBQZLW_LIQIBwhgQm5bU4X-rSsVNPdeF2iE4QGJ4,410
 eegdash/features/__init__.py,sha256=484CLxpPifc8ZQfeM8jWZLvtVKljCxn3qqlUCaq-Yxk,1284
 eegdash/features/datasets.py,sha256=kU1DO70ArSIy-LF1hHD2NN4iT-kJrI0mVpSkyV_OSeI,18301
 eegdash/features/decorators.py,sha256=v0qaJz_dcX703p1fvFYbAIXmwK3d8naYGlq7fRVKn_w,1313
@@ -20,8 +21,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.2.0.dist-info/licenses/LICENSE,sha256=KykUD4H3kw3HLz5bZ0kxMWwZotnk8rhkfCCerGyX2sk,855
-eegdash-0.2.0.dist-info/METADATA,sha256=GhxMc7p2HvTZo9lZFjBX1tJ70VeMlMnaYBhvpqw0iG8,10220
-eegdash-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-eegdash-0.2.0.dist-info/top_level.txt,sha256=zavO69HQ6MyZM0aQMR2zUS6TAFc7bnN5GEpDpOpFZzU,8
-eegdash-0.2.0.dist-info/RECORD,,
+eegdash-0.2.1.dev178237806.dist-info/licenses/LICENSE,sha256=KykUD4H3kw3HLz5bZ0kxMWwZotnk8rhkfCCerGyX2sk,855
+eegdash-0.2.1.dev178237806.dist-info/METADATA,sha256=dn351VNZC1rthL5pYZejIE9ouYek-mp6ZbatrBlKm1k,10137
+eegdash-0.2.1.dev178237806.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+eegdash-0.2.1.dev178237806.dist-info/top_level.txt,sha256=zavO69HQ6MyZM0aQMR2zUS6TAFc7bnN5GEpDpOpFZzU,8
+eegdash-0.2.1.dev178237806.dist-info/RECORD,,