DeepEEG / Git / Diff of /README.md

Models:

ReneeD/

DeepEEG

Downloads: 1

Diff of /README.md [e6696a] .. [723930]

Switch to unified view


## DeepEEG ##

MNE/Keras/Tensorflow library for classification of EEG data

* [Kyle E. Mathewson](https://github.com/kylemath)
* [Kory W. Mathewson](https://github.com/korymath)



DeepEEG is a Keras/Tensorflow deep learning library that processes EEG trials or raw files from the MNE toolbox as input and predicts binary trial category as output (could scale to multiclass?). 

CAN 2019 Poster presentation on DeepEEG - https://docs.google.com/presentation/d/1hO9wKwBVvfXDtUCz7kVRc0A6BsSwX-oVBsDMgrFwLlg/edit?usp=sharing

## Collab notebooks for cloud compution

Colab Notebook Example with simulated data:
https://colab.research.google.com/github/kylemath/DeepEEG/blob/master/notebooks/DeepEEG_Sim.ipynb

Colab Notebook Example with data from Brain Vision Recorder in google drive:
https://colab.research.google.com/github/kylemath/DeepEEG/blob/master/notebooks/Deep_EEG_BV.ipynb

Colab Notebook Example with muse data from [NeurotechX](https://github.com/neurotechx) eeg-notebooks:
https://colab.research.google.com/github/kylemath/DeepEEG/blob/master/notebooks/Deep_EEG_Muse.ipynb

## Getting Started Locally:

DeepEEG is tested on macOS 10.14 with Python3.
Prepare your environment the first time:

```sh
# using virtualenv
 python3 -m venv deepeeg
 source deepeeg/bin/activate
# using conda
#conda create -n deepeeg python=3
#source activate deepeeg

```

```sh
git clone https://github.com/kylemath/DeepEEG/
cd DeepEEG
./install.sh
git clone https://github.com/kylemath/eeg-notebooks_v0.1

```

You are now ready to run DeepEEG.

For example, type ```python``` and use the following:
This loads in some example data from eeg-notebooks

```python
from utils import *
data_dir = 'visual/cueing'
subs = [101,102]
nsesh = 2
event_id = {'LeftCue': 1,'RightCue': 2}
```
Load muse data, preprocess into trials,prepare for model, create model, and train and test model

```python
#Load Data
raw = LoadMuseData(subs,nsesh,data_dir)
```

```python
#Pre-Process EEG Data
epochs = PreProcess(raw,event_id)
```

```python
#Engineer Features for Model
feats = FeatureEngineer(epochs)
```

```python
#Create Model
model,_ = CreateModel(feats)
```

```python
#Train with validation, then Test
TrainTestVal(model,feats)
```

## Tests

You can run the unittests with the following command:
```
python -m unittest tests
```

## Strategy
* Load in Brain Products or Interaxon Muse files with mne as mne.raw,
* PreProcess(mne.raw) - normal ERP preprocessing to get trials by time by electrode mne.epochs
* FeatureEngineer(mne.epochs) - Either time domain or frequency domain feature extraction in DeepEEG.Feats class
* CreateModel(DeepEEG.Feats) - Customizes DeepEEG.Model for input data, pick from NN, CNN, LSTM, or AutoEncoders, splits data
* TrainTestVal(DeepEEG.Feats,DeepEEG.Model) - Train the model, validate it during training, and test it once complete, Plot loss during learning and at test

## Dataset example
* Interaxon Muse - eeg-notebooks -  https://github.com/kylemath/eeg-notebooks
* Brain Recorder Data

## API
* Input the data directory and subject numbers of any eeg-notebook experiment (https://github.com/kylemath/eeg-notebooks)
* Load in .vhdr brain products files by filename with mne io features
* FeatureEngineer can load any mne Epoch object too - https://martinos.org/mne/stable/generated/mne.Epochs.html

## Preprocessing
* To be moved to another repo eventually
* Bandpass filter
* Regression Eye movement correction (if eye channels)
  - EOG Regression example: https://cbrnr.github.io/2017/10/20/removing-eog-regression/
  - Original emcp paper: https://apps.dtic.mil/dtic/tr/fulltext/u2/a125699.pdf
  - Generalized emcp paper: http://www.kylemathewson.com/wp-content/uploads/2010/03/MillerGrattonYee-1988-GeneralizeOcularRemoval.pdf
  - 1988 Fortran, Gehring C code: http://gehringlab.org/emcp2001.zip
  - Matlab implementation: https://github.com/kylemath/MathewsonMatlabTools/blob/master/EEG_analysis/gratton_emcp.m
* Epoch segmentation (time limits, baseline correction)
* Artifact rejection

## LearningModels
* First try basic Neural Network (NN)
* Then try Convolution Neural Net (CNN)
* New is a 3D convolutional NN (CNN3D) in the frequency domain
* Then try Long-Short Term Memory Recurrant Neural Net (LSTM)
* Can also try using (AUTO) or (AUTODeep) to clean eeg data, or create features for other models

## DataModels
* Try subject specific models
* Then pool data over all subjects
* Then try multilevel models (in the works)

## Benchmarks
* Goal build models that can be integrated with https://github.com/NeuroTechX/moabb/

## Code References
* https://github.com/kylemath/eeg-notebooks
* https://github.com/mne-tools/mne-python
* https://github.com/keras-team/keras/blob/master/examples/imdb_cnn_lstm.py
* https://github.com/ml4a/ml4a-guides/blob/master/notebooks/keras_classification.ipynb
* https://github.com/tevisgehr/EEG-Classification

## Resources
* https://arxiv.org/pdf/1901.05498.pdf
* http://proceedings.mlr.press/v56/Thodoroff16.pdf
* https://arxiv.org/abs/1511.06448
* https://github.com/ml4a
* http://oxfordre.com/neuroscience/view/10.1093/acrefore/9780190264086.001.0001/acrefore-9780190264086-e-46
* https://arxiv.org/pdf/1811.10111.pdf

	a/README.md		b/README.md
1	## DeepEEG ##	1	## DeepEEG ##
2		2
3	MNE/Keras/Tensorflow library for classification of EEG data	3	MNE/Keras/Tensorflow library for classification of EEG data
4		4
5	* [Kyle E. Mathewson](https://github.com/kylemath)	5	* [Kyle E. Mathewson](https://github.com/kylemath)
6	* [Kory W. Mathewson](https://github.com/korymath)	6	* [Kory W. Mathewson](https://github.com/korymath)
7		7
8	![DeepEEG Image](DeepEEGImage2.png)
9
10	DeepEEG is a Keras/Tensorflow deep learning library that processes EEG trials or raw files from the MNE toolbox as input and predicts binary trial category as output (could scale to multiclass?).	8	DeepEEG is a Keras/Tensorflow deep learning library that processes EEG trials or raw files from the MNE toolbox as input and predicts binary trial category as output (could scale to multiclass?).
11		9
12	CAN 2019 Poster presentation on DeepEEG - https://docs.google.com/presentation/d/1hO9wKwBVvfXDtUCz7kVRc0A6BsSwX-oVBsDMgrFwLlg/edit?usp=sharing	10	CAN 2019 Poster presentation on DeepEEG - https://docs.google.com/presentation/d/1hO9wKwBVvfXDtUCz7kVRc0A6BsSwX-oVBsDMgrFwLlg/edit?usp=sharing
13		11
14	## Collab notebooks for cloud compution	12	## Collab notebooks for cloud compution
15		13
16	Colab Notebook Example with simulated data:	14	Colab Notebook Example with simulated data:
17	https://colab.research.google.com/github/kylemath/DeepEEG/blob/master/notebooks/DeepEEG_Sim.ipynb	15	https://colab.research.google.com/github/kylemath/DeepEEG/blob/master/notebooks/DeepEEG_Sim.ipynb
18		16
19	Colab Notebook Example with data from Brain Vision Recorder in google drive:	17	Colab Notebook Example with data from Brain Vision Recorder in google drive:
20	https://colab.research.google.com/github/kylemath/DeepEEG/blob/master/notebooks/Deep_EEG_BV.ipynb	18	https://colab.research.google.com/github/kylemath/DeepEEG/blob/master/notebooks/Deep_EEG_BV.ipynb
21		19
22	Colab Notebook Example with muse data from [NeurotechX](https://github.com/neurotechx) eeg-notebooks:	20	Colab Notebook Example with muse data from [NeurotechX](https://github.com/neurotechx) eeg-notebooks:
23	https://colab.research.google.com/github/kylemath/DeepEEG/blob/master/notebooks/Deep_EEG_Muse.ipynb	21	https://colab.research.google.com/github/kylemath/DeepEEG/blob/master/notebooks/Deep_EEG_Muse.ipynb
24		22
25	## Getting Started Locally:	23	## Getting Started Locally:
26		24
27	DeepEEG is tested on macOS 10.14 with Python3.	25	DeepEEG is tested on macOS 10.14 with Python3.
28	Prepare your environment the first time:	26	Prepare your environment the first time:
29		27
30	```sh	28	```sh
31	# using virtualenv	29	# using virtualenv
32	python3 -m venv deepeeg	30	python3 -m venv deepeeg
33	source deepeeg/bin/activate	31	source deepeeg/bin/activate
34	# using conda	32	# using conda
35	#conda create -n deepeeg python=3	33	#conda create -n deepeeg python=3
36	#source activate deepeeg	34	#source activate deepeeg
37		35
38	```	36	```
39		37
40	```sh	38	```sh
41	git clone https://github.com/kylemath/DeepEEG/	39	git clone https://github.com/kylemath/DeepEEG/
42	cd DeepEEG	40	cd DeepEEG
43	./install.sh	41	./install.sh
44	git clone https://github.com/kylemath/eeg-notebooks_v0.1	42	git clone https://github.com/kylemath/eeg-notebooks_v0.1
45		43
46	```	44	```
47		45
48	You are now ready to run DeepEEG.	46	You are now ready to run DeepEEG.
49		47
50	For example, type ```python``` and use the following:	48	For example, type ```python``` and use the following:
51	This loads in some example data from eeg-notebooks	49	This loads in some example data from eeg-notebooks
52		50
53	```python	51	```python
54	from utils import *	52	from utils import *
55	data_dir = 'visual/cueing'	53	data_dir = 'visual/cueing'
56	subs = [101,102]	54	subs = [101,102]
57	nsesh = 2	55	nsesh = 2
58	event_id = {'LeftCue': 1,'RightCue': 2}	56	event_id = {'LeftCue': 1,'RightCue': 2}
59	```	57	```
60	Load muse data, preprocess into trials,prepare for model, create model, and train and test model	58	Load muse data, preprocess into trials,prepare for model, create model, and train and test model
61		59
62	```python	60	```python
63	#Load Data	61	#Load Data
64	raw = LoadMuseData(subs,nsesh,data_dir)	62	raw = LoadMuseData(subs,nsesh,data_dir)
65	```	63	```
66		64
67	```python	65	```python
68	#Pre-Process EEG Data	66	#Pre-Process EEG Data
69	epochs = PreProcess(raw,event_id)	67	epochs = PreProcess(raw,event_id)
70	```	68	```
71		69
72	```python	70	```python
73	#Engineer Features for Model	71	#Engineer Features for Model
74	feats = FeatureEngineer(epochs)	72	feats = FeatureEngineer(epochs)
75	```	73	```
76		74
77	```python	75	```python
78	#Create Model	76	#Create Model
79	model,_ = CreateModel(feats)	77	model,_ = CreateModel(feats)
80	```	78	```
81		79
82	```python	80	```python
83	#Train with validation, then Test	81	#Train with validation, then Test
84	TrainTestVal(model,feats)	82	TrainTestVal(model,feats)
85	```	83	```
86		84
87	## Tests	85	## Tests
88		86
89	You can run the unittests with the following command:	87	You can run the unittests with the following command:
90	```	88	```
91	python -m unittest tests	89	python -m unittest tests
92	```	90	```
93		91
94	## Strategy	92	## Strategy
95	* Load in Brain Products or Interaxon Muse files with mne as mne.raw,	93	* Load in Brain Products or Interaxon Muse files with mne as mne.raw,
96	* PreProcess(mne.raw) - normal ERP preprocessing to get trials by time by electrode mne.epochs	94	* PreProcess(mne.raw) - normal ERP preprocessing to get trials by time by electrode mne.epochs
97	* FeatureEngineer(mne.epochs) - Either time domain or frequency domain feature extraction in DeepEEG.Feats class	95	* FeatureEngineer(mne.epochs) - Either time domain or frequency domain feature extraction in DeepEEG.Feats class
98	* CreateModel(DeepEEG.Feats) - Customizes DeepEEG.Model for input data, pick from NN, CNN, LSTM, or AutoEncoders, splits data	96	* CreateModel(DeepEEG.Feats) - Customizes DeepEEG.Model for input data, pick from NN, CNN, LSTM, or AutoEncoders, splits data
99	* TrainTestVal(DeepEEG.Feats,DeepEEG.Model) - Train the model, validate it during training, and test it once complete, Plot loss during learning and at test	97	* TrainTestVal(DeepEEG.Feats,DeepEEG.Model) - Train the model, validate it during training, and test it once complete, Plot loss during learning and at test
100		98
101	## Dataset example	99	## Dataset example
102	* Interaxon Muse - eeg-notebooks - https://github.com/kylemath/eeg-notebooks	100	* Interaxon Muse - eeg-notebooks - https://github.com/kylemath/eeg-notebooks
103	* Brain Recorder Data	101	* Brain Recorder Data
104		102
105	## API	103	## API
106	* Input the data directory and subject numbers of any eeg-notebook experiment (https://github.com/kylemath/eeg-notebooks)	104	* Input the data directory and subject numbers of any eeg-notebook experiment (https://github.com/kylemath/eeg-notebooks)
107	* Load in .vhdr brain products files by filename with mne io features	105	* Load in .vhdr brain products files by filename with mne io features
108	* FeatureEngineer can load any mne Epoch object too - https://martinos.org/mne/stable/generated/mne.Epochs.html	106	* FeatureEngineer can load any mne Epoch object too - https://martinos.org/mne/stable/generated/mne.Epochs.html
109		107
110	## Preprocessing	108	## Preprocessing
111	* To be moved to another repo eventually	109	* To be moved to another repo eventually
112	* Bandpass filter	110	* Bandpass filter
113	* Regression Eye movement correction (if eye channels)	111	* Regression Eye movement correction (if eye channels)
114	- EOG Regression example: https://cbrnr.github.io/2017/10/20/removing-eog-regression/	112	- EOG Regression example: https://cbrnr.github.io/2017/10/20/removing-eog-regression/
115	- Original emcp paper: https://apps.dtic.mil/dtic/tr/fulltext/u2/a125699.pdf	113	- Original emcp paper: https://apps.dtic.mil/dtic/tr/fulltext/u2/a125699.pdf
116	- Generalized emcp paper: http://www.kylemathewson.com/wp-content/uploads/2010/03/MillerGrattonYee-1988-GeneralizeOcularRemoval.pdf	114	- Generalized emcp paper: http://www.kylemathewson.com/wp-content/uploads/2010/03/MillerGrattonYee-1988-GeneralizeOcularRemoval.pdf
117	- 1988 Fortran, Gehring C code: http://gehringlab.org/emcp2001.zip	115	- 1988 Fortran, Gehring C code: http://gehringlab.org/emcp2001.zip
118	- Matlab implementation: https://github.com/kylemath/MathewsonMatlabTools/blob/master/EEG_analysis/gratton_emcp.m	116	- Matlab implementation: https://github.com/kylemath/MathewsonMatlabTools/blob/master/EEG_analysis/gratton_emcp.m
119	* Epoch segmentation (time limits, baseline correction)	117	* Epoch segmentation (time limits, baseline correction)
120	* Artifact rejection	118	* Artifact rejection
121		119
122	## LearningModels	120	## LearningModels
123	* First try basic Neural Network (NN)	121	* First try basic Neural Network (NN)
124	* Then try Convolution Neural Net (CNN)	122	* Then try Convolution Neural Net (CNN)
125	* New is a 3D convolutional NN (CNN3D) in the frequency domain	123	* New is a 3D convolutional NN (CNN3D) in the frequency domain
126	* Then try Long-Short Term Memory Recurrant Neural Net (LSTM)	124	* Then try Long-Short Term Memory Recurrant Neural Net (LSTM)
127	* Can also try using (AUTO) or (AUTODeep) to clean eeg data, or create features for other models	125	* Can also try using (AUTO) or (AUTODeep) to clean eeg data, or create features for other models
128		126
129	## DataModels	127	## DataModels
130	* Try subject specific models	128	* Try subject specific models
131	* Then pool data over all subjects	129	* Then pool data over all subjects
132	* Then try multilevel models (in the works)	130	* Then try multilevel models (in the works)
133		131
134	## Benchmarks	132	## Benchmarks
135	* Goal build models that can be integrated with https://github.com/NeuroTechX/moabb/	133	* Goal build models that can be integrated with https://github.com/NeuroTechX/moabb/
136		134
137	## Code References	135	## Code References
138	* https://github.com/kylemath/eeg-notebooks	136	* https://github.com/kylemath/eeg-notebooks
139	* https://github.com/mne-tools/mne-python	137	* https://github.com/mne-tools/mne-python
140	* https://github.com/keras-team/keras/blob/master/examples/imdb_cnn_lstm.py	138	* https://github.com/keras-team/keras/blob/master/examples/imdb_cnn_lstm.py
141	* https://github.com/ml4a/ml4a-guides/blob/master/notebooks/keras_classification.ipynb	139	* https://github.com/ml4a/ml4a-guides/blob/master/notebooks/keras_classification.ipynb
142	* https://github.com/tevisgehr/EEG-Classification	140	* https://github.com/tevisgehr/EEG-Classification
143		141
144	## Resources	142	## Resources
145	* https://arxiv.org/pdf/1901.05498.pdf	143	* https://arxiv.org/pdf/1901.05498.pdf
146	* http://proceedings.mlr.press/v56/Thodoroff16.pdf	144	* http://proceedings.mlr.press/v56/Thodoroff16.pdf
147	* https://arxiv.org/abs/1511.06448	145	* https://arxiv.org/abs/1511.06448
148	* https://github.com/ml4a	146	* https://github.com/ml4a
149	* http://oxfordre.com/neuroscience/view/10.1093/acrefore/9780190264086.001.0001/acrefore-9780190264086-e-46	147	* http://oxfordre.com/neuroscience/view/10.1093/acrefore/9780190264086.001.0001/acrefore-9780190264086-e-46
150	* https://arxiv.org/pdf/1811.10111.pdf	148	* https://arxiv.org/pdf/1811.10111.pdf