eegdash 0.4.0.dev153__tar.gz → 0.4.0.dev171__tar.gz

{eegdash-0.4.0.dev153/eegdash.egg-info → eegdash-0.4.0.dev171}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.4.0.dev153
+Version: 0.4.0.dev171
 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

{eegdash-0.4.0.dev153 → eegdash-0.4.0.dev171}/docs/source/api/api_core.rst

@@ -76,4 +76,4 @@ API Reference
    hbn
    mongodb
    paths
-   utils
+   utils

{eegdash-0.4.0.dev153 → eegdash-0.4.0.dev171}/docs/source/conf.py

@@ -12,13 +12,15 @@ from sphinx.util import logging
 from sphinx_gallery.sorting import ExplicitOrder, FileNameSortKey
 from tabulate import tabulate
 
+sys.path.insert(0, os.path.abspath(".."))
+
 import eegdash
 
 # -- Project information -----------------------------------------------------
 
 project = "EEG Dash"
 copyright = f"2025–{datetime.now(tz=timezone.utc).year}, {project} Developers"
-author = "Arnaud Delorme"
+author = "Bruno Aristimunha and Arnaud Delorme"
 release = eegdash.__version__
 version = ".".join(release.split(".")[:2])
 
@@ -44,6 +46,7 @@ extensions = [
     "sphinx_sitemap",
     "sphinx_copybutton",
     "sphinx.ext.graphviz",
+    "sphinx_time_estimation",
 ]
 
 templates_path = ["_templates"]
