mini-mne 0.1.0__tar.gz

mini_mne-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.3
+Name: mini-mne
+Version: 0.1.0
+Summary: A simplified MNE-Python wrapper for teaching EEG analysis
+Author: Ina Bornkessel-Schlesewsky
+License: BSD-3-Clause
+Requires-Dist: autoreject>=0.4.3
+Requires-Dist: mne>=1.12.0
+Requires-Dist: mne-bids>=0.18.0
+Requires-Dist: mpld3>=0.5.12
+Requires-Dist: numpy>=1.21
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# mini-mne
+
+A simplified wrapper around [MNE-Python](https://mne.tools) for teaching EEG data analysis. mini-mne exposes only the essential classes and methods, reducing the cognitive load for learners who are new to EEG preprocessing and analysis.
+
+## Installation
+
+```bash
+pip install --upgrade mini-mne
+```
+
+Requires Python ≥ 3.11.
+
+## Usage
+
+mini-mne follows the standard EEG analysis pipeline: load continuous data → epoch around events → compute ERPs.
+
+```python
+from mini_mne import SimpleRaw, SimpleEpoch, SimpleEvoked, plot_evokeds
+
+# Load data (downloads the MNE ERP-CORE example dataset if no path is given)
+raw = SimpleRaw()
+
+# Inspect the data
+print(raw)
+print(raw.sampling_frequency)  # Hz
+print(raw.channel_names)
+print(raw.duration)            # seconds
+
+# Preprocess
+raw = raw.filter(l_freq=0.1, h_freq=40.0)
+raw = raw.re_reference()
+
+# Extract events from annotations
+events, event_id = raw.get_events()
+
+# Epoch the data
+epochs = SimpleEpoch(raw, events, event_id,
+                     tmin=-0.2, tmax=0.8,
+                     baseline=(-0.2, 0),
+                     reject={"eeg": 100e-6})
+
+print(epochs)
+print(epochs.event_types)
+print(epochs.dropped_epochs)
+
+# Compute ERPs
+evokeds = epochs.average(by_event_type=True)
+
+# Plot
+plot_evokeds(evokeds)
+```
+
+## Classes
+
+| Class | Wraps | Purpose |
+|---|---|---|
+| `SimpleRaw` | `mne.io.Raw` | Continuous EEG data |
+| `SimpleEpoch` | `mne.Epochs` | Segmented data around events |
+| `SimpleEvoked` | `mne.Evoked` | Averaged ERP |
+
+## Licence
+
+mini-mne is licenced under the [BSD-3-Clause licence](LICENSE).
+
+## Acknowledgements
+
+mini-mne is built on top of [MNE-Python](https://mne.tools). The default example dataset is from the [ERP-CORE dataset](https://osf.io/thsqg/) (Kappenman et al., 2021).

mini_mne-0.1.0/README.md

@@ -0,0 +1,67 @@
+# mini-mne
+
+A simplified wrapper around [MNE-Python](https://mne.tools) for teaching EEG data analysis. mini-mne exposes only the essential classes and methods, reducing the cognitive load for learners who are new to EEG preprocessing and analysis.
+
+## Installation
+
+```bash
+pip install --upgrade mini-mne
+```
+
+Requires Python ≥ 3.11.
+
+## Usage
+
+mini-mne follows the standard EEG analysis pipeline: load continuous data → epoch around events → compute ERPs.
+
+```python
+from mini_mne import SimpleRaw, SimpleEpoch, SimpleEvoked, plot_evokeds
+
+# Load data (downloads the MNE ERP-CORE example dataset if no path is given)
+raw = SimpleRaw()
+
+# Inspect the data
+print(raw)
+print(raw.sampling_frequency)  # Hz
+print(raw.channel_names)
+print(raw.duration)            # seconds
+
+# Preprocess
+raw = raw.filter(l_freq=0.1, h_freq=40.0)
+raw = raw.re_reference()
+
+# Extract events from annotations
+events, event_id = raw.get_events()
+
+# Epoch the data
+epochs = SimpleEpoch(raw, events, event_id,
+                     tmin=-0.2, tmax=0.8,
+                     baseline=(-0.2, 0),
+                     reject={"eeg": 100e-6})
+
+print(epochs)
+print(epochs.event_types)
+print(epochs.dropped_epochs)
+
+# Compute ERPs
+evokeds = epochs.average(by_event_type=True)
+
+# Plot
+plot_evokeds(evokeds)
+```
+
+## Classes
+
+| Class | Wraps | Purpose |
+|---|---|---|
+| `SimpleRaw` | `mne.io.Raw` | Continuous EEG data |
+| `SimpleEpoch` | `mne.Epochs` | Segmented data around events |
+| `SimpleEvoked` | `mne.Evoked` | Averaged ERP |
+
+## Licence
+
+mini-mne is licenced under the [BSD-3-Clause licence](LICENSE).
+
+## Acknowledgements
+
+mini-mne is built on top of [MNE-Python](https://mne.tools). The default example dataset is from the [ERP-CORE dataset](https://osf.io/thsqg/) (Kappenman et al., 2021).

mini_mne-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "mini-mne"
+version = "0.1.0"
+description = "A simplified MNE-Python wrapper for teaching EEG analysis"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "BSD-3-Clause" }
+authors = [{ name = "Ina Bornkessel-Schlesewsky" }]
+dependencies = [
+    "autoreject>=0.4.3",
+    "mne>=1.12.0",
+    "mne-bids>=0.18.0",
+    "mpld3>=0.5.12",
+    "numpy>=1.21",
+]
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[tool.pytest.ini_options]

mini_mne-0.1.0/src/mini_mne/__init__.py

@@ -0,0 +1,3 @@
+from .raw import SimpleRaw
+from .epochs import SimpleEpoch
+from .evoked import SimpleEvoked, plot_evokeds

mini_mne-0.1.0/src/mini_mne/epochs.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import mne
+from .raw import SimpleRaw
+from .evoked import SimpleEvoked
+
+class SimpleEpoch:
+    """
+    A simplified wrapper around MNE's Epoch object for teaching purposes.
+    Exposes only essential attributes and methods.
+    """
+    def __init__(self,
+                 raw: SimpleRaw,
+                 events=None,
+                 event_id=None,
+                 tmin: float = -0.2,
+                 tmax: float = 1.0,
+                 baseline: tuple | None = None,
+                 reject: dict | None = None):
+        """
+        Parameters
+        ----------
+        raw : SimpleRaw
+            The continuous EEG data to epoch.
+        events : np.ndarray, shape (n_events, 3)
+            Event array as returned by SimpleRaw.get_events().
+        event_id : dict
+            Mapping of event labels to integer IDs, as returned by
+            SimpleRaw.get_events().
+        tmin : float
+            Start of the epoch in seconds, relative to the event onset.
+        tmax : float
+            End of the epoch in seconds, relative to the event onset.
+        baseline : tuple or None
+            Time interval for baseline correction as (tmin, tmax) in seconds.
+            None applies no baseline correction.
+        reject : dict or None
+            Peak-to-peak amplitude rejection thresholds, e.g.
+            {'eeg': 100e-6} rejects epochs exceeding 100 µV.
+            None applies no rejection.
+        """
+        base_raw = raw._raw
+
+        epochs = mne.Epochs(base_raw, events, event_id, tmin, tmax,
+                            baseline=baseline, reject=reject, preload=True)
+        self._epochs = epochs
+
+    @property
+    def event_types(self) -> list:
+        """Get the list of event type labels."""
+        return list(self._epochs.event_id.keys())
+
+    @property
+    def time_range(self) -> tuple[float, float]:
+        """Get the epoch time range in seconds as (tmin, tmax)."""
+        return self._epochs.tmin, self._epochs.tmax
+
+    @property
+    def dropped_epochs(self) -> int:
+        """Get the number of dropped epochs."""
+        return len([d for d in self._epochs.drop_log if len(d) > 0])
+
+    def __str__(self):
+        event_labels = ", ".join(self.event_types)
+        tmin, tmax = self.time_range
+        return (f"Epoch object | {len(self)} epochs; "
+                f"event types: {event_labels}; "
+                f"time range: {tmin}–{tmax} s; "
+                f"{self.dropped_epochs} dropped")
+
+    def __repr__(self):
+        return repr(self._epochs)
+
+    def __len__(self):
+        return len(self._epochs)
+
+    def __iter__(self):
+        return iter(self._epochs)
+
+    def __dir__(self):
+        return ['event_types', 'time_range', 'dropped_epochs', 'average', 'plot']
+
+    @classmethod
+    def _from_epochs(cls, epochs: mne.Epochs) -> "SimpleEpoch":
+        """Wrap an existing mne.Epochs object without going through __init__."""
+        instance = cls.__new__(cls)
+        instance._epochs = epochs
+        return instance
+
+    def __getitem__(self, item) -> "SimpleEpoch":
+        return SimpleEpoch._from_epochs(self._epochs[item])
+
+    def average(self, by_event_type: bool = False) -> SimpleEvoked | list[SimpleEvoked]:
+        """Compute the ERP by averaging across epochs.
+
+        Parameters
+        ----------
+        by_event_type : bool
+            If False (default), average across all epochs regardless of
+            condition, returning a single SimpleEvoked. If True, average
+            separately per condition, returning a list of SimpleEvoked
+            (one per event type).
+
+        Returns
+        -------
+        SimpleEvoked or list of SimpleEvoked
+        """
+        evoked = self._epochs.average(by_event_type=by_event_type)
+        if isinstance(evoked, list):
+            return [SimpleEvoked(e) for e in evoked]
+        else:
+            return SimpleEvoked(evoked)
+
+    def plot(self, *args, **kwargs):
+        return self._epochs.plot(*args, **kwargs)
+
+
+

mini_mne-0.1.0/src/mini_mne/evoked.py

@@ -0,0 +1,79 @@
+import mne
+
+
+class SimpleEvoked:
+    """
+    A simplified wrapper around MNE's Evoked object for teaching purposes.
+    Exposes only essential attributes and methods.
+    """
+    def __init__(self, evoked: mne.Evoked):
+        """
+        Parameters
+        ----------
+        evoked : mne.Evoked
+            The underlying MNE Evoked object, typically obtained via
+            SimpleEpoch.average().
+        """
+        self._evoked = evoked
+
+    @property
+    def comment(self) -> str:
+        """Get the event type label."""
+        return self._evoked.comment
+
+    @property
+    def nave(self) -> int:
+        """Get the number of averaged epochs."""
+        return self._evoked.nave
+
+    @property
+    def time_range(self) -> tuple[float, float]:
+        """Get the time range in seconds as (tmin, tmax)."""
+        return self._evoked.times[0], self._evoked.times[-1]
+
+    @property
+    def channel_names(self) -> list:
+        """Get the list of channel names."""
+        return self._evoked.ch_names
+
+    def __str__(self):
+        tmin, tmax = self.time_range
+        return (f"Evoked object | condition: {self.comment}; "
+                f"{self.nave} epochs averaged; "
+                f"time range: {tmin:.3f}–{tmax:.3f} s; "
+                f"{len(self.channel_names)} channels")
+
+    def __repr__(self):
+        return repr(self._evoked)
+
+    def __dir__(self):
+        return ['comment', 'nave', 'time_range', 'channel_names', 'plot']
+
+    def plot(self, *args, **kwargs):
+        return self._evoked.plot(*args, **kwargs)
+
+
+def _unwrap(e: "SimpleEvoked | mne.Evoked") -> mne.Evoked:
+    return e._evoked if isinstance(e, SimpleEvoked) else e
+
+
+def plot_evokeds(
+    evokeds: "SimpleEvoked | mne.Evoked | list | dict",
+    *args,
+    **kwargs
+):
+    """Plot and compare evoked responses.
+
+    Parameters
+    ----------
+    evokeds : SimpleEvoked, mne.Evoked, list, or dict of str -> evoked
+        The evoked response(s) to plot. Accepts SimpleEvoked wrappers or
+        raw mne.Evoked objects interchangeably.
+    """
+    if isinstance(evokeds, (SimpleEvoked, mne.Evoked)):
+        unwrapped = _unwrap(evokeds)
+    elif isinstance(evokeds, dict):
+        unwrapped = {label: _unwrap(e) for label, e in evokeds.items()}
+    else:
+        unwrapped = [_unwrap(e) for e in evokeds]
+    return mne.viz.plot_compare_evokeds(unwrapped, *args, **kwargs)

mini_mne-0.1.0/src/mini_mne/raw.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import mne
+import numpy as np
+from pathlib import Path
+from .raw_io import DefaultImportRawHandler, FileImportRawHandler
+
+class SimpleRaw:
+    """
+    A simplified wrapper around MNE's Raw object for teaching purposes.
+    Exposes only essential attributes and methods.
+    """
+    def __init__(self, raw_input: mne.io.BaseRaw | Path | None = None):
+        """
+        Parameters
+        ----------
+        raw_input : mne.io.BaseRaw, Path, or None
+            The data source. Pass an MNE Raw object to wrap it directly, a
+            Path to load from a BrainVision file, or None to download and
+            use the MNE ERP-CORE example dataset.
+        """
+        # If no raw object and no path is provided, download and use an MNE example file instead
+        if raw_input is None:
+            handler = DefaultImportRawHandler()
+            self._raw = handler.load_raw()
+        elif isinstance(raw_input, mne.io.BaseRaw):
+            self._raw = raw_input
+        else:
+            file_path = Path(raw_input)
+            handler = FileImportRawHandler(file_path)
+            self._raw = handler.load_raw()
+
+    # Attributes (read-only properties)
+    @property
+    def sampling_frequency(self) -> float:
+        """Get the sampling frequency in Hz."""
+        return self._raw.info['sfreq']
+
+    @property
+    def channel_names(self) -> list:
+        """Get the list of channel names."""
+        return self._raw.ch_names
+
+    @property
+    def duration(self) -> float:
+        """Get the duration in seconds."""
+        return self._raw.duration
+
+    @property
+    def frequency_range(self) -> tuple[float, float]:
+        """Get the frequency range in Hz: tuple of lowpass and highpass frequencies. """
+        return self._raw.info['highpass'], self._raw.info['lowpass']
+
+    @property
+    def custom_reference(self) -> bool:
+        """Has a custom reference been applied"""
+        return bool(self._raw.info['custom_ref_applied'])
+
+    def __str__(self):
+        return f"Raw (continuous) EEG object | length: {self._raw.duration} seconds; {len(self._raw.ch_names)} channels"
+
+    def __repr__(self):
+        return f"MiniRaw(raw={self._raw})"
+
+    def __dir__(self):
+        return ['sampling_frequency', 'channel_names', 'duration', 'custom_reference',
+                'plot', 'plot_psd', 'filter', 're_reference', 'get_events']
+
+    # Methods
+    def plot(self, *args, **kwargs):
+        return self._raw.plot(*args, **kwargs)
+
+    def plot_psd(self, fmin: float = 0, fmax: float = np.inf,
+                 tmin: float | None = None, tmax: float | None = None, **kwargs):
+        """Plot the power spectral density (PSD) using Welch's method.
+
+        Parameters
+        ----------
+        fmin : float
+            Lower frequency bound in Hz.
+        fmax : float
+            Upper frequency bound in Hz.
+        tmin : float or None
+            Start of the time window in seconds. None uses the start of the recording.
+        tmax : float or None
+            End of the time window in seconds. None uses the end of the recording.
+        **kwargs
+            Additional arguments passed to the MNE PSD plot function.
+        """
+        return self._raw.compute_psd(method='welch', fmin=fmin, fmax=fmax,
+                                     tmin=tmin, tmax=tmax).plot(**kwargs)
+
+    def filter(self, l_freq: float, h_freq: float) -> SimpleRaw:
+        """
+        Apply a bandpass filter to the data.
+
+        Parameters
+        ----------
+        l_freq : float
+            Low frequency cutoff in Hz (e.g., 0.1 for high-pass at 0.1 Hz)
+        h_freq : float
+            High frequency cutoff in Hz (e.g., 40 for low-pass at 40 Hz)
+
+        Returns
+        -------
+        SimpleRaw
+            A new SimpleRaw object with filtered data
+        """
+        filtered_raw = self._raw.copy().filter(l_freq=l_freq, h_freq=h_freq)
+        return SimpleRaw(filtered_raw)
+
+    def re_reference(self, ref_channels: list | None = None) -> SimpleRaw:
+        """
+        Re-reference the data.
+
+        Parameters
+        ----------
+        ref_channels : list or None
+            Channel(s) to use as reference. If None, uses average reference.
+
+        Returns
+        -------
+        SimpleRaw
+            A new SimpleRaw object with re-referenced data
+        """
+        reref_raw = self._raw.copy()
+        if ref_channels is None:
+            # Average reference
+            reref_raw.set_eeg_reference('average')
+        else:
+            reref_raw.set_eeg_reference(ref_channels)
+        return SimpleRaw(reref_raw)
+
+    def get_events(self) -> tuple[np.ndarray, dict]:
+        """Extract events from annotations.
+
+        Returns
+        -------
+        events : np.ndarray, shape (n_events, 3)
+            Array of events (sample, duration, event_id).
+        event_id : dict
+            Mapping of event labels to integer IDs.
+        """
+        return mne.events_from_annotations(self._raw)
+
+

mini_mne-0.1.0/src/mini_mne/raw_io.py

@@ -0,0 +1,56 @@
+import mne
+import os.path as op
+from pathlib import Path
+from typing import Protocol
+
+class ImportRawHandler(Protocol):
+    """Protocol for reading data into the SimpleRaw class"""
+
+    def load_raw(self, directory: Path | None) -> mne.io.Raw:
+        """Read data from file and return a mne.io.Raw object"""
+        ...
+
+    # def save_raw(self, directory: Path, raw: mne.io.Raw) -> None:
+    #     """Save data to file"""
+    #     ...
+
+class DefaultImportRawHandler:
+    """Default implementation of ImportRawHandler Protocol using MNE example data"""
+
+    FIF_FILE = "ERP-CORE_Subject-001_Task-Flankers_eeg.fif"
+
+    def load_raw(self, directory: Path | None = None) -> mne.io.Raw:
+        if directory is None:
+            directory = Path(".")
+        else:
+            directory = Path(directory)
+            directory.mkdir(parents=True, exist_ok=True)
+        # extend this later so that the user can abort if this is not what they want
+        # could also give them a choice of path?
+        print("No raw data provided, downloading MNE sample data to {directory}.")
+        data_path = mne.datasets.erp_core.data_path(directory)
+
+        erp_core_file = data_path / self.FIF_FILE
+        print(f"Downloaded {erp_core_file}.")
+        raw = mne.io.read_raw_fif(erp_core_file, preload=True)
+
+        return raw
+
+    # def save_raw(self, directory: Path, raw: mne.io.Raw) -> None:
+    #     """Save data to file"""
+
+class FileImportRawHandler:
+    """
+    Implementation of ImportRawHandler Protocol that reads raw data from file.
+    Only equipped to handle BrainVision at the moment.
+    """
+    # Extend this to handle fif and BIDS
+    # perhaps use a dispatch dictionary?
+    def __init__(self, directory: Path):
+        directory = Path(directory)
+        self.directory = directory
+
+    def load_raw(self) -> mne.io.Raw:
+        raw = mne.io.read_raw_brainvision(self.directory, preload=True)
+        return raw
+