moecog 0.1.0__tar.gz

moecog-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Yifan Yu
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

moecog-0.1.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: moecog
+Version: 0.1.0
+Summary: Mother of All ECoG Benchmarks — MOABB-style benchmarking for ECoG motor decoding
+Author-email: Yifan Yu <yifanyu97@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/epyifany/MOECoG
+Project-URL: Repository, https://github.com/epyifany/MOECoG
+Project-URL: Issues, https://github.com/epyifany/MOECoG/issues
+Keywords: ECoG,electrocorticography,BCI,brain-computer interface,motor decoding,benchmark,neuroscience,neural decoding
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mne>=1.5
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: pandas>=2.0
+Requires-Dist: h5py>=3.8
+Requires-Dist: pooch>=1.7
+Requires-Dist: tqdm>=4.65
+Provides-Extra: deep
+Requires-Dist: torch>=2.0; extra == "deep"
+Requires-Dist: braindecode>=0.8; extra == "deep"
+Provides-Extra: nwb
+Requires-Dist: pynwb>=2.5; extra == "nwb"
+Requires-Dist: dandi>=0.55; extra == "nwb"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == "viz"
+Requires-Dist: seaborn>=0.12; extra == "viz"
+Provides-Extra: anatomy
+Requires-Dist: nilearn>=0.10; extra == "anatomy"
+Requires-Dist: nibabel>=5.0; extra == "anatomy"
+Provides-Extra: dev
+Requires-Dist: moecog[anatomy,deep,nwb,viz]; extra == "dev"
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Provides-Extra: all
+Requires-Dist: moecog[anatomy,deep,nwb,viz]; extra == "all"
+Dynamic: license-file
+
+# MOECoG — Mother of All ECoG Benchmarks
+
+A MOABB-style benchmarking framework for electrocorticographic (ECoG) motor decoding.
+
+> *"ECoG isn't just the future — it's the testable present."*
+
+## Vision
+
+[MOABB](https://github.com/NeuroTechX/moabb) transformed EEG-BCI research by making algorithm comparison reproducible and fair. **MOECoG does the same for ECoG motor decoding** — the signal modality at the critical intersection of clinical viability (long-term stability, lower surgical risk) and high-performance neural control (high-gamma access, mm-scale spatial resolution).
+
+This project will be successful when we read in an abstract:
+
+> *"...the proposed method obtained a correlation of 0.82 on MOECoG, outperforming the state of the art by 12%..."*
+
+## Why ECoG Needs Its Own Benchmark
+
+| Property | EEG (MOABB) | ECoG (MOECoG) |
+|---|---|---|
+| Signal type | Scalp potentials | Cortical surface potentials |
+| Key features | mu/beta ERD/ERS | High-gamma broadband (>70 Hz) + beta suppression |
+| Spatial resolution | ~cm | ~mm |
+| Electrode geometry | Standard montages (10-20) | Patient-specific grids/strips |
+| Primary tasks | Classification (L/R imagery) | Both classification AND continuous regression |
+| Cross-subject | Standard channel alignment | Requires anatomical registration |
+| Noise profile | EMG, EOG artifacts | Epileptiform activity, referencing |
+
+MOABB's paradigm/dataset/evaluation/pipeline abstraction is brilliant — but its assumptions (fixed channel montages, epoched classification, standard frequency bands) break down for ECoG.
+
+## Architecture
+
+MOECoG follows MOABB's 4-concept design, adapted for ECoG:
+
+```
++--------------+    +---------------+    +---------------+    +---------------+
+|   Dataset    |--->|   Paradigm    |--->|  Evaluation   |--->|   Pipeline    |
+|              |    |               |    |               |    |               |
+| Raw ECoG +   |    | Motor Imagery |    | WithinSubject |    | Feature ext.  |
+| electrode    |    | Finger Flex   |    | CrossSession  |    | + Classifier  |
+| positions +  |    | Arm Reach     |    | Transfer      |    | or Regressor  |
+| anatomy      |    | Grasp Type    |    |               |    |               |
++--------------+    +---------------+    +---------------+    +---------------+
+```
+
+### Key Differences from MOABB
+
+- **Dual-task paradigms:** Classification (which finger?) AND regression (finger trajectory)
+- **Anatomical electrode registration:** Patient-specific grids mapped to MNI/FreeSurfer atlas
+- **Broadband feature extraction:** High-gamma (70-150 Hz), beta (13-30 Hz), phase-amplitude coupling
+- **Continuous decoding metrics:** Correlation coefficient (r), R-squared, normalized MSE — not just accuracy
+- **Naturalistic movement support:** Not just cued trials but free/spontaneous movements (AJILE12)
+
+## Included Datasets
+
+### Tier 1: Core Benchmark
+
+Motor-specific, public, well-documented.
+
+| ID | Dataset | Source | Subjects | Task | Channels | Modality |
+|---|---|---|---|---|---|---|
+| MillerFingerFlex | BCI Competition IV Dataset 4 | Miller & Schalk | 3 | Individual finger flexion (5-class regression) | 48-64 | ECoG grid |
+| MillerLibrary | Stanford/Mayo ECoG Library | Miller 2019, *Nature Human Behaviour* | 34 | 16 experiments (motor, sensory, language, visual) | Varies | ECoG grid |
+| AJILE12 | Annotated Joints in Long-term ECoG | Peterson et al. 2022, *Scientific Data* | 12 | Naturalistic wrist movements | >=64 | ECoG grid |
+
+### Tier 2: Extended Benchmark
+
+| ID | Dataset | Source | Subjects | Task |
+|---|---|---|---|---|
+| BCITetraplegia | BCI and Tetraplegia (WIMAGINE) | Benabid/Costecalde et al. | 1 (chronic) | 4-class motor imagery, 2D cursor |
+| GraspECoG | Natural grasp types | Various (Pistohl, Bleichner) | Varies | Grasp classification |
+| MoveAgain | Blackrock/BrainGate ECoG subsets | If released publicly | Varies | Arm/hand movement |
+
+### Tier 3: Cross-Modality Comparison
+
+| ID | Dataset | Why included |
+|---|---|---|
+| MOABB_MI | MOABB motor imagery EEG datasets | Direct EEG vs ECoG comparison on matched paradigms |
+
+## Paradigms
+
+### FingerFlexionRegression
+
+- **Task:** Predict continuous finger flexion trajectories from ECoG
+- **Metrics:** Pearson r, R-squared, NRMSE per finger
+- **Datasets:** MillerFingerFlex, MillerLibrary (motor subset)
+- **Baseline:** BCI Competition IV Dataset 4 leaderboard
+
+### MotorImageryClassification
+
+- **Task:** Classify imagined/attempted movements (L/R hand, feet, tongue, etc.)
+- **Metrics:** Accuracy, ROC-AUC, Cohen's kappa
+- **Datasets:** MillerLibrary (motor imagery subset), BCITetraplegia
+
+### NaturalisticReachDecoding
+
+- **Task:** Decode wrist movement onset and trajectory from unconstrained behavior
+- **Metrics:** Event detection F1, trajectory r, latency
+- **Datasets:** AJILE12
+
+### GraspClassification
+
+- **Task:** Classify grasp types or hand gestures from sensorimotor ECoG
+- **Metrics:** Accuracy, confusion matrix analysis
+- **Datasets:** GraspECoG, MillerLibrary (gesture subset)
+
+## Evaluation Strategies
+
+| Strategy | Description | Use Case |
+|---|---|---|
+| WithinSubjectCV | K-fold within single subject | Standard single-patient decoding |
+| CrossSessionEval | Train on session A, test on session B | Stability / recalibration assessment |
+| CrossSubjectTransfer | Leave-one-subject-out (with atlas projection) | Generalization / zero-shot transfer |
+| TemporalStabilityEval | Chronological split (early to late) | Long-term signal stability |
+
+## Baseline Pipelines
+
+### Feature Extraction
+
+- **LogBandPower** — Log power in canonical bands (mu, beta, low-gamma, high-gamma)
+- **BroadbandChange** — Miller's broadband spectral change method
+- **PAC** — Phase-amplitude coupling (theta/gamma, beta/high-gamma)
+- **CSP_ECoG** — Common Spatial Patterns adapted for patient-specific grids
+- **TimeFrequency** — Continuous wavelet / multitaper spectrograms
+
+### Decoders
+
+- **LDA / SVM / LogisticRegression** — Classical classifiers
+- **Ridge / Kalman** — Linear regressors for trajectory decoding
+- **ECoGNet** — Lightweight CNN for ECoG (braindecode-compatible)
+- **FingerFlex** — Convolutional encoder-decoder (Lomtev et al.)
+- **HTNet** — Transfer learning across subjects via Hilbert transform
+
+## Quick Start
+
+```python
+import moecog
+from moecog.datasets import MillerFingerFlex
+from moecog.paradigms import FingerFlexionRegression
+from moecog.evaluations import WithinSubjectCV
+from moecog.pipelines.features import LogBandPower
+from sklearn.linear_model import Ridge
+from sklearn.pipeline import make_pipeline
+
+# Define pipeline
+pipelines = {
+    "LogBandPower+Ridge": make_pipeline(LogBandPower(), Ridge(alpha=1.0))
+}
+
+# Load data
+dataset = MillerFingerFlex()
+paradigm = FingerFlexionRegression(fmin=1, fmax=150)
+evaluation = WithinSubjectCV(paradigm=paradigm, datasets=[dataset], n_splits=5)
+
+# Run benchmark
+results = evaluation.process(pipelines)
+print(results.groupby("pipeline")["score"].mean())
+```
+
+## Installation
+
+```bash
+pip install moecog
+```
+
+Or for development:
+
+```bash
+git clone https://github.com/epyifany/MOECoG.git
+cd MOECoG
+pip install -e ".[dev]"
+```
+
+### Dependencies
+
+**Core:**
+- `mne >= 1.5` — ECoG signal handling, coordinate transforms
+- `numpy`, `scipy`, `scikit-learn` — Core ML
+- `pandas` — Results management
+- `h5py` — Persistent results storage
+- `pooch` — Robust data downloading
+
+**Optional:**
+- `torch`, `braindecode` — Deep learning baselines (`pip install moecog[deep]`)
+- `pynwb`, `dandi` — NWB data access for AJILE12 (`pip install moecog[nwb]`)
+- `nilearn`, `nibabel` — Anatomical registration (`pip install moecog[anatomy]`)
+- `matplotlib`, `seaborn` — Visualization (`pip install moecog[viz]`)
+
+## Citation
+
+If you use MOECoG in your research, please cite:
+
+```bibtex
+@software{moecog2025,
+  title = {MOECoG: Mother of All ECoG Benchmarks},
+  author = {Yu, Yifan},
+  year = {2025},
+  url = {https://github.com/epyifany/MOECoG}
+}
+```
+
+And the foundational datasets:
+
+- Miller, K.J. "A library of human electrocorticographic data and analyses." *Nature Human Behaviour* 3(11), 1225-1235 (2019).
+- Peterson, S.M. et al. "AJILE12: Long-term naturalistic human intracranial neural recordings and pose." *Scientific Data* 9, 184 (2022).
+- Schalk, G. et al. BCI Competition IV Dataset 4.
+
+## License
+
+BSD-3-Clause (matching MOABB)

moecog-0.1.0/README.md

@@ -0,0 +1,208 @@
+# MOECoG — Mother of All ECoG Benchmarks
+
+A MOABB-style benchmarking framework for electrocorticographic (ECoG) motor decoding.
+
+> *"ECoG isn't just the future — it's the testable present."*
+
+## Vision
+
+[MOABB](https://github.com/NeuroTechX/moabb) transformed EEG-BCI research by making algorithm comparison reproducible and fair. **MOECoG does the same for ECoG motor decoding** — the signal modality at the critical intersection of clinical viability (long-term stability, lower surgical risk) and high-performance neural control (high-gamma access, mm-scale spatial resolution).
+
+This project will be successful when we read in an abstract:
+
+> *"...the proposed method obtained a correlation of 0.82 on MOECoG, outperforming the state of the art by 12%..."*
+
+## Why ECoG Needs Its Own Benchmark
+
+| Property | EEG (MOABB) | ECoG (MOECoG) |
+|---|---|---|
+| Signal type | Scalp potentials | Cortical surface potentials |
+| Key features | mu/beta ERD/ERS | High-gamma broadband (>70 Hz) + beta suppression |
+| Spatial resolution | ~cm | ~mm |
+| Electrode geometry | Standard montages (10-20) | Patient-specific grids/strips |
+| Primary tasks | Classification (L/R imagery) | Both classification AND continuous regression |
+| Cross-subject | Standard channel alignment | Requires anatomical registration |
+| Noise profile | EMG, EOG artifacts | Epileptiform activity, referencing |
+
+MOABB's paradigm/dataset/evaluation/pipeline abstraction is brilliant — but its assumptions (fixed channel montages, epoched classification, standard frequency bands) break down for ECoG.
+
+## Architecture
+
+MOECoG follows MOABB's 4-concept design, adapted for ECoG:
+
+```
++--------------+    +---------------+    +---------------+    +---------------+
+|   Dataset    |--->|   Paradigm    |--->|  Evaluation   |--->|   Pipeline    |
+|              |    |               |    |               |    |               |
+| Raw ECoG +   |    | Motor Imagery |    | WithinSubject |    | Feature ext.  |
+| electrode    |    | Finger Flex   |    | CrossSession  |    | + Classifier  |
+| positions +  |    | Arm Reach     |    | Transfer      |    | or Regressor  |
+| anatomy      |    | Grasp Type    |    |               |    |               |
++--------------+    +---------------+    +---------------+    +---------------+
+```
+
+### Key Differences from MOABB
+
+- **Dual-task paradigms:** Classification (which finger?) AND regression (finger trajectory)
+- **Anatomical electrode registration:** Patient-specific grids mapped to MNI/FreeSurfer atlas
+- **Broadband feature extraction:** High-gamma (70-150 Hz), beta (13-30 Hz), phase-amplitude coupling
+- **Continuous decoding metrics:** Correlation coefficient (r), R-squared, normalized MSE — not just accuracy
+- **Naturalistic movement support:** Not just cued trials but free/spontaneous movements (AJILE12)
+
+## Included Datasets
+
+### Tier 1: Core Benchmark
+
+Motor-specific, public, well-documented.
+
+| ID | Dataset | Source | Subjects | Task | Channels | Modality |
+|---|---|---|---|---|---|---|
+| MillerFingerFlex | BCI Competition IV Dataset 4 | Miller & Schalk | 3 | Individual finger flexion (5-class regression) | 48-64 | ECoG grid |
+| MillerLibrary | Stanford/Mayo ECoG Library | Miller 2019, *Nature Human Behaviour* | 34 | 16 experiments (motor, sensory, language, visual) | Varies | ECoG grid |
+| AJILE12 | Annotated Joints in Long-term ECoG | Peterson et al. 2022, *Scientific Data* | 12 | Naturalistic wrist movements | >=64 | ECoG grid |
+
+### Tier 2: Extended Benchmark
+
+| ID | Dataset | Source | Subjects | Task |
+|---|---|---|---|---|
+| BCITetraplegia | BCI and Tetraplegia (WIMAGINE) | Benabid/Costecalde et al. | 1 (chronic) | 4-class motor imagery, 2D cursor |
+| GraspECoG | Natural grasp types | Various (Pistohl, Bleichner) | Varies | Grasp classification |
+| MoveAgain | Blackrock/BrainGate ECoG subsets | If released publicly | Varies | Arm/hand movement |
+
+### Tier 3: Cross-Modality Comparison
+
+| ID | Dataset | Why included |
+|---|---|---|
+| MOABB_MI | MOABB motor imagery EEG datasets | Direct EEG vs ECoG comparison on matched paradigms |
+
+## Paradigms
+
+### FingerFlexionRegression
+
+- **Task:** Predict continuous finger flexion trajectories from ECoG
+- **Metrics:** Pearson r, R-squared, NRMSE per finger
+- **Datasets:** MillerFingerFlex, MillerLibrary (motor subset)
+- **Baseline:** BCI Competition IV Dataset 4 leaderboard
+
+### MotorImageryClassification
+
+- **Task:** Classify imagined/attempted movements (L/R hand, feet, tongue, etc.)
+- **Metrics:** Accuracy, ROC-AUC, Cohen's kappa
+- **Datasets:** MillerLibrary (motor imagery subset), BCITetraplegia
+
+### NaturalisticReachDecoding
+
+- **Task:** Decode wrist movement onset and trajectory from unconstrained behavior
+- **Metrics:** Event detection F1, trajectory r, latency
+- **Datasets:** AJILE12
+
+### GraspClassification
+
+- **Task:** Classify grasp types or hand gestures from sensorimotor ECoG
+- **Metrics:** Accuracy, confusion matrix analysis
+- **Datasets:** GraspECoG, MillerLibrary (gesture subset)
+
+## Evaluation Strategies
+
+| Strategy | Description | Use Case |
+|---|---|---|
+| WithinSubjectCV | K-fold within single subject | Standard single-patient decoding |
+| CrossSessionEval | Train on session A, test on session B | Stability / recalibration assessment |
+| CrossSubjectTransfer | Leave-one-subject-out (with atlas projection) | Generalization / zero-shot transfer |
+| TemporalStabilityEval | Chronological split (early to late) | Long-term signal stability |
+
+## Baseline Pipelines
+
+### Feature Extraction
+
+- **LogBandPower** — Log power in canonical bands (mu, beta, low-gamma, high-gamma)
+- **BroadbandChange** — Miller's broadband spectral change method
+- **PAC** — Phase-amplitude coupling (theta/gamma, beta/high-gamma)
+- **CSP_ECoG** — Common Spatial Patterns adapted for patient-specific grids
+- **TimeFrequency** — Continuous wavelet / multitaper spectrograms
+
+### Decoders
+
+- **LDA / SVM / LogisticRegression** — Classical classifiers
+- **Ridge / Kalman** — Linear regressors for trajectory decoding
+- **ECoGNet** — Lightweight CNN for ECoG (braindecode-compatible)
+- **FingerFlex** — Convolutional encoder-decoder (Lomtev et al.)
+- **HTNet** — Transfer learning across subjects via Hilbert transform
+
+## Quick Start
+
+```python
+import moecog
+from moecog.datasets import MillerFingerFlex
+from moecog.paradigms import FingerFlexionRegression
+from moecog.evaluations import WithinSubjectCV
+from moecog.pipelines.features import LogBandPower
+from sklearn.linear_model import Ridge
+from sklearn.pipeline import make_pipeline
+
+# Define pipeline
+pipelines = {
+    "LogBandPower+Ridge": make_pipeline(LogBandPower(), Ridge(alpha=1.0))
+}
+
+# Load data
+dataset = MillerFingerFlex()
+paradigm = FingerFlexionRegression(fmin=1, fmax=150)
+evaluation = WithinSubjectCV(paradigm=paradigm, datasets=[dataset], n_splits=5)
+
+# Run benchmark
+results = evaluation.process(pipelines)
+print(results.groupby("pipeline")["score"].mean())
+```
+
+## Installation
+
+```bash
+pip install moecog
+```
+
+Or for development:
+
+```bash
+git clone https://github.com/epyifany/MOECoG.git
+cd MOECoG
+pip install -e ".[dev]"
+```
+
+### Dependencies
+
+**Core:**
+- `mne >= 1.5` — ECoG signal handling, coordinate transforms
+- `numpy`, `scipy`, `scikit-learn` — Core ML
+- `pandas` — Results management
+- `h5py` — Persistent results storage
+- `pooch` — Robust data downloading
+
+**Optional:**
+- `torch`, `braindecode` — Deep learning baselines (`pip install moecog[deep]`)
+- `pynwb`, `dandi` — NWB data access for AJILE12 (`pip install moecog[nwb]`)
+- `nilearn`, `nibabel` — Anatomical registration (`pip install moecog[anatomy]`)
+- `matplotlib`, `seaborn` — Visualization (`pip install moecog[viz]`)
+
+## Citation
+
+If you use MOECoG in your research, please cite:
+
+```bibtex
+@software{moecog2025,
+  title = {MOECoG: Mother of All ECoG Benchmarks},
+  author = {Yu, Yifan},
+  year = {2025},
+  url = {https://github.com/epyifany/MOECoG}
+}
+```
+
+And the foundational datasets:
+
+- Miller, K.J. "A library of human electrocorticographic data and analyses." *Nature Human Behaviour* 3(11), 1225-1235 (2019).
+- Peterson, S.M. et al. "AJILE12: Long-term naturalistic human intracranial neural recordings and pose." *Scientific Data* 9, 184 (2022).
+- Schalk, G. et al. BCI Competition IV Dataset 4.
+
+## License
+
+BSD-3-Clause (matching MOABB)

moecog-0.1.0/moecog/__init__.py

@@ -0,0 +1,6 @@
+"""MOECoG — Mother of All ECoG Benchmarks.
+
+A MOABB-style benchmarking framework for electrocorticographic (ECoG) motor decoding.
+"""
+
+__version__ = "0.1.0"

moecog-0.1.0/moecog/analysis/__init__.py

@@ -0,0 +1 @@
+"""Analysis — results storage, statistics, and visualization."""

moecog-0.1.0/moecog/datasets/__init__.py

@@ -0,0 +1,8 @@
+"""ECoG dataset loaders."""
+
+from .base import BaseECoGDataset, ElectrodeInfo
+
+__all__ = [
+    "BaseECoGDataset",
+    "ElectrodeInfo",
+]

moecog-0.1.0/moecog/datasets/base.py

@@ -0,0 +1,161 @@
+"""Base class for all ECoG datasets."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+
+
+@dataclass
+class ElectrodeInfo:
+    """Patient-specific electrode metadata.
+
+    Parameters
+    ----------
+    positions : np.ndarray, shape (n_channels, 3)
+        Electrode coordinates (MNI or native space).
+    labels : list of str
+        Channel names.
+    hemisphere : list of str or None
+        Hemisphere per electrode ("L" or "R").
+    lobe : list of str or None
+        Anatomical lobe per electrode.
+    gyrus : list of str or None
+        Gyrus per electrode.
+    brodmann_area : list of int or None
+        Brodmann area per electrode.
+    grid_type : str
+        Electrode array type: "grid", "strip", or "depth".
+    spacing_mm : float
+        Inter-electrode distance in millimeters.
+    """
+
+    positions: np.ndarray
+    labels: list[str]
+    hemisphere: list[str] | None = None
+    lobe: list[str] | None = None
+    gyrus: list[str] | None = None
+    brodmann_area: list[int] | None = None
+    grid_type: str = "grid"
+    spacing_mm: float = 10.0
+
+
+class BaseECoGDataset(ABC):
+    """Base class for all ECoG datasets.
+
+    Every concrete dataset must implement:
+        - ``_get_single_subject_data(subject)``
+        - ``data_path(subject)``
+        - ``get_electrode_info(subject)``
+
+    Parameters
+    ----------
+    subjects : list of int
+        Available subject IDs.
+    sessions_per_subject : int
+        Number of recording sessions per subject.
+    events : dict or None
+        Mapping of event names to integer codes. None for pure regression datasets.
+    code : str
+        Unique dataset identifier string.
+    paradigm : str
+        Paradigm type: "motor_regression", "motor_imagery", or "naturalistic".
+    interval : list of float or None
+        Epoch window [tmin, tmax] in seconds. None for continuous data.
+    sfreq : float
+        Sampling frequency in Hz.
+    doi : str or None
+        DOI of the associated publication.
+    """
+
+    def __init__(
+        self,
+        subjects: list[int],
+        sessions_per_subject: int,
+        events: dict[str, int] | None,
+        code: str,
+        paradigm: str,
+        interval: list[float] | None,
+        sfreq: float,
+        doi: str | None = None,
+    ):
+        self.subject_list = subjects
+        self.n_sessions = sessions_per_subject
+        self.event_id = events
+        self.code = code
+        self.paradigm_type = paradigm
+        self.interval = interval
+        self.sfreq = sfreq
+        self.doi = doi
+
+    def get_data(self, subjects=None):
+        """Load data for one or more subjects.
+
+        Parameters
+        ----------
+        subjects : list of int or None
+            Subject IDs to load. If None, loads all subjects.
+
+        Returns
+        -------
+        dict
+            Nested dict: ``{subject: {session: {run: mne.io.Raw}}}``.
+        """
+        subjects = subjects or self.subject_list
+        data = {}
+        for subject in subjects:
+            data[subject] = self._get_single_subject_data(subject)
+        return data
+
+    @abstractmethod
+    def _get_single_subject_data(self, subject):
+        """Load all sessions and runs for a single subject.
+
+        Parameters
+        ----------
+        subject : int
+            Subject identifier.
+
+        Returns
+        -------
+        dict
+            ``{session_id: {run_id: mne.io.Raw}}``.
+        """
+
+    @abstractmethod
+    def data_path(self, subject):
+        """Return local file paths for a subject's data, downloading if needed.
+
+        Parameters
+        ----------
+        subject : int
+            Subject identifier.
+
+        Returns
+        -------
+        list of Path
+            Local paths to the data files.
+        """
+
+    @abstractmethod
+    def get_electrode_info(self, subject):
+        """Return electrode metadata for a subject.
+
+        Parameters
+        ----------
+        subject : int
+            Subject identifier.
+
+        Returns
+        -------
+        ElectrodeInfo
+            Electrode positions and anatomical labels.
+        """
+
+    def __repr__(self):
+        return (
+            f"{self.__class__.__name__}(code={self.code!r}, "
+            f"subjects={len(self.subject_list)}, "
+            f"sessions={self.n_sessions})"
+        )

moecog-0.1.0/moecog/evaluations/__init__.py

@@ -0,0 +1,7 @@
+"""Evaluation strategies for ECoG benchmarking."""
+
+from .base import BaseEvaluation
+
+__all__ = [
+    "BaseEvaluation",
+]