Metadata-Version: 2.2
Name: tmseegpy
Version: 0.2.0
Summary: A pipeline for preprocessing and analyzing TMS-EEG data with a GUI developed using Streamlit
Author-email: LazyCyborg <hjarneko@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/LazyCyborg/tmseegpy
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.26.0
Requires-Dist: scipy>=1.12.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: mne>=1.9.0
Requires-Dist: mne-faster>=1.2
Requires-Dist: mne-qt-browser
Requires-Dist: scikit-learn>=1.4.0
Requires-Dist: tensorly>=0.8.0
Requires-Dist: matplotlib>=3.9.2
Requires-Dist: seaborn>=0.12.0
Requires-Dist: plotly>=5.13.0
Requires-Dist: PyQt6>=6.4.0
Requires-Dist: PyQt6-Qt6
Requires-Dist: PyQt6-sip
Requires-Dist: pyqtgraph>=0.13.0
Requires-Dist: streamlit>=1.24.0
Requires-Dist: tqdm
Requires-Dist: psutil
Requires-Dist: construct
Requires-Dist: appdirs
Requires-Dist: ipykernel
Requires-Dist: jupyter
Requires-Dist: matplotlib-inline
Requires-Dist: ipympl
Requires-Dist: PyOpenGL
Requires-Dist: pyopengl-accelerate
Requires-Dist: h5py>=3.10.0
Requires-Dist: streamlit>=1.24.0
Requires-Dist: plotly>=5.13.0
Requires-Dist: pyqtgraph>=0.13.0

# tmseegpy

