eegdash 0.3.6.dev182011805__tar.gz → 0.3.7.dev177024734__tar.gz

{eegdash-0.3.6.dev182011805/eegdash.egg-info → eegdash-0.3.7.dev177024734}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.3.6.dev182011805
+Version: 0.3.7.dev177024734
 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.dev182011805 → eegdash-0.3.7.dev177024734}/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,11 @@ html_favicon = "_static/eegdash_icon.png"
 html_title = "EEG Dash"
 html_short_title = "EEG Dash"
 html_css_files = ["custom.css"]
+html_js_files = []
+
+# 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 +101,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 +150,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.7.dev177024734/docs/source/dataset_summary.rst

@@ -0,0 +1,201 @@
+.. meta::
+   :hide_sidebar: true
+
+:html_theme.sidebar_secondary.remove:
+:html_theme.sidebar_primary.remove:
+
+.. _data_summary:
+
+EEGDash 
+========
+
+To leverage recent and ongoing advancements in large-scale computational methods and to ensure the preservation of scientific data generated from publicly funded research, the EEG-DaSh data archive will create a data-sharing resource for MEEG (EEG, MEG) data contributed by collaborators for machine learning (ML) and deep learning (DL) applications.
+
+The archive is currently still in :bdg-danger:`beta testing` mode, so be kind. 
+
+.. raw:: html
+
+  <figure class="eegdash-figure" style="margin: 0 0 1.25rem 0;">
+
+.. raw:: html
+  :file: ../build/dataset_bubble.html
+
+.. raw:: html
+
+  <figcaption class="eegdash-caption">
+    Figure: Dataset landscape. Each bubble represents a dataset: x-axis shows the number of records,
+    y-axis the number of subjects, bubble area encodes on-disk size, and color indicates sampling frequency band.
+    Hover for details and use the legend to highlight groups.
+  </figcaption>
+  </figure>
+
+
+.. raw:: html
+
+  <figure class="eegdash-figure" style="margin: 1.0rem 0 0 0;">
+
+
+MEEG Datasets Table
+===================
+
+The data in EEG-DaSh originates from a collaboration involving 25 laboratories, encompassing 27,053 participants. This extensive collection includes MEEG data, which is a combination of EEG and MEG signals. The data is sourced from various studies conducted by these labs, 
+involving both healthy subjects and clinical populations with conditions such as ADHD, depression, schizophrenia, dementia, autism, and psychosis. Additionally, data spans different mental states like sleep, meditation, and cognitive tasks. 
+
+In addition, EEG-DaSh will incorporate a subset of the data converted from `NEMAR <https://nemar.org/>`__, which includes 330 MEEG BIDS-formatted datasets, further expanding the archive with well-curated, standardized neuroelectromagnetic data.
+
+.. raw:: html
+  :file: ../build/dataset_summary_table.html
+
+.. raw:: html
+
+  <figcaption class="eegdash-caption">
+    Table: Sortable catalogue of EEG‑DaSh datasets. Use the “Filters” button to open column filters;
+    click a column header to jump directly to a filter pane. The Total row is pinned at the bottom.
+    * means that we use the median value across multiple recordings in the dataset, and empty cells
+    when the metainformation is not extracted yet.
+  </figcaption>
+  </figure>
+
+.. raw:: html
+
+  <!-- jQuery + DataTables core -->
+  <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.datatables.net/v/bm/dt-1.13.4/datatables.min.css"/>
+  <script src="https://cdn.datatables.net/v/bm/dt-1.13.4/datatables.min.js"></script>
+
+  <!-- Buttons + SearchPanes (+ Select required by SearchPanes) -->
+  <link rel="stylesheet" href="https://cdn.datatables.net/buttons/2.4.2/css/buttons.dataTables.min.css">
+  <script src="https://cdn.datatables.net/buttons/2.4.2/js/dataTables.buttons.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.datatables.net/select/1.7.0/css/select.dataTables.min.css">
+  <link rel="stylesheet" href="https://cdn.datatables.net/searchpanes/2.3.1/css/searchPanes.dataTables.min.css">
+  <script src="https://cdn.datatables.net/select/1.7.0/js/dataTables.select.min.js"></script>
+  <script src="https://cdn.datatables.net/searchpanes/2.3.1/js/dataTables.searchPanes.min.js"></script>
+
+  <style>
+    /* Styling for the Total row (placed in tfoot) */
+    table.sd-table tfoot td {
+      font-weight: 600;
+      border-top: 2px solid rgba(0,0,0,0.2);
+      background: #f9fafb;
+      /* Match body cell padding to keep perfect alignment */
+      padding: 8px 10px !important;
+      vertical-align: middle;
+    }
+
+    /* Right-align numeric-like columns (2..8) consistently for body & footer */
+    table.sd-table tbody td:nth-child(n+2),
+    table.sd-table tfoot td:nth-child(n+2) {
+      text-align: right;
+    }
+    /* Keep first column (Dataset/Total) left-aligned */
+    table.sd-table tbody td:first-child,
+    table.sd-table tfoot td:first-child {
+      text-align: left;
+    }
+  </style>
+
+  <script>
+  // Helper: robustly extract values for SearchPanes when needed
+  function tagsArrayFromHtml(html) {
+    if (html == null) return [];
+    // If it's numeric or plain text, just return as a single value
+    if (typeof html === 'number') return [String(html)];
+    if (typeof html === 'string' && html.indexOf('<') === -1) return [html.trim()];
+    // Else parse any .tag elements inside HTML
+    var tmp = document.createElement('div');
+    tmp.innerHTML = html;
+    var tags = Array.from(tmp.querySelectorAll('.tag')).map(function(el){
+      return (el.textContent || '').trim();
+    });
+    return tags.length ? tags : [tmp.textContent.trim()];
+  }
+
+  // Helper: parse human-readable sizes like "4.31 GB" into bytes (number)
+  function parseSizeToBytes(text) {
+    if (!text) return 0;
+    var s = String(text).trim();
+    var m = s.match(/([\d,.]+)\s*(TB|GB|MB|KB|B)/i);
+    if (!m) return 0;
+    var value = parseFloat(m[1].replace(/,/g, ''));
+    var unit = m[2].toUpperCase();
+    var factor = { B:1, KB:1024, MB:1024**2, GB:1024**3, TB:1024**4 }[unit] || 1;
+    return value * factor;
+  }
+
+  $(function () {
+    // 1) Move the "Total" row into <tfoot> so sorting/filtering never moves it
+    $('.sortable').each(function(){
+      var $t = $(this);
+      var $tbody = $t.find('tbody');
+      var $total = $tbody.find('tr').filter(function(){
+        return $(this).find('td').eq(0).text().trim() === 'Total';
+      });
+      if ($total.length) {
+        var $tfoot = $t.find('tfoot');
+        if (!$tfoot.length) $tfoot = $('<tfoot/>').appendTo($t);
+        $total.appendTo($tfoot);
+      }
+    });
+
+    // 2) Initialize DataTable with SearchPanes button
+    var FILTER_COLS = [1,2,3,4,5,6];
+    // Detect the index of the size column by header text
+    var sizeIdx = (function(){
+      var idx = -1;
+      $('.sortable thead th').each(function(i){
+        var t = $(this).text().trim().toLowerCase();
+        if (t === 'size on disk' || t === 'size') idx = i;
+      });
+      return idx;
+    })();
+
+    var table = $('.sortable').DataTable({
+      dom: 'Blfrtip',
+      paging: false,
+      searching: true,
+      info: false,
+      language: {
+        search: 'Filter dataset:',
+        searchPanes: { collapse: { 0: 'Filters', _: 'Filters (%d)' } }
+      },
+      buttons: [{
+        extend: 'searchPanes',
+        text: 'Filters',
+        config: { cascadePanes: true, viewTotal: true, layout: 'columns-4', initCollapsed: false }
+      }],
+      columnDefs: (function(){
+        var defs = [
+          { searchPanes: { show: true }, targets: FILTER_COLS }
+        ];
+        if (sizeIdx !== -1) {
+          defs.push({
+            targets: sizeIdx,
+            render: function(data, type) {
+              if (type === 'sort' || type === 'type') {
+                return parseSizeToBytes(data);
+              }
+              return data;
+            }
+          });
+        }
+        return defs;
+      })()
+    });
+
+    // 3) UX: click a header to open the relevant filter pane
+    $('.sortable thead th').each(function (i) {
+      if ([1,2,3,4].indexOf(i) === -1) return;
+      $(this).css('cursor','pointer').attr('title','Click to filter this column');
+      $(this).on('click', function () {
+        table.button('.buttons-searchPanes').trigger();
+        setTimeout(function () {
+          var idx = [1,2,3,4].indexOf(i);
+          var $container = $(table.searchPanes.container());
+          var $pane = $container.find('.dtsp-pane').eq(idx);
+          var $title = $pane.find('.dtsp-title');
+          if ($title.length) $title.trigger('click');
+        }, 0);
+      });
+    });
+  });
+  </script>

