eegdash 0.3.4.dev69__py3-none-any.whl → 0.3.5.dev77__py3-none-any.whl

eegdash/__init__.py

@@ -7,4 +7,4 @@ __init__mongo_client()
 
 __all__ = ["EEGDash", "EEGDashDataset", "EEGChallengeDataset"]
 
-__version__ = "0.3.4.dev69"
+__version__ = "0.3.5.dev77"

eegdash/api.py

@@ -9,6 +9,7 @@ import numpy as np
 import xarray as xr
 from dotenv import load_dotenv
 from joblib import Parallel, delayed
+from mne_bids import get_bids_path_from_fname, read_raw_bids
 from pymongo import InsertOne, UpdateOne
 from s3fs import S3FileSystem
 
@@ -34,6 +35,19 @@ class EEGDash:
 
     """
 
+    _ALLOWED_QUERY_FIELDS = {
+        "data_name",
+        "dataset",
+        "subject",
+        "task",
+        "session",
+        "run",
+        "modality",
+        "sampling_frequency",
+        "nchans",
+        "ntimes",
+    }
+
     def __init__(self, *, is_public: bool = True, is_staging: bool = False) -> None:
         """Create new instance of the EEGDash Database client.
 
@@ -71,34 +85,59 @@ class EEGDash:
             anon=True, client_kwargs={"region_name": "us-east-2"}
         )
 
-    def find(self, query: dict[str, Any], *args, **kwargs) -> list[Mapping[str, Any]]:
-        """Find records in the MongoDB collection that satisfy the given query.
+    def find(
+        self, query: dict[str, Any] = None, /, **kwargs
+    ) -> list[Mapping[str, Any]]:
+        """Find records in the MongoDB collection.
+
+        This method can be called in two ways:
+        1. With a pre-built MongoDB query dictionary (positional argument):
+           >>> eegdash.find({"dataset": "ds002718", "subject": {"$in": ["012", "013"]}})
+        2. With user-friendly keyword arguments for simple and multi-value queries:
+           >>> eegdash.find(dataset="ds002718", subject="012")
+           >>> eegdash.find(dataset="ds002718", subject=["012", "013"])
 
         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.
-        args:
-            Additional positional arguments for the MongoDB find() method; see
-            https://pymongo.readthedocs.io/en/stable/api/pymongo/collection.html#pymongo.collection.Collection.find
-        kwargs:
-            Additional keyword arguments for the MongoDB find() method.
+        query: dict, optional
+            A complete MongoDB query dictionary. This is a positional-only argument.
+        **kwargs:
+            Keyword arguments representing field-value pairs for the query.
+            Values can be single items (str, int) or lists of items for multi-search.
 
         Returns
         -------
         list:
             A list of DB records (string-keyed dictionaries) that match the query.
 
-        Example
-        -------
-        >>> eegdash = EEGDash()
-        >>> eegdash.find({"dataset": "ds002718", "subject": "012"})
+        Raises
+        ------
+        ValueError
+            If both a `query` dictionary and keyword arguments are provided.
 
         """
-        results = self.__collection.find(query, *args, **kwargs)
+        if query is not None and kwargs:
+            raise ValueError(
+                "Provide either a positional 'query' dictionary or keyword arguments, not both."
+            )
 
-        return [result for result in results]
+        final_query = {}
+        if query is not None:
+            final_query = query
+        elif kwargs:
+            final_query = self._build_query_from_kwargs(**kwargs)
+        else:
+            # By default, an empty query {} returns all documents.
+            # This can be dangerous, so we can either allow it or raise an error.
+            # Let's require an explicit query for safety.
+            raise ValueError(
+                "find() requires a query dictionary or at least one keyword argument. "
+                "To find all documents, use find({})."
+            )
+
+        results = self.__collection.find(final_query)
+
+        return list(results)
 
     def exist(self, query: dict[str, Any]) -> bool:
         """Return True if at least one record matches the query, else False.
@@ -184,6 +223,35 @@ class EEGDash:
 
         return record
 
