--- a
+++ b/README.md
@@ -0,0 +1,150 @@
+## 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 Image](DeepEEGImage2.png)
+
+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