{eegdash-0.3.6.dev182011805 → eegdash-0.3.7.dev177024734}/eegdash/__init__.py

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

{eegdash-0.3.6.dev182011805 → eegdash-0.3.7.dev177024734}/eegdash/api.py

@@ -6,15 +6,18 @@ 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
 
 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
@@ -693,9 +696,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 +708,10 @@ 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,
+        n_jobs: int = -1,
         **kwargs,
     ):
         """Create a new EEGDashDataset from a given query or local BIDS dataset directory
@@ -754,35 +757,54 @@ 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.
+        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.
 
         """
-        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
+
+        # Separate query kwargs from other kwargs passed to the BaseDataset constructor
+        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")
+
+        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"
+                "[EEGChallengeDataset] 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` 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()
             _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 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)
-
-        # Allow mixing raw DB query with additional keyword filters. Both will be
-        # merged by EEGDash.find() (logical AND), so we do not raise here.
-
         try:
             if records is not None:
                 self.records = records
@@ -795,42 +817,26 @@ 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)):
-                    datasets = self.load_bids_dataset(
-                        dataset=dataset
-                        if isinstance(dataset, str)
-                        else (dataset[0] if dataset else None),
-                        data_dir=data_dir,
+            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_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:
-                    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 +866,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 +893,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 +904,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,
                 )
