eegdash 0.3.6__py3-none-any.whl → 0.3.6.dev99__py3-none-any.whl

eegdash/__init__.py

@@ -7,4 +7,4 @@ __init__mongo_client()
 
 __all__ = ["EEGDash", "EEGDashDataset", "EEGChallengeDataset"]
 
-__version__ = "0.3.6"
+__version__ = "0.3.6.dev99"

eegdash/api.py

@@ -6,9 +6,11 @@ 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
@@ -693,9 +695,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 +707,9 @@ 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,
         **kwargs,
     ):
         """Create a new EEGDashDataset from a given query or local BIDS dataset directory
@@ -754,34 +755,36 @@ 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.
         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
-        _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}
+        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")
 
-        # 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)
+        self.data_dir = self.cache_dir / self.query["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.
+        _owns_client = False
+        if self.eeg_dash is None and records is None:
+            self.eeg_dash = EEGDash()
+            _owns_client = True
 
         try:
             if records is not None:
@@ -795,42 +798,25 @@ 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)):
+            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(
-                        dataset=dataset
-                        if isinstance(dataset, str)
-                        else (dataset[0] if dataset else None),
-                        data_dir=data_dir,
+                        dataset=self.query["dataset"],
+                        data_dir=self.data_dir,
                         description_fields=description_fields,
                         s3_bucket=s3_bucket,
                         **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 +846,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 +873,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 +884,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,
                 )

eegdash/dataset.py

@@ -335,7 +335,7 @@ class EEGChallengeDataset(EEGDashDataset):
             s3_bucket = f"{s3_bucket}/{release}_L100_bdf"
 
         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.dist-info → eegdash-0.3.6.dev99.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.3.6
+Version: 0.3.6.dev99
 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.dist-info → eegdash-0.3.6.dev99.dist-info}/RECORD

@@ -1,12 +1,12 @@
-eegdash/__init__.py,sha256=98fKNGN_Q6JIg7jL9AQtMbxbGDjnzZ8FAroMiRY-7pA,234
-eegdash/api.py,sha256=yotN4vqurZAxVA4q_DK4z0mhh9P8sbpxKzvyxuRSkcQ,38538
+eegdash/__init__.py,sha256=XWizORotB9VyXTEYyeojm1OmzCw6OfkT1Em1o1pnA8U,240
+eegdash/api.py,sha256=_7Ne1uo9ozYgDewuNOGmu79600SJoAGXHHDgyD-eDVw,37460
 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=WoKVmPoBIiRNn5h5ICUMMg5uUa2cMrc5ymChdfYV_f4,9469
 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.dist-info/licenses/LICENSE,sha256=asisR-xupy_NrQBFXnx6yqXeZcYWLvbAaiETl25iXT0,931
-eegdash-0.3.6.dist-info/METADATA,sha256=jxpD8NJMnPwutQKPSXsL9LsBV5_miObbQy-luSTSUwQ,9919
-eegdash-0.3.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-eegdash-0.3.6.dist-info/top_level.txt,sha256=zavO69HQ6MyZM0aQMR2zUS6TAFc7bnN5GEpDpOpFZzU,8
-eegdash-0.3.6.dist-info/RECORD,,
+eegdash-0.3.6.dev99.dist-info/licenses/LICENSE,sha256=asisR-xupy_NrQBFXnx6yqXeZcYWLvbAaiETl25iXT0,931
+eegdash-0.3.6.dev99.dist-info/METADATA,sha256=EU7-axNmsF0t2UD9MLG-msef0oPZYyvsN5r4_xAWWzc,10052
+eegdash-0.3.6.dev99.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+eegdash-0.3.6.dev99.dist-info/top_level.txt,sha256=zavO69HQ6MyZM0aQMR2zUS6TAFc7bnN5GEpDpOpFZzU,8
+eegdash-0.3.6.dev99.dist-info/RECORD,,