These are notes for the Computational Memory Lab's Workshop on Cognitive Electrophysiology. They are also a good introduction to performing EEG analyses, and you can use them as a resource for learning these tools and methods.
Lectures covering the concepts underpinning the analyses covered in this workshop are available from the Electrophysiology Workshop 2020 page on the Computational Memory Lab wiki.
Our goal is to familiarize you with basic Python tools for data science and the libraries developed by our lab and others to facilitate EEG analyses. In order to understand the psychology / neuroscience at play in these analyses, you'll need to watch the associated lectures from the 2020 workshop. To that end, the course outline is as follows:
- README - This document, describing course structure and inital setup
- Notebook 1 - Intro to Python basics, Jupyter Notebooks, Numpy, and Pandas
- Lecture 1
- Lecture 2
- Notebook 2 - Data loading, experimental events, PTSA, and MNE
- Lecture 3
- Notebook 3 - Working with EEG
- Lecture 4
- Notebook 4 - Signal processing and spectral analysis
- Lecture 5
- Notebook 5 - Machine Learning I, sklearn, regression/classification
- Lecture 6
- Notebook 6 - Machine Learning II, cross-validation, feature selection, other classifiers
By the end of this sequence, you should be able to carry out EEG/iEEG/ECoG analyses, like computing spectral power and phase, and compute statistics or apply machine learning models to those data.
For Rhino users only:
- Notebook 7 - Parallel computing
- Notebook 8 - CMLReaders Usage
- Notebook 9 - Biomarkers of Episodic Memory
These notebooks prepare you for doing in-depth multi-subject analyses with electrophysiological data. Anyone planning to work extensively with CML data should complete them. Notebook 9 is an advanced assignment that will take much longer than any of the others in this workshop - consider it a "final project" of sorts.
Optional appendices:
- Lecture 7
- Notebook A1 - Single Unit Analysis, Spatial Memory
- Lecture 8
- Notebook A2 - Connectivity
These notebooks cover advanced topics in computational neuroscience that go beyond the scope of what a beginner might need to know. If you are interested in these topics, or just want to gain some familiarity with them, we encourage you watch the associated lectures and go through the notebooks.
This tutorial can be made use of on your own system after obtaining the CMLExamples data set (contact kahana-sysadmin@sas.upenn.edu to receive access to these files) or directly on the Rhino computing cluster if you have access to this. Instructions are provided below to set up either your local machine or an environment on Rhino for affiliates of the Computational Memory Lab.
Though this workshop assumes a basic knowledge of Python and command line tools, we have linked recommended resources in Notebook 1 for getting started with python and common data analysis tools. Though this material isn't strictly part of the Workshop, we recommend reviewing it before proceeding to the materials included here unless you are confident in your experience with numpy, pandas, scipy, and basic python syntax. If those words don't mean anything to you (or you want to brush up), please read through these resources!
To start working with any materials contained or linked here, you'll need to set up tools for writing and running Python code. If you are affiliated with the Computational Memory Lab and have access to Rhino, our computing cluster, you can skip down to the Getting started on Rhino section. Otherwise, you can follow the instructions below to set up python on your own computer.
All subsequent stages of these instructions will assume familiarity with and access to a *NIX command line. If this is unfamiliar to you, please use the resources below to get yourself oriented.
If you are using Rhino, an apple computer running OSX, or a Linux computer, you will already have access to a command line. On Windows, we recommend using Cygwin https://www.cygwin.com/ or the Ubuntu subsystem https://docs.microsoft.com/en-us/windows/wsl/install-win10.
General Introduction: https://ubuntu.com/tutorials/command-line-for-beginners#1-overview
For this workshop, we will use conda to manage the various libraries needed to perform analyses using Python. Conda is a tool that allows Python libraries to be installed into 'environments.' This is a folder that lets you manage the needs of different projects independently; the reasons for this may not be apparent immediately, but using some sort of virtual environment system of some sort is a standard practice and isolates issues when they come up. Conda is available from the Anaconda project home. We recommend installing miniconda, though you can read the installation instructions and decide for yourself which distribution is best for you.
Once you have conda set up, we need to additionally set up Jupyter notebooks. This is a tool that makes some types of python development easier since it allows you to run small pieces of code and immediately see the output alongside the code. Installation instructions and general information are available from the Jupyter project home.
If you have been provided with an account on the Rhino computing cluster, these instructions will help you access and setup your account to the point where you can follow these workshop notes and perform analyses. If you are using another system, skip ahead to Setting up JupyterLab.
1. You can log in to Rhino2 in a terminal window by using any ssh client to ssh into rhino as follows, replacing the "username" with your username:
ssh username@rhino2.psych.upenn.edu
and then typing your temporary password when prompted. Once successfully connected, type:
passwd
to change your password to something only you know. Please do this as soon as you have the time!
2. Once you have your password set up, check to be sure you can log in to JupyterLab, where you'll be doing most of the workshop work. If you are connected to the internet on UPenn's campus, you only need to go to https://rhino2.psych.upenn.edu:8200 to access JupyterLab. If you are connecting remotely, follow the rest of this step. In a terminal where ssh is accessible, replace the "username" with your username, and open an ssh tunnel by typing:
ssh -L8000:rhino2.psych.upenn.edu:8200 username@rhino2.psych.upenn.edu
followed by entering your rhino password. In your web browser, navigate to:
and you should see the JupyterLab interface pop up! Note that the "s" on https is critical for this to work. Your browser might warn about this being an insecure connection or invalid certificate, given that 127.0.0.1 (direct to the ssh tunnel on your own computer) is not rhino. Override this warning and connect anyway, because we are using ssh to provide better security here. If the connection still fails, go back and make sure that your ssh tunnel was correctly created.
Good news! Working on rhino gives you access to a computing environment that already has the right software installed to do the whole workshop!
In JupyterLab, open any notebook and then go to Kernel -> Change Kernel... and then select "workshop" from the dropdown! Make sure you use this kernel whenever you're opening a notebook.
Once you've installed the necessary tools, you'll need to create a new virtual environment. To do so, open a terminal and run:
conda create -y -n <environmentname> python=3.7
NOTE: 'environmentname' is a placeholder, please replace it with a more descriptive name!
For commands to alter or refer to this environment, you'll need to activate it. This step will be necessary any time you open a new terminal or restart your session, but will be remembered for subsequent commands.
conda activate <environmentname>
NOTE: on older versions of conda, you may instead need to use source activate environmentname
Next, you'll need to install a suite of tools for EEG analysis. First, install MNE by typing the following (be sure you're in the Anaconda "environment" you just created in Step 1, by typing "source activate environmentname"). Note that this may take a while, because MNE has a lot of dependencies:
conda install -c conda-forge mne
If this does not work at first, try pip install mne
Next, install PTSA, which is a set of EEG tools developed by former lab members:
conda install "traitlets<5"
conda install -c pennmem ptsa=2.0.8
Install a few extra packages in use for these notes:
conda install scikit-learn statsmodels seaborn
Finally, you'll need to link JupyterLab with your specific Python installation. While still logged in and in your Anaconda "environment", type:
conda install ipykernel
and once that's done:
python -m ipykernel install --user --name environmentname --display-name "environmentname"
You should be all set! Next time you log in to your JupyterLab account, you should see an option to launch a new notebook with "environmentname" as your Python environment. If you've been logged in to JupyterLab this whole time, you may need to log out and log back in again to see this change take effect.
To access the data for this workshop outside of Rhino, contact kahana-sysadmin@sas.upenn.edu
In a terminal in the location where you would like to download the workshop materials, enter the following:
git clone 'https://github.com/pennmem/CMLWorkshop.git'
If git is not installed, you can find instructions [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
The workshop will be downloaded to a folder named CMLWorkshop in the same location where you ran the git clone command.
In your ssh terminal to rhino, enter the following commands:
source activate environmentname
conda install -c pennmem cmlreaders=0.9
This package is being phased out, but is still needed for loading a large portion of data stored on Rhino. Any analyses using CMLLoad can bbe done nearly equivalently using CMLReaders, though CMLReaders has access to a much larger set of data on Rhino.
In JupyterLab (please see instructions above for how to set up and launch JupyterLab), navigate to the lecture notes you downloaded using the file browser section on the left, open the lecture notes, and proceed through them in order. If appropriate for your background and situation, jump ahead to the relevant sections to see syntax examples for common analyses and for using the common tools used by the Computational Memory Lab.