Metadata-Version: 2.4
Name: pytep-sound-sspsir
Version: 0.1.1
Summary: SOUND & SSP-SIR algorithms for TMS-EEG artifact cleaning (MNE + MATLAB Engine)
Project-URL: Homepage, https://github.com/MarcioCamposJr
Project-URL: Repository, https://github.com/MarcioCamposJr/PyTEP-SOUND-SSP-SIR
Author: Marcio Campos
License: MIT
Keywords: EEG,MNE,SOUND,SSP-SIR,TMS,artifact,cleaning
Requires-Python: >=3.10
Requires-Dist: matlabengine>=24.1
Requires-Dist: mne>=1.11.0
Requires-Dist: numpy>=2.4.2
Description-Content-Type: text/markdown

# 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

```bash
# From the repository root
pip install -e .

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

## Quick Start

### SOUND (Mutanen et al., 2018)

```python
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)

```python
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

```python
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