@@ -917,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
@@ -931,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.dev182011805/eegdash/dataset.py → eegdash-0.3.7.dev177024734/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=dataset_parameters,
-            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.dev177024734/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.dev182011805 → eegdash-0.3.7.dev177024734}/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.dev182011805 → eegdash-0.3.7.dev177024734/eegdash.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.3.6.dev182011805
+Version: 0.3.7.dev177024734
 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.dev182011805 → eegdash-0.3.7.dev177024734}/eegdash.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ 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
@@ -43,6 +44,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.dev182011805 → eegdash-0.3.7.dev177024734}/eegdash.egg-info/requires.txt

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

{eegdash-0.3.6.dev182011805 → eegdash-0.3.7.dev177024734}/pyproject.toml

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

{eegdash-0.3.6.dev182011805 → eegdash-0.3.7.dev177024734}/tests/test_dataset_registration.py

@@ -16,9 +16,9 @@ def test_register_openneuro_datasets(tmp_path: Path):
     summary.write_text(
         "\n".join(
             [
-                "dataset_id,num_subjects,num_sessions,num_runs,num_channels,sampling_rate,duration",
-                "ds002718,18,18,1,74,250,14.844",
-                "ds000001,1,1,1,1,1,1",
+                "dataset,num_subjects,num_sessions,num_runs,num_channels,sampling_rate,duration,size",
+                "ds002718,18,18,1,74,250,14.844,1.2GB",
+                "ds000001,1,1,1,1,1,1,100MB",
             ]
         )
     )

{eegdash-0.3.6.dev182011805 → eegdash-0.3.7.dev177024734}/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

eegdash-0.3.6.dev182011805/docs/source/dataset_summary.rst

