eegdash 0.4.0.dev173498563__tar.gz → 0.4.1.dev185__tar.gz

{eegdash-0.4.0.dev173498563/eegdash.egg-info → eegdash-0.4.1.dev185}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eegdash
-Version: 0.4.0.dev173498563
+Version: 0.4.1.dev185
 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
@@ -27,23 +27,17 @@ License-File: LICENSE
 Requires-Dist: braindecode>=1.0
 Requires-Dist: mne_bids>=0.17.0
 Requires-Dist: numba
-Requires-Dist: numpy
-Requires-Dist: pandas
-Requires-Dist: pybids
 Requires-Dist: pymongo
-Requires-Dist: python-dotenv
 Requires-Dist: s3fs
-Requires-Dist: scipy
 Requires-Dist: tqdm
-Requires-Dist: h5io>=0.2.4
 Requires-Dist: pymatreader
 Requires-Dist: eeglabio
 Requires-Dist: tabulate
-Requires-Dist: docstring_inheritance
 Requires-Dist: rich
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: pytest-sugar; extra == "tests"
 Requires-Dist: codecov; extra == "tests"
 Requires-Dist: pytest_cases; extra == "tests"
 Requires-Dist: pytest-benchmark; extra == "tests"
@@ -66,10 +60,15 @@ Requires-Dist: lightgbm; extra == "docs"
 Requires-Dist: plotly; extra == "docs"
 Requires-Dist: nbformat; extra == "docs"
 Requires-Dist: graphviz; extra == "docs"
+Requires-Dist: neato; extra == "docs"
+Provides-Extra: digestion
+Requires-Dist: pybids; extra == "digestion"
+Requires-Dist: python-dotenv; extra == "digestion"
 Provides-Extra: all
 Requires-Dist: eegdash[docs]; extra == "all"
 Requires-Dist: eegdash[dev]; extra == "all"
 Requires-Dist: eegdash[tests]; extra == "all"
+Requires-Dist: eegdash[digestion]; extra == "all"
 Dynamic: license-file
 
 # EEG-Dash

{eegdash-0.4.0.dev173498563 → eegdash-0.4.1.dev185}/docs/Makefile

@@ -12,9 +12,9 @@ help:
 .PHONY: apidoc
 apidoc:
 	# Generate full API docs, then prune duplicates covered by autosummary
+	@rm -f "$(APIDIR)"/dataset/eegdash.features*
 	@SPHINX_APIDOC_OPTIONS=members,undoc-members,show-inheritance,noindex \
-		python -m sphinx.ext.apidoc -f -e -M -o "$(APIDIR)/dataset" "../$(PKG)"
-	# Remove top-level package page and modules covered elsewhere
+		python -m sphinx.ext.apidoc -f -e -T -o "$(APIDIR)/dataset" "../$(PKG)" "../$(PKG)/features"
 
 
 # Standard build runs examples

{eegdash-0.4.0.dev173498563 → eegdash-0.4.1.dev185}/docs/source/_templates/autosummary/module.rst

@@ -63,3 +63,19 @@
 {% endif %}
 {%- endblock %}
 
+{% if sg_api_usage %}
+.. _sg_api_{{ fullname }}:
+
+API Usage
+---------
+
+.. raw:: html
+
+    <div class="sg-api-usage">
+
+{{ sg_api_usage }}
+
+.. raw:: html
+
+    </div>
+{% endif %}

{eegdash-0.4.0.dev173498563 → eegdash-0.4.1.dev185}/docs/source/api/api_core.rst

@@ -53,8 +53,8 @@ The API is organized into focused modules that handle specific aspects of EEG da
 
 * :mod:`~eegdash.api` - Main interface for data access and manipulation
 * :mod:`~eegdash.const` - Constants and enumerations used throughout the package
+* :doc:`dataset/api_dataset` - Dataset object management and operations
 * :mod:`~eegdash.bids_eeg_metadata` - BIDS-compliant metadata handling  
-* :mod:`~eegdash.data_utils` - Data preprocessing and transformation utilities
 * :mod:`~eegdash.mongodb` - Database connection and query operations
 * :mod:`~eegdash.paths` - File system and storage path management
 * :mod:`~eegdash.utils` - General utility functions and helpers
@@ -71,9 +71,8 @@ API Reference
    api
    bids_eeg_metadata
    const
