MEEGkit: M/EEG Denoising in Python

MEEGkit is a Python 3.10+ library providing denoising tools for M/EEG (Magneto/Electroencephalography) processing. The library includes implementations of several signal processing and artifact removal methods, including:

• CCA, STAR, SNS, DSS, ZapLine, and Robust Detrending: Methods largely translated from the Matlab NoiseTools toolbox.
• Artifact Subspace Reconstruction (ASR): Includes standard and Riemannian variants.
• Rhythmic Entrainment Source Separation (RESS).
• Task-Related Component Analysis (TRCA).
• Local Outlier Factor (LOF): For density-based local outlier detection.
• Phase Estimation: Including oscillator code and Endpoint Corrected Hilbert Transform (ECHT).

The meegkit.utils package provides a collection of utility modules for signal processing, matrix manipulation, and specialized EEG/MEG analysis tasks. The available submodules are:

• auditory: Auditory-related signal processing.
• buffer: Buffer management utilities.
• coherence: Functions for calculating coherence.
• covariances: Covariance matrix calculation and manipulation.
• denoise: Denoising algorithms and techniques.
• matrix: General matrix manipulation utilities.
• sig: Signal processing utilities.
• stats: Statistical functions.
• trca: Utilities specifically for Task-Related Component Analysis (TRCA).

The meegkit.phase module provides tools for phase estimation and oscillator modeling. It includes classes for representing oscillators and devices, as well as functions for phase calculation and integration steps.

Key Classes

• ResOscillator: Represents a resonant oscillator.
• NonResOscillator: Represents a non-resonant oscillator.
• Device: Represents a measurement device.
• ECHT: (Specific implementation related to phase/oscillator modeling).

Key Functions

• locking_based_phase: Calculates phase based on locking mechanisms.
• rk: Likely implements a Runge-Kutta integration step for oscillator dynamics.
• init_coefs: Initializes coefficients for oscillator models.
• one_step_oscillator: Performs a single integration step for an oscillator.
• one_step_integrator: Performs a single integration step for a general integrator.

If you are new to the package, it is recommended to follow this sequence of examples to understand the different workflows:

1. example_asr: For a full artifact-removal workflow.
2. example_dss: For a simple synthetic component-recovery example.
3. example_trca or example_ress: For task-oriented spatial filtering.

Many of these examples use synthetic data with known ground truth, which is useful for verifying what each method is expected to recover.

MEEGkit supports optional dependency groups for specific features or workflows:

• [extra]: Installs additional dependencies required for certain ASR (Artifact Subspace Reconstruction) variants, such as pymanopt.
• [docs]: Installs dependencies required to build the documentation.
• [tests]: Installs dependencies required to run unit tests.

You can install these using the following syntax:

# Install with extra features (e.g., for ASR variants)
pip install meegkit[extra]

# Or from a local source in developer mode
pip install -e '.[extra]'

# Install documentation dependencies
pip install meegkit[docs]

# Install test dependencies
pip install meegkit[tests]

Install the core meegkit package using pip. Note that meegkit requires Python 3.8+.

If you intend to use ASR (Artifact Subspace Reconstruction) related functionality, you must install the optional dependencies by using the [extra] flag.

# Standard installation
pip install meegkit

# Installation with optional dependencies for ASR functionality
pip install 'meegkit[extra]'

MEEGkit provides a gallery of example scripts to demonstrate basic usage of its methods. These examples are categorized into two types:

1. Synthetic sanity checks: Used when the ground truth is known, allowing you to judge the accuracy of a method directly.
2. Workflow-style demonstrations: Designed to show how to interpret outputs when working with more realistic data.

Suggested starting points

Depending on your goal, use the following scripts as guides:

• Artifact-subspace reconstruction: Use example_asr.
• Compact repeated-signal processing: Use example_dss.
• Line-noise removal: Use example_dss_line.
• Block-wise classification performance: Use example_trca.

Note: Some examples, such as example_trca or those in the notebook-executed gallery, may require more computation time than the smaller synthetic demos.

To install from a local clone of the repository, navigate to the python-meegkit directory and run:

pip install -r requirements.txt
pip install .

To install in developer mode (allowing you to modify the source code and have changes reflected immediately), use the -e flag:

pip install -e .