pytep-sound-sspsir 0.1.1

SOUND & SSP-SIR algorithms for TMS-EEG artifact cleaning (MNE + MATLAB Engine)

pytep — Python TMS-EEG Processing

SOUND and SSP-SIR algorithms for TMS-EEG artifact cleaning, bridging MNE-Python and MATLAB Engine.

Requirements

• Python ≥ 3.11
• MATLAB (with a valid license)
• MATLAB Engine for Python (matlabengine)
• MNE-Python

Installation

# From the repository root
pip install -e .

# With notebook extras (jupyter, matplotlib, etc.)
pip install -e ".[notebooks]"

Quick Start

SOUND (Mutanen et al., 2018)

import mne
from pytep import apply_sound

# Load your data
raw = mne.io.read_raw_edf("your_data.edf", preload=True)
raw.set_montage("standard_1020")

# Apply SOUND
raw_clean = apply_sound(raw, iter_num=5, lambda_val=0.1)

SSP-SIR (Mutanen et al., 2016)

import mne
from pytep import apply_sspsir

# Load epoched data
epochs = mne.read_epochs("your_epochs-epo.fif", preload=True)

# Apply SSP-SIR
epochs_clean = apply_sspsir(epochs, pc=2, art_scale='automatic')

Sharing a MATLAB Engine session

import matlab.engine
from pytep import apply_sound, apply_sspsir

eng = matlab.engine.start_matlab()

raw_clean = apply_sound(raw, eng=eng)
epochs_clean = apply_sspsir(epochs, eng=eng, pc=2)

eng.quit()

API Reference

apply_sound(inst, eng=None, iter_num=5, lambda_val=0.1)

Parameter	Type	Description
inst	Raw/Epochs	MNE object with EEG data (montage required)
eng	MatlabEngine	Existing MATLAB session (optional)
iter_num	int	Number of SOUND iterations (default: 5)
lambda_val	float	Regularization parameter (default: 0.1)

apply_sspsir(inst, eng=None, art_scale='automatic', time_range=None, pc=1, M=None)

Parameter	Type	Description
inst	Epochs	Epoched MNE data (montage required)
eng	MatlabEngine	Existing MATLAB session (optional)
art_scale	str	'automatic', 'manual', or 'manualConstant'
time_range	list[float]	[start_ms, end_ms] artifact window
pc	int	Number of artifact PCs to remove (default: 1)
M	int/None	SIR truncation dimension

References

• SOUND: Mutanen, T. P., et al. (2018). Automatic and robust noise suppression in EEG and MEG: The SOUND algorithm. NeuroImage, 166, 135-151.
• SSP-SIR: Mutanen, T. P., et al. (2016). Recovering TMS-evoked EEG responses masked by muscle artifacts. NeuroImage, 139, 157-166.

License

MIT