-   data_utils
    logging
    hbn
    mongodb
    paths
-   utils
+   utils

eegdash-0.4.1.dev185/docs/source/api/api_features.rst

@@ -0,0 +1,24 @@
+Feature API
+===========
+
+.. toctree::
+   :maxdepth: 1
+
+   Feature Package Overview <features_overview>
+
+.. autosummary::
+   :toctree: generated/api-features
+
+   eegdash.features.datasets
+   eegdash.features.decorators
+   eegdash.features.extractors
+   eegdash.features.inspect
+   eegdash.features.serialization
+   eegdash.features.utils
+   eegdash.features.feature_bank.complexity
+   eegdash.features.feature_bank.connectivity
+   eegdash.features.feature_bank.csp
+   eegdash.features.feature_bank.dimensionality
+   eegdash.features.feature_bank.signal
+   eegdash.features.feature_bank.spectral
+   eegdash.features.feature_bank.utils

eegdash-0.4.1.dev185/docs/source/api/features_overview.rst

@@ -0,0 +1,37 @@
+Feature Package Overview
+========================
+
+.. currentmodule:: eegdash.features
+
+The :mod:`eegdash.features` namespace re-exports feature extractors,
+decorators, and dataset utilities from the underlying submodules so callers can
+import the most common helpers from a single place. To avoid duplicated
+documentation in the API reference, the classes themselves are documented in
+their defining modules (see the links below). This page focuses on the
+high-level orchestration helpers that only live in the package ``__init__``.
+
+High-level discovery helpers
+----------------------------
+
+.. autofunction:: get_all_features
+.. autofunction:: get_feature_kind
+.. autofunction:: get_feature_predecessors
+.. autofunction:: get_all_feature_extractors
+.. autofunction:: get_all_feature_kinds
+
+Dataset and extraction utilities
+--------------------------------
+
+.. autofunction:: extract_features
+.. autofunction:: fit_feature_extractors
+.. autofunction:: load_features_concat_dataset
+
+See also
+--------
+
+- :mod:`eegdash.features.extractors` for the feature-extraction base classes
+  such as :class:`~eegdash.features.extractors.FeatureExtractor`.
+- :mod:`eegdash.features.datasets` for dataset wrappers like
+  :class:`~eegdash.features.datasets.FeaturesConcatDataset`.
+- :mod:`eegdash.features.feature_bank.*` for the concrete feature families
+  (complexity, connectivity, spectral, and more).

{eegdash-0.4.0.dev173498563 → eegdash-0.4.1.dev185}/docs/source/conf.py

@@ -2,6 +2,7 @@ import csv
 import importlib
 import inspect
 import os
+import shutil
 import sys
 from collections import Counter
 from datetime import datetime, timezone
@@ -12,13 +13,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 +47,7 @@ extensions = [
     "sphinx_sitemap",
     "sphinx_copybutton",
     "sphinx.ext.graphviz",
+    "sphinx_time_estimation",
 ]
 
 templates_path = ["_templates"]
@@ -61,6 +65,16 @@ suppress_warnings = [
     "config.cache",
 ]
 