+    def _build_query_from_kwargs(self, **kwargs) -> dict[str, Any]:
+        """Builds and validates a MongoDB query from user-friendly keyword arguments.
+
+        Translates list values into MongoDB's `$in` operator.
+        """
+        # 1. Validate that all provided keys are allowed for querying
+        unknown_fields = set(kwargs.keys()) - self._ALLOWED_QUERY_FIELDS
+        if unknown_fields:
+            raise ValueError(
+                f"Unsupported query field(s): {', '.join(sorted(unknown_fields))}. "
+                f"Allowed fields are: {', '.join(sorted(self._ALLOWED_QUERY_FIELDS))}"
+            )
+
+        # 2. Construct the query dictionary
+        query = {}
+        for key, value in kwargs.items():
+            if isinstance(value, (list, tuple)):
+                if not value:
+                    raise ValueError(
+                        f"Received an empty list for query parameter '{key}'. This is not supported."
+                    )
+                # If the value is a list, use the `$in` operator for multi-search
+                query[key] = {"$in": value}
+            else:
+                # Otherwise, it's a direct match
+                query[key] = value
+
+        return query
+
     def load_eeg_data_from_s3(self, s3path: str) -> xr.DataArray:
         """Load an EEGLAB .set file from an AWS S3 URI and return it as an xarray DataArray.
 
@@ -218,14 +286,15 @@ class EEGDash:
         Parameters
         ----------
         bids_file : str
-            Path to the file on the local filesystem.
+            Path to the BIDS-compliant file on the local filesystem.
 
         Notes
         -----
         Currently, only non-epoched .set files are supported.
 
         """
-        raw_object = mne.io.read_raw(bids_file)
+        bids_path = get_bids_path_from_fname(bids_file, verbose=False)
+        raw_object = read_raw_bids(bids_path=bids_path, verbose=False)
         eeg_data = raw_object.get_data()
 
         fs = raw_object.info["sfreq"]
