russellu / eegfmripy

python code for denoising eeg data from eeg-fmri experiments, and fusing with FMRI

eegfmripy

NOTE: This python code works, but it's sub-optimal for a number of reasons (Python-specific issues, and MNE-specific issues). We've implemented it in Matlab with much better results: https://github.com/gmierz/eegfmri-matlab

Python code for denoising eeg data from eeg-fmri experiments, and fusing eeg-fmri data.

A fully automatic pipeline for cleaning raw EEG data acquired inside the scanner.

The package performs the following in sequential order:

1. gradient artifact removal
2. ballistocardigram artifact removal

The following features may be added in the future:

1. Residual noise removal using ICA
2. EEG motion detection and censoring
3. Source localization of cleaned scalp space signal
4. Co-registration of source space with FMRI voxel space
5. Frequency specific EEG-FMRI correlations in each voxel
6. Time-varying heart rate based on frequency of EEG ballistocardiogram artifacts
7. Respiratory volume based on amplitude of EEG ballistocardiogram artifacts
8. Millisecond precise head motion amplitude based on broadband high frequency EEG power

NB: due to overhead, the maximum size EEG dataset for a computer with 16 Gb RAM is 1.5Gb, this will typically only be a problem during the gradient denoising step

Dependencies can be installed with

cd eegfmripy
python setup.py install

These dependencies are the same as for mne-python (https://github.com/mne-tools/mne-python/blob/master/README.rst).

After installation, you can run eegfmripy --help for more info. The pipelines available can be found in the clianalysis folder. Use the configuration YAML's in the configs folder for options that can be supplied to each script.

Example for the full clean - gradient artifact removal, followed by BCG artifact removal:

eegfmripy clean -c configs/config_clean.yml

eegfmripy's Issues

Move files to 'eegfmri' folder

To simplify integration in the future, we could move all the source files into a folder (either named 'eegfmri' or something else) with a 'init.py' file - leaving the README where it is now.

Add usage examples.

Examples for how to use the library need to be added.

Using eegfmripy with jupyter notebook

Hello, thanks for creating this tool. How can I apply this tool using Jupyter notebook?

If I pip in the repo:

pip install git+git://github.com/russellu/eegfmripy.git

I can access some functions with:

from eegfmripy.clianalysis import remove_gradient

But if I try to access other packages that need the helper functions (e.g., clean or basic_gradient), I run into an error, here is the traceback

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
<ipython-input-209-a0d5e9147731> in <module>
      4 import eegfmripy
      5 import sys
----> 6 from eegfmripy.clianalysis import remove_gradient, clean
      7 
      8 get_ipython().run_line_magic('matplotlib', 'inline')

~/anaconda3/envs/mnedev/lib/python3.7/site-packages/eegfmripy/clianalysis/clean.py in <module>
      5 
      6 from ..cli import AnalysisParser
----> 7 from ..clianalysis.run_bcg_denoise import remove_bcg
      8 from ..clianalysis.remove_gradient_single import remove_gradient
      9 

~/anaconda3/envs/mnedev/lib/python3.7/site-packages/eegfmripy/clianalysis/run_bcg_denoise.py in <module>
     12 from mne.preprocessing import ICA
     13 
---> 14 from ..clianalysis import remove_bcg as bcg_utils
     15 from ..utils import helpers
     16 from ..cli import AnalysisParser

~/anaconda3/envs/mnedev/lib/python3.7/site-packages/eegfmripy/clianalysis/remove_bcg.py in <module>
     12 
     13 from ..cli import AnalysisParser
---> 14 from ..utils.general_utils import write_same_line, finish_same_line
     15 
     16 log = logging.getLogger("eegfmripy")

ModuleNotFoundError: No module named 'eegfmripy.utils'

Any help would be appreciated.

Add tests.

This issue is for adding tests to the library. We can also add some CI tooling for this if we want to.

Add flake8 linting through Travis.

We should start enforcing a style early, it will make it easier for later. Since MNE Python uses flake8, we could add that type of linting for each push through Travis.

Remove all hardcoded values from everywhere.

There are many hard-coded values scattered across the tool. It would be good if they could be stored into a YAML configuration file (one for each script). For hard-coded values that are common across all, we can store them at the top of the utility scripts (or in a config that all utility functions check).

integrate slice timing with DICOM information

to perfectly align the EEG time series with FMRI volumes, the number of dummy volumes, multiband factor, and number of slices must be known. from this, the FMRI and EEG can be aligned by examing the gradient pulse shape in the EEG data.

Gradient Subtraction FFT takes a long time

On some OS/PC combinations (from what we can tell), the fft performed by numpy can be slow but it isn't that terrible. That said, there are some EEG datasets which will cause it to go 2-3x slower on those OS/PC combinations. This causes gradient subtraction to take hours to finish.

Stand-alone tool?

Would this be something we would like? i.e. a tool we could invoke from bash/CLI that does not require MNE to be used.

If so, we could use python's setuptools tool, here's an example of what I am thinking: https://github.com/gmierz/coco-tools/blob/new_tool/setup.py

If we don't want anything like this, we can close this issue.