eegdash 0.3.6.dev97__tar.gz → 0.3.6.dev170720560__tar.gz

{eegdash-0.3.6.dev97/eegdash.egg-info → eegdash-0.3.6.dev170720560}/PKG-INFO

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

{eegdash-0.3.6.dev97 → eegdash-0.3.6.dev170720560}/docs/source/conf.py

@@ -31,6 +31,8 @@ extensions = [
     # "autoapi.extension",
     "numpydoc",
     "sphinx_gallery.gen_gallery",
+    # Generate sitemap.xml for search engines
+    "sphinx_sitemap",
 ]
 
 templates_path = ["_templates"]
@@ -45,6 +47,17 @@ html_favicon = "_static/eegdash_icon.png"
 html_title = "EEG Dash"
 html_short_title = "EEG Dash"
 html_css_files = ["custom.css"]
+html_js_files = [
+    (
+        "https://www.googletagmanager.com/gtag/js?id=G-CHY0V439ZQ",
+        {"async": "async"},
+    ),
+    "js/ga4.js",
+]
+
+# Required for sphinx-sitemap: set the canonical base URL of the site
+# Make sure this matches the actual published docs URL and ends with '/'
+html_baseurl = "https://sccn.github.io/eegdash/"
 
 html_theme_options = {
     "icon_links_label": "External Links",  # for screen reader
@@ -94,6 +107,9 @@ html_theme_options = {
 
 html_sidebars = {"api": [], "dataset_summary": [], "installation": []}
 
+# Copy extra files (e.g., robots.txt) to the output root
+html_extra_path = ["_extra"]
+
 
 # -- Extension configurations ------------------------------------------------
 autoclass_content = "both"
@@ -140,3 +156,7 @@ def setup(app):
     )
     if not os.path.exists(backreferences_dir):
         os.makedirs(backreferences_dir)
+
+
+# Configure sitemap URL format (omit .html where possible)
+sitemap_url_scheme = "{link}"

{eegdash-0.3.6.dev97 → eegdash-0.3.6.dev170720560}/eegdash/__init__.py

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

{eegdash-0.3.6.dev97 → eegdash-0.3.6.dev170720560}/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-0.3.6.dev97 → eegdash-0.3.6.dev170720560}/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-0.3.6.dev97 → eegdash-0.3.6.dev170720560/eegdash.egg-info}/PKG-INFO

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

{eegdash-0.3.6.dev97 → eegdash-0.3.6.dev170720560}/eegdash.egg-info/SOURCES.txt

@@ -43,6 +43,7 @@ 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.dev97 → eegdash-0.3.6.dev170720560}/eegdash.egg-info/requires.txt

@@ -22,6 +22,7 @@ eegdash[tests]
 
 [dev]
 pre-commit
+ipykernel
 
 [docs]
 sphinx
@@ -30,6 +31,7 @@ sphinx_gallery
 sphinx_rtd_theme
 pydata-sphinx-theme
 sphinx-autobuild
+sphinx-sitemap
 numpydoc
 memory_profiler
 ipython

{eegdash-0.3.6.dev97 → eegdash-0.3.6.dev170720560}/pyproject.toml

@@ -67,7 +67,8 @@ tests = [
     'pytest-benchmark',
 ]
 dev = [
-  "pre-commit"
+  "pre-commit",
+  "ipykernel"
 ]
 
 docs = [
@@ -77,6 +78,7 @@ docs = [
   "sphinx_rtd_theme",
   "pydata-sphinx-theme",
   "sphinx-autobuild",
+  "sphinx-sitemap",
   "numpydoc",
   "memory_profiler",
   "ipython",

{eegdash-0.3.6.dev97 → eegdash-0.3.6.dev170720560}/tests/test_offline.py

@@ -12,7 +12,9 @@ def test_dataset_loads_without_eegdash(monkeypatch):
     """Dataset should load from records without contacting network resources."""
     eeg_dash = EEGDash()
 
-    records = eeg_dash.find(subject="NDARAC350XUM", task="RestingState")
+    records = eeg_dash.find(
+        dataset="ds005509", subject="NDARAC350XUM", task="RestingState"
+    )
 
     # test with internet
     dataset_internet = EEGDashDataset(
@@ -24,14 +26,14 @@ def test_dataset_loads_without_eegdash(monkeypatch):
     # Monkeypatch any network calls inside EEGDashDataset to raise if called
     monkeypatch.setattr(
         EEGDashDataset,
-        "find_datasets",
+        "_find_datasets",
         lambda *args, **kwargs: pytest.skip(
             "Skipping network download in offline test"
         ),
     )
     monkeypatch.setattr(
         EEGDashDataset,
-        "find_datasets",
+        "_find_datasets",
         lambda *args, **kwargs: pytest.skip(
             "Skipping network download in offline test"
         ),
@@ -39,7 +41,7 @@ def test_dataset_loads_without_eegdash(monkeypatch):
     # TO-DO: discover way to do this pytest
 
     dataset_without_internet = EEGDashDataset(
-        records=records, cache_dir=CACHE_DIR, eeg_dash_instance=None
+        dataset="ds005509", records=records, cache_dir=CACHE_DIR, eeg_dash_instance=None
     )
 
     assert dataset_internet.datasets[0].raw == dataset_without_internet.datasets[0].raw