+autodoc_type_aliases = {
+    "FeatureExtractor": "eegdash.features.extractors.FeatureExtractor",
+    "MultivariateFeature": "eegdash.features.extractors.MultivariateFeature",
+    "FeaturesConcatDataset": "eegdash.features.datasets.FeaturesConcatDataset",
+    "FeaturesDataset": "eegdash.features.datasets.FeaturesDataset",
+    "TrainableFeature": "eegdash.features.extractors.TrainableFeature",
+}
+
+python_use_unqualified_type_names = False
+
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = "pydata_sphinx_theme"
@@ -75,6 +89,7 @@ html_css_files = [
     "https://cdn.datatables.net/select/1.7.0/css/select.dataTables.min.css",
     "https://cdn.datatables.net/searchpanes/2.3.1/css/searchPanes.dataTables.min.css",
     "custom.css",
+    "css/treemap.css",
 ]
 html_js_files = [
     "https://code.jquery.com/jquery-3.7.1.min.js",
@@ -103,8 +118,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": [
@@ -218,11 +233,23 @@ EX_DIR = "../../examples"  # relative to docs/source
 sphinx_gallery_conf = {
     "examples_dirs": [f"{EX_DIR}"],
     "gallery_dirs": ["generated/auto_examples"],
+    # Disable plotting during doc builds; matches `html-noplot` behaviour.
+    "plot_gallery": False,
+    "binder": {
+        "org": "sccn",
+        "repo": "EEGDash",
+        "branch": "main",
+        "binderhub_url": "https://mybinder.org",
+        "dependencies": "binder/requirements.txt",
+        "notebooks_dir": "notebooks",
+        "use_jupyter_lab": True,
+    },
+    "capture_repr": ("_repr_html_", "__repr__"),
     "nested_sections": False,
     "backreferences_dir": "gen_modules/backreferences",
     "inspect_global_variables": True,
     "show_memory": True,
-    "show_api_usage": False,
+    "show_api_usage": True,
     "doc_module": ("eegdash", "numpy", "scipy", "matplotlib"),
     "reference_url": {"eegdash": None},
     "filename_pattern": r"/(?:plot|tutorial)_(?!_).*\.py",
@@ -243,8 +270,8 @@ LOGGER = logging.getLogger(__name__)
 
 
 AUTOGEN_NOTICE = """..
-   This file is auto-generated during the Sphinx build.
-   Do not edit by hand; changes will be overwritten.
+   This documentation page is generated during the Sphinx build.
+   The underlying code is manually maintained and not autogenerated.
 
 """
 
@@ -279,7 +306,9 @@ See Also
 """
 
 
-DATASET_INDEX_TEMPLATE = """{notice}Datasets API
+DATASET_INDEX_TEMPLATE = """{notice}.. _api/dataset/api_dataset:
+
+Datasets API
 =======================
 
 The :mod:`eegdash.dataset` package exposes dynamically registered dataset
@@ -299,6 +328,7 @@ Base Dataset API
 .. toctree::
    :maxdepth: 1
 
+   eegdash.EEGDashDataset
    eegdash.dataset.EEGChallengeDataset
 
 .. list-table:: Dataset counts by experimental type
@@ -338,6 +368,39 @@ EEGChallengeDataset
 """
 
 
+PRIMARY_DATASET_TEMPLATE = """{notice}.. _api_eegdash_dataset:
+
+.. currentmodule:: eegdash
+
+EEGDashDataset
+==============
+
+.. autoclass:: eegdash.EEGDashDataset
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :inherited-members:
+   :member-order: bysource
+
+Usage Example
+-------------
+
+.. code-block:: python
+
+   from eegdash import EEGDashDataset
+
+   dataset = EEGDashDataset(cache_dir="./data", dataset="ds002718")
+   print(f"Number of recordings: {{len(dataset)}}")
+
+See Also
+--------
+
+* :mod:`eegdash.dataset`
+* :class:`eegdash.dataset.EEGChallengeDataset`
+
+"""
+
+
 def _write_if_changed(path: Path, content: str) -> bool:
     """Write ``content`` to ``path`` if it differs from the current file."""
     existing = path.read_text(encoding="utf-8") if path.exists() else None
@@ -350,7 +413,7 @@ def _write_if_changed(path: Path, content: str) -> bool:
 def _iter_dataset_classes() -> Sequence[str]:
     """Return the sorted dataset class names exported by ``eegdash.dataset``."""
     import eegdash.dataset as dataset_module  # local import for clarity
-    from eegdash.api import EEGDashDataset
+    from eegdash.dataset import EEGDashDataset
 
     class_names: list[str] = []
     for name in getattr(dataset_module, "__all__", []):
@@ -569,6 +632,11 @@ def _generate_dataset_docs(app) -> None:
     if _write_if_changed(base_path, base_content):
         LOGGER.info("[dataset-docs] Updated %s", base_path.relative_to(app.srcdir))
 
+    primary_content = PRIMARY_DATASET_TEMPLATE.format(notice=AUTOGEN_NOTICE)
+    primary_path = dataset_dir / "eegdash.EEGDashDataset.rst"
+    if _write_if_changed(primary_path, primary_content):
+        LOGGER.info("[dataset-docs] Updated %s", primary_path.relative_to(app.srcdir))
+
     generated_paths: set[Path] = set()
     for name in dataset_names:
         title = f"eegdash.dataset.{name}"
@@ -599,8 +667,108 @@ def _generate_dataset_docs(app) -> None:
             continue
 
 
+def _split_tokens(value: str | None) -> set[str]:
+    tokens: set[str] = set()
+    if not value:
+        return tokens
+    for part in value.split(","):
+        cleaned = part.strip()
+        if cleaned:
+            tokens.add(cleaned)
+    return tokens
+
+
+def _compute_dataset_counter_defaults() -> dict[str, int]:
+    csv_path = Path(importlib.import_module("eegdash.dataset").__file__).with_name(
+        "dataset_summary.csv"
+    )
+    if not csv_path.exists():
+        return {}
+
+    dataset_ids: set[str] = set()
+    modalities: set[str] = set()
+    cognitive: set[str] = set()
+    subject_total = 0
+
+    with csv_path.open(encoding="utf-8") as handle:
+        filtered = (
+            line
+            for line in handle
+            if line.strip() and not line.lstrip().startswith("#")
+        )
+        reader = csv.DictReader(filtered)
+        for row in reader:
+            dataset = (row.get("dataset") or row.get("Dataset") or "").strip()
+            if dataset:
+                dataset_ids.add(dataset)
+
+            try:
+                subject_total += int(float(row.get("n_subjects", "0") or 0))
+            except (TypeError, ValueError):
+                pass
+
+            modalities.update(_split_tokens(row.get("record_modality")))
+            cognitive.update(_split_tokens(row.get("type of exp")))
+
+    return {
+        "datasets": len(dataset_ids),
+        "subjects": subject_total,
+        "modalities": len(modalities),
+        "cognitive": len(cognitive),
+    }
+
+
+_DATASET_COUNTER_DEFAULTS = _compute_dataset_counter_defaults()
+
+
+def _format_counter(key: str) -> str:
+    value = _DATASET_COUNTER_DEFAULTS.get(key, 0)
+    if isinstance(value, (int, float)):
+        if isinstance(value, float) and not value.is_integer():
+            return f"{value:,.2f}"
+        return f"{int(value):,}"
+    return str(value)
+
+
+_DATASET_COUNTER_PLACEHOLDERS = {
+    "|datasets_total|": _format_counter("datasets"),
+    "|subjects_total|": _format_counter("subjects"),
+    "|modalities_total|": _format_counter("modalities"),
+    "|cognitive_total|": _format_counter("cognitive"),
+}
+
+
+def _copy_dataset_summary(app, exception) -> None:
+    if exception is not None or not getattr(app, "builder", None):
+        return
+
+    csv_path = Path(importlib.import_module("eegdash.dataset").__file__).with_name(
+        "dataset_summary.csv"
+    )
+    if not csv_path.exists():
+        LOGGER.warning("dataset_summary.csv not found; skipping counter data copy.")
+        return
+
+    static_dir = Path(app.outdir) / "_static"
+    try:
+        static_dir.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(csv_path, static_dir / "dataset_summary.csv")
+    except OSError as exc:
+        LOGGER.warning("Unable to copy dataset_summary.csv to _static: %s", exc)
+
+
+def _inject_counter_values(app, docname, source) -> None:
+    if docname != "dataset_summary":
+        return
+
+    text = source[0]
+    for token, value in _DATASET_COUNTER_PLACEHOLDERS.items():
+        text = text.replace(token, value)
+    source[0] = text
+
+
 def setup(app):
-    """Create the back-references directory if it doesn't exist."""
+    """Create the back-references directory and setup Sphinx events."""
     backreferences_dir = os.path.join(
         app.srcdir, sphinx_gallery_conf["backreferences_dir"]
     )
@@ -608,6 +776,8 @@ def setup(app):
         os.makedirs(backreferences_dir)
 
     app.connect("builder-inited", _generate_dataset_docs)
+    app.connect("build-finished", _copy_dataset_summary)
+    app.connect("source-read", _inject_counter_values)
 
 
 # Configure sitemap URL format (omit .html where possible)

eegdash-0.4.1.dev185/docs/source/dataset_summary/treemap.rst

@@ -0,0 +1,19 @@
+.. title:: Dataset treemap
+
+.. rubric:: Dataset treemap
+
+.. raw:: html
+
+   <figure class="eegdash-figure" style="margin: 0 0 1.25rem 0;">
+
+.. raw:: html
+   :file: ../_static/dataset_generated/dataset_treemap.html
+
+.. raw:: html
+
+   <figcaption class="eegdash-caption">
+     Figure: Treemap of EEG Dash datasets. The top level groups population type,
+     the second level breaks down experimental modality, and leaves list individual datasets.
+     Tile area encodes the total number of subjects; hover to view aggregated hours (or records when unavailable).
+   </figcaption>
+   </figure>

eegdash-0.4.1.dev185/docs/source/dataset_summary.rst

@@ -0,0 +1,99 @@
+:hide_sidebar: true
+:html_theme.sidebar_secondary.remove: true
+:html_theme.sidebar_primary.remove: true
+
+.. _data_summary:
+
+.. raw:: html
+
+   <script>document.documentElement.classList.add('dataset-summary-page');</script>
+
+.. rst-class:: dataset-summary-article
+
+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.
+
+.. raw:: html
+
+   <section class="dataset-counter-grid">
+     <article class="dataset-counter-card">
+       <div class="dataset-counter-icon" aria-hidden="true">
+         <svg class="dataset-counter-svg" viewBox="0 0 24 24" role="presentation" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
+           <ellipse cx="12" cy="5" rx="7" ry="3"></ellipse>
+           <path d="M5 5v10c0 1.66 3.13 3 7 3s7-1.34 7-3V5"></path>
+           <path d="M5 12c0 1.66 3.13 3 7 3s7-1.34 7-3"></path>
+         </svg>
+       </div>
+       <div class="dataset-counter-body">
+         <span class="dataset-counter-label">Datasets</span>
+         <span class="dataset-counter-value">|datasets_total|</span>
+       </div>
+     </article>
+     <article class="dataset-counter-card">
+       <div class="dataset-counter-icon" aria-hidden="true">
+         <svg class="dataset-counter-svg" viewBox="0 0 24 24" role="presentation" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
+           <circle cx="8" cy="9" r="3"></circle>
+           <circle cx="16" cy="9" r="3"></circle>
+           <path d="M4 19c0-3 2.24-5 4-5s4 2 4 5"></path>
+           <path d="M12 19c0-3 2.24-5 4-5s4 2 4 5"></path>
+         </svg>
+       </div>
+       <div class="dataset-counter-body">
+         <span class="dataset-counter-label">Subjects</span>
+         <span class="dataset-counter-value">|subjects_total|</span>
+       </div>
+     </article>
+     <article class="dataset-counter-card">
+       <div class="dataset-counter-icon" aria-hidden="true">
+         <svg class="dataset-counter-svg" viewBox="0 0 24 24" role="presentation" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
+           <path d="M3 15c2.5 0 2.5-6 5-6s2.5 6 5 6 2.5-6 5-6 2.5 6 5 6"></path>
+           <path d="M3 9c2.5 0 2.5-5 5-5s2.5 5 5 5 2.5-5 5-5 2.5 5 5 5"></path>
+         </svg>
+       </div>
+       <div class="dataset-counter-body">
+         <span class="dataset-counter-label">Experiment Modalities</span>
+         <span class="dataset-counter-value">|modalities_total|</span>
+       </div>
+     </article>
+     <article class="dataset-counter-card">
+       <div class="dataset-counter-icon" aria-hidden="true">
+         <svg class="dataset-counter-svg" viewBox="0 0 24 24" role="presentation" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">
+           <path d="M12 4c-3.5 0-7 2-7 6 0 3.5 2.5 6 6 6v4l3-2 3 2v-4c2.5 0 4-2 4-5 0-3.5-2.5-7-9-7z"></path>
+         </svg>
+       </div>
+       <div class="dataset-counter-body">
+         <span class="dataset-counter-label">Cognitive Domains</span>
+         <span class="dataset-counter-value">|cognitive_total|</span>
+       </div>
+     </article>
+   </section>
+
+.. raw:: html
+
+   <script src="https://cdn.plot.ly/plotly-3.1.0.min.js"></script>
+
+.. tab-set::
+
+   .. tab-item:: Dataset Table
+
+      .. include:: dataset_summary/table.rst
+
+   .. tab-item:: Participant Distribution
+
+      .. include:: dataset_summary/kde.rst
+
+   .. tab-item:: Dataset Flow
+
+      .. include:: dataset_summary/sankey.rst
+
+   .. tab-item:: Dataset Treemap
+
+      .. include:: dataset_summary/treemap.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.