@@ -103,8 +106,8 @@ html_theme_options = {
     "navbar_end": ["theme-switcher", "navbar-icon-links"],
     "footer_start": ["copyright"],
     "logo": {
-        "image_light": "_static/eegdash_long.png",
-        "image_dark": "_static/eegdash_long.png",
+        "image_light": "_static/eegdash_long_white.svg",
+        "image_dark": "_static/eegdash_long_dark.svg",
         "alt_text": "EEG Dash Logo",
     },
     "external_links": [

{eegdash-0.4.0.dev153 → eegdash-0.4.0.dev171}/docs/source/dataset_summary/bubble.rst

@@ -1,3 +1,5 @@
+.. title:: Dataset landscape
+
 .. rubric:: Dataset landscape
 
 .. raw:: html

{eegdash-0.4.0.dev153 → eegdash-0.4.0.dev171}/docs/source/dataset_summary/kde.rst

@@ -1,4 +1,6 @@
-.. rubric:: Participant Distribution by Modality
+.. title:: Participant Distribution by Modality
+
+.. rubric:: Distribution of Sample Sizes Varies by Experimental Modality
 
 .. raw:: html
 

eegdash-0.4.0.dev171/docs/source/dataset_summary/sankey.rst

@@ -0,0 +1,20 @@
+.. title:: Dataset flow
+
+.. rubric:: Sankey diagrams of EEGDash Datasets by Population, Modality, and Cognitive Domain
+
+.. raw:: html
+
+   <figure class="eegdash-figure" style="margin: 0 0 1.25rem 0;">
+
+.. raw:: html
+   :file: ../_static/dataset_generated/dataset_sankey.html
+
+.. raw:: html
+
+   <figcaption class="eegdash-caption">
+     Figure: Dataset flow across population, modality, and cognitive domain.
+     Link thickness is proportional to the total number of subjects, and the tooltip
+     reports both subject and dataset counts. Hover and click legend entries to
+     explore specific segments.
+   </figcaption>
+   </figure>

eegdash-0.4.0.dev171/docs/source/dataset_summary/table.rst

@@ -0,0 +1,27 @@
+.. title:: EEG Datasets Table
+
+.. rubric:: EEG Datasets Table
+
+The data in EEG-DaSh originates from a collaboration involving 25 laboratories, encompassing 27,053 participants. This extensive collection includes M-EEG 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
+
+   <figure class="eegdash-figure" style="margin: 0 0 1.25rem 0;">
+
+.. raw:: html
+   :file: ../_static/dataset_generated/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>
+
+Pathology, modality, and dataset type now surface as consistent color-coded tags so you can scan the table at a glance.

{eegdash-0.4.0.dev153 → eegdash-0.4.0.dev171}/docs/source/dataset_summary.rst

@@ -10,13 +10,11 @@
 
 .. rst-class:: dataset-summary-article
 
-Datasets 
-=========
+Datasets Catalog
+================
 
 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
 
    <script src="https://cdn.plot.ly/plotly-3.1.0.min.js"></script>
@@ -27,10 +25,16 @@ The archive is currently still in :bdg-danger:`beta testing` mode, so be kind.
 
       .. include:: dataset_summary/table.rst
 
-   .. tab-item:: Participant KDE
+   .. tab-item:: Participant Distribution
 
       .. include:: dataset_summary/kde.rst
 
-   .. tab-item:: Landscape
+   .. tab-item:: Dataset Flow
+
+      .. include:: dataset_summary/sankey.rst
+
+   .. tab-item:: Scatter of Sample Size vs. Recording Duration
 
       .. include:: dataset_summary/bubble.rst
+
+The archive is currently still in :bdg-danger:`beta testing` mode, so be kind. 

eegdash-0.4.0.dev171/docs/source/index.rst

@@ -0,0 +1,86 @@
+:html_theme.sidebar_secondary.remove: true
+
+EEGDASH Homepage
+=================
+
+.. title:: EEG Dash
+
+
+EEG Dash Homepage
+==================
+
+.. raw:: html
+
+   <style type="text/css">h1 {display:none;}</style>
+
+.. raw:: html
+
+   <h1 class="eegdash-hero__title">EEG Dash</h1>
+
+
+.. image:: _static/logos/eegdash.svg
+    :alt: EEG Dash Logo
+    :class: logo mainlogo only-dark
+    :align: center
+    :scale: 50%
+
+.. image:: _static/logos/eegdash.svg
+    :alt: EEG Dash Logo
+    :class: logo mainlogo only-light
+    :align: center
+    :scale: 50%
+
+.. rst-class:: h4 text-center font-weight-light my-4
+
+   The EEG-DaSh data archive is a data-sharing resource for MEEG (EEG, MEG) data, enabling 
+   large-scale computational advancements to preserve and share scientific data from publicly funded 
+   research for machine learning and deep learning applications.
+
+.. rst-class:: text-center
+
+    The "DaSh" in EEG-DaSh stands for **Data Share**.
+
+    The EEG-DaSh data archive is a collaborative effort led by the University of California, San Diego (UCSD) and Ben-Gurion University of the Negev (BGU) and partially funded by the National Science Foundation (NSF). All are welcome to contribute to the https://github.com/sccn/EEGDash project.
+
+    The archive is currently still in :bdg-danger:`beta testing` mode, so be kind. 
+
+.. raw:: html
+
+    <h2 style="text-align: center;">Institutions</h2>
+
+
+.. image:: _static/logos/ucsd_white.svg
+    :alt: UCSD
+    :class: logo mainlogo only-dark flex-logo
+    :width: 45%
+    :align: left
+
+    
+.. image:: _static/logos/ucsd_dark.svg
+    :alt: UCSD
+    :class: logo mainlogo only-light flex-logo
+    :align: left
+    :width: 45%
+    
+
+.. image:: _static/logos/bgu_dark.svg
+    :alt: Ben-Gurion University of the Negev (BGU)
+    :class: logo mainlogo only-dark flex-logo
+    :align: right
+    :width: 40%
+
+.. image:: _static/logos/bgu_white.svg
+    :alt: Ben-Gurion University of the Negev (BGU)
+    :class: logo mainlogo only-light flex-logo
+    :align: right
+    :width: 40%
+
+
+.. toctree::
+   :hidden:
+
+   Installing <install/install>
+   User Guide <user_guide>
+   API <api/api>
+   Dataset Catalog <dataset_summary>
+   Examples <generated/auto_examples/index>

{eegdash-0.4.0.dev153 → eegdash-0.4.0.dev171}/eegdash/__init__.py

@@ -18,4 +18,4 @@ _init_mongo_client()
 
 __all__ = ["EEGDash", "EEGDashDataset", "EEGChallengeDataset", "preprocessing"]
 
-__version__ = "0.4.0.dev153"
+__version__ = "0.4.0.dev171"

{eegdash-0.4.0.dev153 → eegdash-0.4.0.dev171}/eegdash/api.py

@@ -212,17 +212,22 @@ class EEGDash:
         return doc is not None
 
     def _validate_input(self, record: dict[str, Any]) -> dict[str, Any]:
-        """Internal method to validate the input record against the expected schema.
+        """Validate the input record against the expected schema.
 
         Parameters
         ----------
-        record: dict
+        record : dict
             A dictionary representing the EEG data record to be validated.
 
         Returns
         -------
-        dict:
-            Returns the record itself on success, or raises a ValueError if the record is invalid.
+        dict
+            The record itself on success.
+
+        Raises
+        ------
+        ValueError
+            If the record is missing required keys or has values of the wrong type.
 
         """
         input_types = {
@@ -252,20 +257,44 @@ class EEGDash:
         return record
 
     def _build_query_from_kwargs(self, **kwargs) -> dict[str, Any]:
-        """Internal helper to build a validated MongoDB query from keyword args.
+        """Build a validated MongoDB query from keyword arguments.
+
+        This delegates to the module-level builder used across the package.
+
+        Parameters
+        ----------
+        **kwargs
+            Keyword arguments to convert into a MongoDB query.
+
+        Returns
+        -------
+        dict
+            A MongoDB query dictionary.
 
-        This delegates to the module-level builder used across the package and
-        is exposed here for testing and convenience.
         """
         return build_query_from_kwargs(**kwargs)
 
-    # --- Query merging and conflict detection helpers ---
-    def _extract_simple_constraint(self, query: dict[str, Any], key: str):
+    def _extract_simple_constraint(
+        self, query: dict[str, Any], key: str
+    ) -> tuple[str, Any] | None:
         """Extract a simple constraint for a given key from a query dict.
 
-        Supports only top-level equality (key: value) and $in (key: {"$in": [...]})
-        constraints. Returns a tuple (kind, value) where kind is "eq" or "in". If the
-        key is not present or uses other operators, returns None.
+        Supports top-level equality (e.g., ``{'subject': '01'}``) and ``$in``
+        (e.g., ``{'subject': {'$in': ['01', '02']}}``) constraints.
+
+        Parameters
+        ----------
+        query : dict
+            The MongoDB query dictionary.
+        key : str
+            The key for which to extract the constraint.
+
+        Returns
+        -------
+        tuple or None
+            A tuple of (kind, value) where kind is "eq" or "in", or None if the
+            constraint is not present or unsupported.
+
         """
         if not isinstance(query, dict) or key not in query:
             return None
@@ -275,16 +304,28 @@ class EEGDash:
                 return ("in", list(val["$in"]))
             return None  # unsupported operator shape for conflict checking
         else:
-            return ("eq", val)
+            return "eq", val
 
     def _raise_if_conflicting_constraints(
         self, raw_query: dict[str, Any], kwargs_query: dict[str, Any]
     ) -> None:
-        """Raise ValueError if both query sources define incompatible constraints.
+        """Raise ValueError if query sources have incompatible constraints.
+
+        Checks for mutually exclusive constraints on the same field to avoid
+        silent empty results.
+
+        Parameters
+        ----------
+        raw_query : dict
+            The raw MongoDB query dictionary.
+        kwargs_query : dict
+            The query dictionary built from keyword arguments.
+
+        Raises
+        ------
+        ValueError
+            If conflicting constraints are found.
 
-        We conservatively check only top-level fields with simple equality or $in
-        constraints. If a field appears in both queries and constraints are mutually
-        exclusive, raise an explicit error to avoid silent empty result sets.
         """
         if not raw_query or not kwargs_query:
             return
@@ -388,12 +429,31 @@ class EEGDash:
             logger.info("Upserted: %s", result.upserted_count)
             logger.info("Errors: %s ", result.bulk_api_result.get("writeErrors", []))
 
-    def _add_request(self, record: dict):
-        """Internal helper method to create a MongoDB insertion request for a record."""
+    def _add_request(self, record: dict) -> InsertOne:
+        """Create a MongoDB insertion request for a record.
+
+        Parameters
+        ----------
+        record : dict
+            The record to insert.
+
+        Returns
+        -------
+        InsertOne
+            A PyMongo ``InsertOne`` object.
+
+        """
         return InsertOne(record)
 
-    def add(self, record: dict):
-        """Add a single record to the MongoDB collection."""
+    def add(self, record: dict) -> None:
+        """Add a single record to the MongoDB collection.
+
+        Parameters
+        ----------
+        record : dict
+            The record to add.
+
+        """
         try:
             self.__collection.insert_one(record)
         except ValueError as e:
@@ -405,11 +465,23 @@ class EEGDash:
             )
             logger.debug("Add operation failed", exc_info=exc)
 
-    def _update_request(self, record: dict):
-        """Internal helper method to create a MongoDB update request for a record."""
+    def _update_request(self, record: dict) -> UpdateOne:
+        """Create a MongoDB update request for a record.
+
+        Parameters
+        ----------
+        record : dict
+            The record to update.
+
+        Returns
+        -------
+        UpdateOne
+            A PyMongo ``UpdateOne`` object.
+
+        """
         return UpdateOne({"data_name": record["data_name"]}, {"$set": record})
 
-    def update(self, record: dict):
+    def update(self, record: dict) -> None:
         """Update a single record in the MongoDB collection.
 
         Parameters
@@ -429,58 +501,81 @@ class EEGDash:
             logger.debug("Update operation failed", exc_info=exc)
 
     def exists(self, query: dict[str, Any]) -> bool:
-        """Alias for :meth:`exist` provided for API clarity."""
+        """Check if at least one record matches the query.
+
+        This is an alias for :meth:`exist`.
+
+        Parameters
+        ----------
+        query : dict
+            MongoDB query to check for existence.
+
+        Returns
+        -------
+        bool
+            True if a matching record exists, False otherwise.
+
+        """
         return self.exist(query)
 
-    def remove_field(self, record, field):
-        """Remove a specific field from a record in the MongoDB collection.
+    def remove_field(self, record: dict, field: str) -> None:
+        """Remove a field from a specific record in the MongoDB collection.
 
         Parameters
         ----------
         record : dict
-            Record identifying object with ``data_name``.
+            Record-identifying object with a ``data_name`` key.
         field : str
-            Field name to remove.
+            The name of the field to remove.
 
         """
         self.__collection.update_one(
             {"data_name": record["data_name"]}, {"$unset": {field: 1}}
         )
 
-    def remove_field_from_db(self, field):
-        """Remove a field from all records (destructive).
+    def remove_field_from_db(self, field: str) -> None:
+        """Remove a field from all records in the database.
+
+        .. warning::
+            This is a destructive operation and cannot be undone.
 
         Parameters
         ----------
         field : str
-            Field name to remove from every document.
+            The name of the field to remove from all documents.
 
         """
         self.__collection.update_many({}, {"$unset": {field: 1}})
 
     @property
     def collection(self):
-        """Return the MongoDB collection object."""
-        return self.__collection
+        """The underlying PyMongo ``Collection`` object.
 
-    def close(self):
-        """Backward-compatibility no-op; connections are managed globally.
+        Returns
+        -------
+        pymongo.collection.Collection
+            The collection object used for database interactions.
 
-        Notes
-        -----
-        Connections are managed by :class:`MongoConnectionManager`. Use
-        :meth:`close_all_connections` to explicitly close all clients.
+        """
+        return self.__collection
 
+    def close(self) -> None:
+        """Close the MongoDB connection.
+
+        .. deprecated:: 0.1
+            Connections are now managed globally by :class:`MongoConnectionManager`.
+            This method is a no-op and will be removed in a future version.
+            Use :meth:`EEGDash.close_all_connections` to close all clients.
         """
         # Individual instances no longer close the shared client
         pass
 
     @classmethod
-    def close_all_connections(cls):
-        """Close all MongoDB client connections managed by the singleton."""
+    def close_all_connections(cls) -> None:
+        """Close all MongoDB client connections managed by the singleton manager."""
         MongoConnectionManager.close_all()
 
-    def __del__(self):
+    def __del__(self) -> None:
         """Destructor; no explicit action needed due to global connection manager."""
         # No longer needed since we're using singleton pattern
         pass
@@ -775,45 +870,30 @@ class EEGDashDataset(BaseConcatDataset, metaclass=NumpyDocstringInheritanceInitM
     ) -> list[dict]:
         """Discover local BIDS EEG files and build minimal records.
 
-        This helper enumerates EEG recordings under ``dataset_root`` via
-        ``mne_bids.find_matching_paths`` and applies entity filters to produce a
-        list of records suitable for ``EEGDashBaseDataset``. No network access
-        is performed and files are not read.
+        Enumerates EEG recordings under ``dataset_root`` using
+        ``mne_bids.find_matching_paths`` and applies entity filters to produce
+        records suitable for :class:`EEGDashBaseDataset`. No network access is
+        performed, and files are not read.
 
         Parameters
         ----------
         dataset_root : Path
-            Local dataset directory. May be the plain dataset folder (e.g.,
-            ``ds005509``) or a suffixed cache variant (e.g.,
-            ``ds005509-bdf-mini``).
-        filters : dict of {str, Any}
-            Query filters. Must include ``'dataset'`` with the dataset id (without
-            local suffixes). May include BIDS entities ``'subject'``,
-            ``'session'``, ``'task'``, and ``'run'``. Each value can be a scalar
-            or a sequence of scalars.
+            Local dataset directory (e.g., ``/path/to/cache/ds005509``).
+        filters : dict
+            Query filters. Must include ``'dataset'`` and may include BIDS
+            entities like ``'subject'``, ``'session'``, etc.
 
         Returns
         -------
-        records : list of dict
-            One record per matched EEG file with at least:
-
-            - ``'data_name'``
-            - ``'dataset'`` (dataset id, without suffixes)
-            - ``'bidspath'`` (normalized to start with the dataset id)
-            - ``'subject'``, ``'session'``, ``'task'``, ``'run'`` (may be None)
-            - ``'bidsdependencies'`` (empty list)
-            - ``'modality'`` (``"eeg"``)
-            - ``'sampling_frequency'``, ``'nchans'``, ``'ntimes'`` (minimal
-              defaults for offline usage)
+        list of dict
+            A list of records, one for each matched EEG file. Each record
+            contains BIDS entities, paths, and minimal metadata for offline use.
 
         Notes
         -----
-        - Matching uses ``datatypes=['eeg']`` and ``suffixes=['eeg']``.
-        - ``bidspath`` is constructed as
-          ``<dataset_id> / <relative_path_from_dataset_root>`` to ensure the
-          first path component is the dataset id (without local cache suffixes).
-        - Minimal defaults are set for ``sampling_frequency``, ``nchans``, and
-          ``ntimes`` to satisfy dataset length requirements offline.
+        Matching is performed for ``datatypes=['eeg']`` and ``suffixes=['eeg']``.
+        The ``bidspath`` is normalized to ensure it starts with the dataset ID,
+        even for suffixed cache directories.
 
         """
         dataset_id = filters["dataset"]
@@ -875,10 +955,22 @@ class EEGDashDataset(BaseConcatDataset, metaclass=NumpyDocstringInheritanceInitM
         return records_out
 
     def _find_key_in_nested_dict(self, data: Any, target_key: str) -> Any:
-        """Recursively search for target_key in nested dicts/lists with normalized matching.
+        """Recursively search for a key in nested dicts/lists.
+
+        Performs a case-insensitive and underscore/hyphen-agnostic search.
+
+        Parameters
+        ----------
+        data : Any
+            The nested data structure (dicts, lists) to search.
+        target_key : str
+            The key to search for.
+
+        Returns
+        -------
+        Any
+            The value of the first matching key, or None if not found.
 
-        This makes lookups tolerant to naming differences like "p-factor" vs "p_factor".
-        Returns the first match or None.
         """
         norm_target = normalize_key(target_key)
         if isinstance(data, dict):
@@ -901,23 +993,25 @@ class EEGDashDataset(BaseConcatDataset, metaclass=NumpyDocstringInheritanceInitM
         description_fields: list[str],
         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.
+        """Find and construct datasets from a MongoDB query.
+
+        Queries the database, then creates a list of
+        :class:`EEGDashBaseDataset` objects from the results.
 
         Parameters
         ----------
-        query : dict
-            The query object, as in EEGDash.find().
-        description_fields : list[str]
-            A list of fields to be extracted from the dataset records and included in
-            the returned dataset description(s).
-        kwargs: additional keyword arguments to be passed to the EEGDashBaseDataset
-            constructor.
+        query : dict, optional
+            The MongoDB query to execute.
+        description_fields : list of str
+            Fields to extract from each record for the dataset description.
+        base_dataset_kwargs : dict
+            Additional keyword arguments to pass to the
+            :class:`EEGDashBaseDataset` constructor.
 
         Returns
         -------
-        list :
-            A list of EEGDashBaseDataset objects that match the query.
+        list of EEGDashBaseDataset
+            A list of dataset objects matching the query.
 
         """
         datasets: list[EEGDashBaseDataset] = []