This repository contains my attempt at building some sort of pipeline for preprocessing and analyzing Transcranial Magnetic Stimulation (TMS)-EEG data using python. I have attempted to implement some of the functionality found in TESA (https://github.com/nigelrogasch/TESA) which has been my guide and benchmark for the development. 

The pipeline includes steps for artifact removal, filtering, Independent Component Analysis (ICA), muscle artifact cleaning (using Tensorly), and analysis of Perturbational Complexity Index based on State transitions (PCIst) (Comolatti et al., 2019). The analysis of PCIst is just a copy paste from https://github.com/renzocom/PCIst/blob/master/PCIst/pci_st.py which is written by Renzo Comolatti. The code is mostly adapted from a very long jupyter notebook which used mostly native MNE-Python methods which I expanded to a toolbox that I have been using in my analyses. So the code base might not be very efficient. 

If you have trouble with the current dataloader and creates one that is compatible with multiple systems (maybe out of frustration) feel free to reach out to hjarneko@gmail.com. The package uses a modified version of the neurone_loader (https://github.com/heilerich/neurone_loader) to load the data from the Bittium NeurOne and convert it to an MNE-Python raw object. 


## Installation 

1. Clone the repository:

   ```bash
   git clone https://github.com/LazyCyborg/tmseegpy.git
   cd tmseegpy

2. Create a virtual environment (optional but very recommended):

   ```bash
   conda env create -f environment.yml
   conda activate tmseegpy
   ``` 

3. Install the package:

   ```bash
   pip install -e .
   ```


### Download Releases
Download the latest GUI release for your platform from:
https://github.com/LazyCyborg/tmseegpy/releases (look for GUI releases tagged with `gui-v*`)


### GUI Application (Recommended)

The GUI application provides an interactive way to load data, configure preprocessing steps, visualize data at each stage, and run the analysis.  
The GUI is bundled as a standalone application using PyInstaller, meaning it can be run without any additional Python installations or dependencies.

### Command-Line Arguments
Run tmseegpy --help for full list of command line arguments and default values. The CLI-version is mostly built so that experienced user can run batch processing of large datasets.

Note that, if run in fully automatic mode the code uses MNE-FASTER for both channel and epoch rejection and uses either an adapted version of the TESA classification algorithm of ICA-components 
or my own classification algorithm which classifies components based on the topography and number of peaks in the components. This means that a lot of cortical avtivity can be 
removed and artifacts can remain which probably makes the final result unreliable due to the low SNR of TEPs. However it might be useful as a quick first pass of a large dataset. 

### Example Usage

To run the pipeline with default settings with manual ICA component selection using MNEs QT viewer and PyQt6:

```bash
tmseegpy process --data_dir ./data_dir_with_TMSEEG_folder --output_dir ./your_output_dir
```

To run and for example disable ICA preprocessing and PCIst plots 

```bash
tmseegpy process --data_dir ./data_dir_with_TMSEEG_folder --output_dir ./your_output_dir --no_first_ica --no_second_ica --no_pcist
```

To enable PARAFAC muscle artifact removal :

```bash
tmseegpy process --data_dir ./data_dir_with_TMSEEG_folder --output_dir ./your_output_dir --parafac_muscle_artifacts
```

To enable saving of eeg data in .fif format during preprocessing for quality checks (plots will be saved in a steps directory):

```bash
tmseegpy process --data_dir ./data_dir_with_TMSEEG_folder --output_dir ./your_output_dir --save_preproc
```

3. Use the scripts:

Ofcourse it is also possible to use the separate parts of the pipeline in a Jupyter Notebook or similar (I mostly run it like this for debugging, and it is probably impractical to run an entire analysis pipeline like this):

```Python
from tmseegpy.preproc import TMSEEGPreprocessor
from tmseegpy.preproc import detect_tms_artifacts

processor = TMSEEGPreprocessor(raw=raw)

events = detect_tms_artifacts(raw=raw)

processor.fix_tms_artifact(events=events)

processor.run_ica(use_topo=True, manual_mode=False) ## For using automatic topography based classification of TMS-artifacts (I would however recommend to always inspect ICA components)


```
## Data Preparation for batch processing through the CLI

If running the code through the CLI your data should be organized in the following structure:

```
data/
└── TMSEEG/
    ├── session1/
    │     ├── DataSetSession.xml 
    ├── session2/
    │     ├── DataSetSession.xml 
    └── ...
```

- The `--data_dir` argument should point to the directory containing your TMS data (e.g., `data/`).
- Each session should be in its own subdirectory under `TMSEEG/`.

Or if using EDF or other formats that are directly compatible with MNE-Python
```
data/
└── TMSEEG/
    ├── session1.edf
    │    
    └──session2.edf/

```

# Processing Pipeline

Below is the **updated** pipeline that aligns with the **default parameters** used in the `run.py` script (and in roughly the same order). These steps are still modelled after the recommendations in:

> Comolatti, R., Pigorini, A., Casarotto, S., Fecchio, M., Faria, G., Sarasso, S., Rosanova, M., Gosseries, O., Boly, M., Bodart, O., Ledoux, D., Brichant, J. F., Nobili, L., Laureys, S., Tononi, G., Massimini, M., & Casali, A. G. (2019). A fast and general method to empirically estimate the complexity of brain responses to transcranial and intracranial stimulations. *Brain Stimulation, 12(5)*, 1280–1289. [https://doi.org/10.1016/j.brs.2019.05.013](https://doi.org/10.1016/j.brs.2019.05.013)

> [Nigel Rogasch’s TESA toolbox pipeline overview](https://nigelrogasch.gitbook.io/tesa-user-manual/example_pipelines)

And the TMS-artifact removal + ICA classification steps are guided by the open-source TESA toolbox:

> Rogasch NC, Sullivan C, Thomson RH, Rose NS, Bailey NW, Fitzgerald PB, Farzan F, Hernandez-Pavon JC. Analysing concurrent transcranial magnetic stimulation and electroencephalographic data: a review and introduction to the open-source TESA software. *NeuroImage.* 2017; 147:934-951.  
> Mutanen TP, Biabani M, Sarvas J, Ilmoniemi RJ, Rogasch NC. Source-based artifact-rejection techniques available in TESA, an open-source TMS-EEG toolbox. *Brain Stimulation.* 2020; In press.

---

## Example Pipeline 

Below is the pipeline **I use**, after iterating a lot and verifying that the final EEG looks reasonable (contains typical TEPs and stable PCI-values). It’s primarily tested on recordings from one healthy subject (awake/slightly somnolent). **Use at your own risk**—always visually check data quality.

## Notes on Quality Control
- *Always visually inspect final TMS-EEG waveforms* and confirm TEP latencies/amplitudes are physiologically reasonable.  
- PCI\_st is only meaningful if the data are relatively artifact-free and well-epoched.

---

## Order of steps 

1. Load data  
2. Set seed, find/create events
3. Drop unused channels (e.g., EMG)
4. Remove TMS artifact using baseline data (window: -5 - 2ms)
5. Filter raw EEG data (high-pass 1 Hz and low-pass: 100 Hz)
6. **Create epochs** (-0.8 to 0.8)  
7. **Average reference**  
8. **Remove bad channels** (threshold=3)  
9. **Remove bad epochs** (threshold=3)
10. **First ICA** (FastICA)  
11. **(Optional and very experimental) Clean muscle (PARAFAC)**
12. **Optional) Second ICA** (Infomax)  
13. **(Optional) SSP**
14. **Downsampling** (725 Hz)  
15. **(Optional) TEP plotting**
16. **PCIst**  


### TMSArtifactCleaner (which might work)

The TMSArtifactCleaner class is designed to detect and clean transcranial magnetic stimulation (TMS)-evoked muscle artifacts in EEG/MEG data using tensor decomposition techniques. It uses the tensorly library for tensor operations and mne for handling eeg data. and was inspired by the article by Tangwiriyasakul et al., 2019. 

Tangwiriyasakul, C., Premoli, I., Spyrou, L., Chin, R. F., Escudero, J., & Richardson, M. P. (2019). Tensor decomposition of TMS-induced EEG oscillations reveals data-driven profiles of antiepileptic drug effects. Scientific Reports, 9(1). https://doi.org/10.1038/s41598-019-53565-9

#### What it does 

- Artifact Detection: Uses Non-negative PARAFAC tensor decomposition to detect muscle artifacts in EEG epochs.
- Artifact Cleaning: Uses Tucker decomposition to clean the detected artifacts.
- Threshold Optimization: Includes a method to find the optimal detection threshold based on a target detection rate.

### Special Thanks

- **Dr. Silvia Casarotto** for kindly sharing code and verifying the preprocessing output
- **Dr. Nigel Rogasch** for sanctioning the adaptation of TESA in Python
- **Dr. Mats Svantesson** (Linköping University Hospital) for many hours of assistance with code, signal processing, and EEG data verification
- **Dr. Magnus Thordstein** (Linköping University Hospital) for providing access to TMS and TMS-EEG equipment for sample data collection
- **Dr. Andrew Wold, PhD** for teaching me how to use the TMS equipment
- **Gramfort et al.** for creating MNE-Python, which this program is built upon

  This project would not have been possible to complete without the support and contributions of these individuals.

## License

This project is licensed under the MIT License.

## References

The PCIst implementation is based on:

>  Comolatti, R., Pigorini, A., Casarotto, S., Fecchio, M., Faria, G., Sarasso, S., Rosanova, M., Gosseries, O., Boly, M., Bodart, O., Ledoux, D., Brichant, J. F., Nobili, L., Laureys, S., Tononi, G., Massimini, M., & Casali, A. G. (2019). A fast and general method to empirically estimate the complexity of brain responses to transcranial and intracranial stimulations. Brain Stimulation, 12(5), 1280–1289. https://doi.org/10.1016/j.brs.2019.05.013

The pipeline uses the MNE-Python library for EEG data processing:

>  Gramfort, A., Luessi, M., Larson, E., Engemann, D. A., Strohmeier, D., Brodbeck, C., Goj, R., Jas, M., Brooks, T., Parkkonen, L., & Hämäläinen, M. (2013). MEG and EEG data analysis with MNE-Python. Frontiers in Neuroscience, 7 DEC. https://doi.org/10.3389/fnins.2013.00267

The bad channel, and epoch detection uses MNE-FASTER:

>  Nolan H, Whelan R, Reilly RB. FASTER: Fully Automated Statistical Thresholding for EEG artifact Rejection. J Neurosci Methods. 2010 Sep 30;192(1):152-62. doi: 10.1016/j.jneumeth.2010.07.015. Epub 2010 Jul 21. PMID: 20654646.

The PARAFAC decomposition was modellled after:

>  Tangwiriyasakul, C., Premoli, I., Spyrou, L., Chin, R. F., Escudero, J., & Richardson, M. P. (2019). Tensor decomposition of TMS-induced EEG oscillations reveals data-driven profiles of antiepileptic drug effects. Scientific Reports, 9(1). https://doi.org/10.1038/s41598-019-53565-9

Custom functions are modelled after: 

>  Rogasch NC, Sullivan C, Thomson RH, Rose NS, Bailey NW, Fitzgerald PB, Farzan F, Hernandez-Pavon JC. Analysing concurrent transcranial magnetic stimulation and electroencephalographic data: a review and introduction to the open-source TESA software. NeuroImage. 2017; 147:934-951.

>  Mutanen TP, Biabani M, Sarvas J, Ilmoniemi RJ, Rogasch NC. Source-based artifact-rejection techniques available in TESA, an open-source TMS-EEG toolbox. Brain Stimulation. 2020; In press.