@@ -1,85 +0,0 @@
-.. meta::
-   :hide_sidebar: true
-
-:html_theme.sidebar_secondary.remove:
-:html_theme.sidebar_primary.remove:
-
-.. _data_summary:
-.. automodule:: eegdash.dataset
-
-.. currentmodule:: eegdash.dataset
-
-To leverage recent and ongoing advancements in large-scale computational methods and to ensure the preservation of scientific data generated from publicly funded research, the EEG-DaSh data archive will create a data-sharing resource for MEEG (EEG, MEG) data contributed by collaborators for machine learning (ML) and deep learning (DL) applications.
-
-The archive is currently still in :bdg-danger:`beta testing` mode, so be kind. 
-
-EEG Dash Datasets
-==================
-
-The data in EEG-DaSh originates from a collaboration involving 25 laboratories, encompassing 27,053 participants. This extensive collection includes MEEG data, which is a combination of EEG and MEG signals. The data is sourced from various studies conducted by these labs, involving both healthy subjects and clinical populations with conditions such as ADHD, depression, schizophrenia, dementia, autism, and psychosis. Additionally, data spans different mental states like sleep, meditation, and cognitive tasks. In addition, EEG-DaSh will incorporate a subset of the data converted from NEMAR, which includes 330 MEEG BIDS-formatted datasets, further expanding the archive with well-curated, standardized neuroelectromagnetic data.
-
-Columns definitions for the table below:
-   - **dataset**: Name of the dataset.
-   - **n_records**: Number of EEG records in the dataset.
-   - **n_subjects**: Number of subjects in the dataset.
-   - **n_tasks**: Number of experimental tasks in the dataset.
-   - **nchans_set**: Set of EEG channel counts used in the dataset.
-   - **sampling_freqs**: Set of sampling frequencies used in the dataset.
-   - **duration_hours_total**: Total duration of all recordings in hours.
-
-
-Datasets
-======================
-
-.. csv-table::
-   :file: ../build/dataset_summary.csv
-   :header-rows: 1
-   :class: sortable
-
-
-
-.. raw:: html
-   <style>
-     /* Make this page full-width and remove side padding */
-     :root {
-       --pst-page-max-width: 100%;
-       --pst-content-max-width: 100%;
-     }
-     .bd-main .bd-content .bd-article-container {
-       max-width: 100%;
-       padding-left: 0;
-       padding-right: 0;
-     }
-     /* Ensure the DataTable uses the full width */
-     table.sortable { width: 100% !important; }
-   </style>
-
-   <link href="https://cdn.datatables.net/v/bm/jq-3.7.0/dt-2.3.2/af-2.7.0/b-3.2.4/b-html5-3.2.4/cr-2.1.1/fh-4.0.3/r-3.0.5/datatables.min.css"
-         rel="stylesheet"
-         integrity="sha384-aemAM3yl2c0KAZZkR1b1AwMH2u3r1NHOppsl5i6Ny1L5pfqn7SDH52qdaa1TbyN9"
-         crossorigin="anonymous">
-
-   <script src="https://cdn.datatables.net/v/bm/jq-3.7.0/dt-2.3.2/af-2.7.0/b-3.2.4/b-html5-3.2.4/cr-2.1.1/fh-4.0.3/r-3.0.5/datatables.min.js"
-           integrity="sha384-CKcCNsP1rMRsJFtrN6zMWK+KIK/FjYiV/d8uOp0LZtbEVzbidk105YcuVncAhBR8"
-           crossorigin="anonymous"></script>
-
-   <script>
-     document.addEventListener('DOMContentLoaded', function () {
-       const tables = document.querySelectorAll('table.sortable');
-       tables.forEach(function (tbl) {
-         // Use the jQuery plugin that ships in the bundle
-         $(tbl).DataTable({
-           paging: false,
-           searching: false,
-           info: false,
-           ordering: true,
-           responsive: true,
-           fixedHeader: true,
-           // Avoid re-initialization if this script runs more than once
-           retrieve: true,
-           scrollX: true
-         });
-       });
-     });
-   </script>
-