@@ -521,8 +590,8 @@ class EEGDashDataset(BaseConcatDataset):
     def __init__(
         self,
         query: dict | None = None,
-        data_dir: str | list | None = None,
-        dataset: str | list | None = None,
+        cache_dir: str = "~/eegdash_cache",
+        dataset: str | None = None,
         description_fields: list[str] = [
             "subject",
             "session",
@@ -532,36 +601,55 @@ class EEGDashDataset(BaseConcatDataset):
             "gender",
             "sex",
         ],
-        cache_dir: str = "~/eegdash_cache",
         s3_bucket: str | None = None,
+        data_dir: str | None = None,
         eeg_dash_instance=None,
+        records: list[dict] | None = None,
         **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.
 
+
+        Querying Examples:
+        ------------------
+        # Find by single subject
+        >>> ds = EEGDashDataset(dataset="ds005505", subject="NDARCA153NKE")
+
+        # Find by a list of subjects and a specific task
+        >>> subjects = ["NDARCA153NKE", "NDARXT792GY8"]
+        >>> ds = EEGDashDataset(dataset="ds005505", subject=subjects, task="RestingState")
+
+        # Use a raw MongoDB query for advanced filtering
+        >>> raw_query = {"dataset": "ds005505", "subject": {"$in": subjects}}
+        >>> ds = EEGDashDataset(query=raw_query)
+
         Parameters
         ----------
         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
+            A raw MongoDB query dictionary. If provided, keyword arguments for filtering are ignored.
+        **kwargs : dict
+            Keyword arguments for filtering (e.g., `subject="X"`, `task=["T1", "T2"]`) and/or
+            arguments to be passed to the EEGDashBaseDataset constructor (e.g., `subject=...`).
+        cache_dir : str
+            A directory where the dataset will be cached locally.
+        data_dir : str | None
+            Optionally a string specifying a local BIDS dataset directory 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.
+        dataset : str | None
+            If data_dir is given, a name for the dataset 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.
-        cache_dir : str
-            A directory where the dataset will be cached locally.
         s3_bucket : str | None
             An optional S3 bucket URI (e.g., "s3://mybucket") to use instead of the
             default OpenNeuro bucket for loading data files
+        records : list[dict] | None
+            Optional list of pre-fetched metadata records. If provided, the dataset is
+            constructed directly from these records without querying MongoDB.
         kwargs : dict
             Additional keyword arguments to be passed to the EEGDashBaseDataset
             constructor.
@@ -569,20 +657,47 @@ class EEGDashDataset(BaseConcatDataset):
         """
         self.cache_dir = cache_dir
         self.s3_bucket = s3_bucket
-        self.eeg_dash = eeg_dash_instance or EEGDash()
-        _owns_client = eeg_dash_instance is None
+        self.eeg_dash = eeg_dash_instance
+        _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 query and query_kwargs:
+            raise ValueError(
+                "Provide either a 'query' dictionary or keyword arguments for filtering, not both."
+            )
 
         try:
-            if query:
-                datasets = self.find_datasets(query, description_fields, **kwargs)
+            if records is not None:
+                datasets = [
+                    EEGDashBaseDataset(
+                        record,
+                        self.cache_dir,
+                        self.s3_bucket,
+                        **base_dataset_kwargs,
+                    )
+                    for record in records
+                ]
             elif data_dir:
+                # This path loads from a local directory and is not affected by DB query logic
                 if isinstance(data_dir, str):
                     datasets = self.load_bids_dataset(
-                        dataset, data_dir, description_fields, s3_bucket, **kwargs
+                        dataset,
+                        data_dir,
+                        description_fields,
+                        s3_bucket,
+                        **base_dataset_kwargs,
                     )
                 else:
                     assert len(data_dir) == len(dataset), (
-                        "Number of datasets and their directories must match"
+                        "Number of datasets and directories must match"
                     )
                     datasets = []
                     for i, _ in enumerate(data_dir):
@@ -592,27 +707,28 @@ class EEGDashDataset(BaseConcatDataset):
                                 data_dir[i],
                                 description_fields,
                                 s3_bucket,
-                                **kwargs,
+                                **base_dataset_kwargs,
                             )
                         )
+            elif query or query_kwargs:
+                # This is the DB query path that we are improving
+                datasets = self.find_datasets(
+                    query=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
+                self.filesystem = S3FileSystem(
+                    anon=True, client_kwargs={"region_name": "us-east-2"}
+                )
             else:
                 raise ValueError(
-                    "Exactly one of 'query' or 'data_dir' must be provided."
+                    "You must provide either 'records', a 'data_dir', or a query/keyword arguments for filtering."
                 )
         finally:
-            # If we created the client, close it now that construction is done.
-            if _owns_client:
-                try:
-                    self.eeg_dash.close()
-                except Exception:
-                    # Don't let close errors break construction
-                    pass
-
-        self.filesystem = S3FileSystem(
-            anon=True, client_kwargs={"region_name": "us-east-2"}
-        )
-
-        self.eeg_dash.close()
+            if _owns_client and self.eeg_dash is not None:
+                self.eeg_dash.close()
 
         super().__init__(datasets)
 
@@ -630,7 +746,11 @@ class EEGDashDataset(BaseConcatDataset):
         return None
 
     def find_datasets(
-        self, query: dict[str, Any], description_fields: list[str], **kwargs
+        self,
+        query: dict[str, Any],
+        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
         given query and return them as a list of EEGDashBaseDataset objects.
@@ -652,7 +772,10 @@ class EEGDashDataset(BaseConcatDataset):
 
         """
         datasets: list[EEGDashBaseDataset] = []
-        for record in self.eeg_dash.find(query):
+
+        records = self.eeg_dash.find(query, **query_kwargs)
+
+        for record in records:
             description = {}
             for field in description_fields:
                 value = self.find_key_in_nested_dict(record, field)
@@ -664,7 +787,7 @@ class EEGDashDataset(BaseConcatDataset):
                     self.cache_dir,
                     self.s3_bucket,
                     description=description,
-                    **kwargs,
+                    **base_dataset_kwargs,
                 )
             )
         return datasets

eegdash/registry.py

@@ -1,52 +1,39 @@
 from __future__ import annotations
 
-import csv
 from pathlib import Path
 from typing import Any, Dict
 
+import pandas as pd
+from tabulate import tabulate
+
 
 def register_openneuro_datasets(
     summary_file: str | Path,
     *,
     base_class=None,
     namespace: Dict[str, Any] | None = None,
+    add_to_all: bool = True,
 ) -> Dict[str, type]:
