snorben/EEG_preprocessing_UMCU

What is this software?

With our software, we hope to provide users with an accessible way to preprocess resting-state EEG files, while still including powerful analysis tools. We do this by combining several functions from the MNE (MEG/EEG preprocessing) open-source project. By using an intuitive graphical user interface on top of a Python script, we hope that our software is easy to start using without coding experience, while still allowing more experienced users to adapt the software to their needs by altering the underlying code.

The software is currently able to:

Open raw EEG files of type .txt, .bdf, .edf, .eeg and .fif.
Open a single EEG or choose analysis settings for an entire batch of files.
Apply a montage to the raw EEG (including electrode coordinates necessary for some analyses).
Drop bad channels entirely.
Interpolate bad channels after visual inspection.
Apply an average reference.
Apply independent component analysis to remove artefacts.
Apply beamformer source reconstruction to the EEG (standard MNE LCMV beamformer with standard head model).
Down sample the file to a lower sample frequency.
Perform interactive visual epoch selection.
Perform filtering in different frequency bands and broadband output.
After performing analyses on a batch, rerun the batch with preservation of channel and epoch selection.
Log the chosen settings and performed analyses steps in a log file.

The software is not (yet) able to:

Analyse task EEG data.
Calculate quantitative features on the output epochs (coming in the near future).
Open EEG files with data types not mentioned previously (you can put this in a new GitHub issue if you need another filetype).

Tips for use and known issues

When choosing the settings for the current analysis batch, most windows contain a "more info" button which will take you to an appropriate MNE documentation page.

When no raw EEG files show up in the file selection window, please choose a different file type in the dropdown menu on the right (it might be stuck on only showing .txt files for instance).

For the bad channel selection (for interpolation), you can select bad channels by clicking the channel names on the left side of the plot. The deselected (grey) channels will be interpolated. For ICA, this works the same but then artefact-containing components can be deselected in the graph plot of the ICA. These components will be filtered out of the EEG. For interactive epoch selection, epochs of insufficient quality can be deselected by clicking anywhere on the epoch, which will then turn red. This means the epoch will not be saved.

If the program glitches or stops working, we found that it works best to stop the Python process, for instance by clicking the red stop button or restarting the kernel in Spyder IDE or similar.

There is currently an unresolved problem where removing multiple ICA components and/or interpolating channels can result in a data rank that is too low to caculate the beamforming solution. See here for an explanation of this problem.

When using Spyder IDE to run the program (like we do), Spyder prompts the user that Spyder does not have the spyder-kernels module. Please follow the instructions provided by Spyder.

Installation

This guide will walk you through the process of setting up the EEG Preprocessing Tool using Miniconda. Miniconda provides an easy way to create isolated Python environments and manage package dependencies.

1. Install Miniconda and Git

First, download and install Miniconda:

For Windows: Miniconda Windows Installer
For macOS: Miniconda macOS Installer
For Linux: Miniconda Linux Installer

Follow the installation instructions provided on the Miniconda website.

If not done already, install Git.

2. Set up a Conda Environment

Open a terminal (or Anaconda Prompt on Windows) and run the following commands:

# Create a new conda environment named 'eeg_env' with Python 3.11
conda create -n eeg_env python=3.11

# Activate the new environment
conda activate eeg_env

3. Clone the Repository

Clone the EEG Preprocessing Tool repository:

git clone https://github.com/snorben/eeg_preprocessing_umcu.git
cd eeg_preprocessing_umcu

4. Install the Package and Dependencies

Install the package and its dependencies using pip:

python -m pip install .

5. Verify Installation

To verify that the installation was successful, you can try running the main script (eeg_processing_script.py) in your favorite way (we have used Spyder to run the script during development). For the first use, it is important to select your newly created Miniconda environment in your IDE. In Spyder this is done via: preferences > Python interpreter > use the following interpreter. When opening the script in an IDE like Spyder, you can simply press 'run' to start the script. If everything is set up correctly, the script should run without any import errors.

Troubleshooting

If you encounter any issues during installation:

Make sure you have activated the conda environment (conda activate eeg_env).
Try updating pip: python -m pip install --upgrade pip
If you encounter any dependency conflicts, you can try installing dependencies manually:
```
conda install numpy pandas matplotlib scikit-learn
pip install PySimpleGUI mne
```

For any further issues, please open an issue on the GitHub repository.

Updating the Software

When there's an update available on GitHub, follow these steps to update your local installation:

Navigate to the Project Directory Open a terminal (or Anaconda Prompt on Windows) and navigate to your project directory:
```
cd path/to/eeg_preprocessing_umcu
```
Activate the Conda Environment Ensure you're using the correct environment:
```
conda activate eeg_env
```
Pull the Latest Changes Fetch and merge the latest changes from the GitHub repository:
```
git pull origin main
```
Update Dependencies If there are any changes to the dependencies, reinstall the package:
```
python -m pip install . --upgrade
```
This command will update the package and any new or updated dependencies.

If you encounter issues after updating:

Ensure your conda environment is up to date:

conda update --all

If you're still having problems, you can try creating a fresh environment:

conda deactivate
conda remove --name eeg_env --all
conda create -n eeg_env python=3.8
conda activate eeg_env
python -m pip install .

Contributing

If you want to contribute to the development of eeg_preprocessing_umcu, have a look at the contribution guidelines.

Credits

This package was created with Cookiecutter and the NLeSC/python-template.

Badges

(Customize these badges with your own links, and check https://shields.io/ or https://badgen.net/ to see which other badges are available.)

fair-software.eu recommendations
(1/5) code repository
(2/5) license
(3/5) community registry
(4/5) citation
(5/5) checklist
howfairis
Other best practices
Static analysis
Coverage
Documentation
GitHub Actions
Build
Citation data consistency
SonarCloud
MarkDown link checker