-    """Dynamically create dataset classes from a summary file.
-
-    Parameters
-    ----------
-    summary_file : str | Path
-        Path to a CSV file where each line starts with the dataset identifier.
-    base_class : type | None
-        Base class for the generated datasets. If ``None``, defaults to
-        :class:`eegdash.api.EEGDashDataset`.
-    namespace : dict | None
-        Mapping where the new classes will be registered. Defaults to the
-        module's global namespace.
-
-    Returns
-    -------
-    dict
-        Mapping from class names to the generated classes.
-
-    """
+    """Dynamically create dataset classes from a summary file."""
     if base_class is None:
         from .api import EEGDashDataset as base_class  # lazy import
 
     summary_path = Path(summary_file)
     namespace = namespace if namespace is not None else globals()
+    module_name = namespace.get("__name__", __name__)
     registered: Dict[str, type] = {}
 
-    with summary_path.open() as f:
-        reader = csv.reader(f)
-        for row in reader:
-            if not row:
-                continue
-            dataset_id = row[0].strip()
-            if not dataset_id or dataset_id.startswith("#"):
-                continue
-            class_name = dataset_id.upper()
+    df = pd.read_csv(summary_path, comment="#", skip_blank_lines=True)
+    for _, row_series in df.iterrows():
+        row = row_series.tolist()
+        dataset_id = str(row[0]).strip()
+        if not dataset_id:
+            continue
+
+        class_name = dataset_id.upper()
 
+        # avoid zero-arg super() here
+        def make_init(_dataset: str):
             def __init__(
                 self,
                 cache_dir: str,
@@ -54,19 +41,96 @@ def register_openneuro_datasets(
                 s3_bucket: str | None = None,
                 **kwargs,
             ):
-                q = {"dataset": self._dataset}
+                q = {"dataset": _dataset}
                 if query:
                     q.update(query)
-                super().__init__(
-                    query=q, cache_dir=cache_dir, s3_bucket=s3_bucket, **kwargs
+                # call base_class.__init__ directly
+                base_class.__init__(
+                    self,
+                    query=q,
+                    cache_dir=cache_dir,
+                    s3_bucket=s3_bucket,
+                    **kwargs,
                 )
 
-            cls = type(
-                class_name,
-                (base_class,),
-                {"_dataset": dataset_id, "__init__": __init__},
-            )
-            namespace[class_name] = cls
-            registered[class_name] = cls
+            return __init__
+
+        init = make_init(dataset_id)
+
+        doc = f"""Create an instance for OpenNeuro dataset ``{dataset_id}``.
+
+        {markdown_table(row_series)}
+
+        Parameters
+        ----------
+        cache_dir : str
+            Local cache directory.
+        query : dict | None
+            Extra Mongo query merged with ``{{'dataset': '{dataset_id}'}}``.
+        s3_bucket : str | None
+            Optional S3 bucket name.
+        **kwargs
+            Passed through to {base_class.__name__}.
+        """
+
+        init.__doc__ = doc
+
+        cls = type(
+            class_name,
+            (base_class,),
+            {
+                "_dataset": dataset_id,
+                "__init__": init,
+                "__doc__": doc,
+                "__module__": module_name,  #
+            },
+        )
+
+        namespace[class_name] = cls
+        registered[class_name] = cls
+
+        if add_to_all:
+            ns_all = namespace.setdefault("__all__", [])
+            if isinstance(ns_all, list) and class_name not in ns_all:
+                ns_all.append(class_name)
 
     return registered
+
+
+def markdown_table(row_series: pd.Series) -> str:
+    """Create a reStructuredText grid table from a pandas Series."""
+    if row_series.empty:
+        return ""
+
+    # Prepare the dataframe with user's suggested logic
+    df = (
+        row_series.to_frame()
+        .T.rename(
+            columns={
+                "n_subjects": "#Subj",
+                "nchans_set": "#Chan",
+                "n_tasks": "#Classes",
+                "sampling_freqs": "Freq(Hz)",
+                "duration_hours_total": "Duration(H)",
+            }
+        )
+        .reindex(
+            columns=[
+                "dataset",
+                "#Subj",
+                "#Chan",
+                "#Classes",
+                "Freq(Hz)",
+                "Duration(H)",
+            ]
+        )
+        .infer_objects(copy=False)
+        .fillna("")
+    )
+
+    # Use tabulate for the final rst formatting
+    table = tabulate(df, headers="keys", tablefmt="rst", showindex=False)
+
+    # 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}"

{eegdash-0.3.4.dev69.dist-info → eegdash-0.3.5.dev77.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.3.4.dev69
+Version: 0.3.5.dev77
 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
@@ -38,6 +38,8 @@ Requires-Dist: tqdm
 Requires-Dist: xarray
 Requires-Dist: h5io>=0.2.4
 Requires-Dist: pymatreader
+Requires-Dist: eeglabio
+Requires-Dist: tabulate
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"

{eegdash-0.3.4.dev69.dist-info → eegdash-0.3.5.dev77.dist-info}/RECORD

@@ -1,12 +1,12 @@
-eegdash/__init__.py,sha256=jE7WgvWD5alhbtOwzVZ0NCFWRdTx2_xEOrf40uPu8QY,240
-eegdash/api.py,sha256=OqOZ27GYURSAZwTQHSs0QcW_6Mq1i_5XHP6KMcihb8A,27295
+eegdash/__init__.py,sha256=kEfROPte5G7SgYy3bdM6r3KrWm_XuXcvS-tNPMVBIr4,240
+eegdash/api.py,sha256=M4QX93iqOneqO9zz6ruwGKpmU9h40K8lqYnICqAaj5o,32158
 eegdash/data_config.py,sha256=OS6ERO-jHrnEOfMJUehY7ieABdsRw_qWzOKJ4pzSfqw,1323
 eegdash/data_utils.py,sha256=_dycnPmGfTbYs7bc6edHxUn_m01dLYtp92_k44ffEoY,26475
 eegdash/dataset.py,sha256=ooLoxMFy2I8BY9gJl6ncTp_Gz-Rq0Z-o4NJyyomxLcU,2670
 eegdash/dataset_summary.csv,sha256=EfnPciglkf4Vgc8dDq_1x7Woeeze1II8vOhx60g4yhc,8670
 eegdash/mongodb.py,sha256=GD3WgA253oFgpzOHrYaj4P1mRjNtDMT5Oj4kVvHswjI,2006
 eegdash/preprocessing.py,sha256=7S_TTRKPKEk47tTnh2D6WExBt4cctAMxUxGDjJqq5lU,2221
-eegdash/registry.py,sha256=u2TqnMZPhnhItFupPbV50QGemeImnuc18wnEkKzLtL8,2118
+eegdash/registry.py,sha256=cxqX53GYyDvg5DkiqJkvjqHDPI72JTPlI4qVh2sILu8,3873
 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.4.dev69.dist-info/licenses/LICENSE,sha256=asisR-xupy_NrQBFXnx6yqXeZcYWLvbAaiETl25iXT0,931
-eegdash-0.3.4.dev69.dist-info/METADATA,sha256=ez_LqhgS-Lhf-GYlNnhi0ffE50YT3bvzlqNv8UUce5A,10340
-eegdash-0.3.4.dev69.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-eegdash-0.3.4.dev69.dist-info/top_level.txt,sha256=zavO69HQ6MyZM0aQMR2zUS6TAFc7bnN5GEpDpOpFZzU,8
-eegdash-0.3.4.dev69.dist-info/RECORD,,
+eegdash-0.3.5.dev77.dist-info/licenses/LICENSE,sha256=asisR-xupy_NrQBFXnx6yqXeZcYWLvbAaiETl25iXT0,931
+eegdash-0.3.5.dev77.dist-info/METADATA,sha256=1-0zRsLKzuM36yIDIlpbxTSCbCSp75XQoi2MC0C2pdA,10388
+eegdash-0.3.5.dev77.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+eegdash-0.3.5.dev77.dist-info/top_level.txt,sha256=zavO69HQ6MyZM0aQMR2zUS6TAFc7bnN5GEpDpOpFZzU,8
+eegdash-0.3.5.dev77.dist-info/RECORD,,