Introduction to MNE-Python

Introduction

In this workshop, we will analyze EEG data in Python. We will use MNE-Python, which is currently the largest and most popular Python package for EEG/MEG analysis. Using real-world EEG data, we will investigate both induced and evoked activity. Whereas time–frequency analysis is used to quantify induced activity in specific frequency bands, we quantify evoked activity by simply averaging over epochs of EEG data. We will learn how to perform both types of analyses with MNE-Python in this workshop. Some experience with Python is useful, but not required to follow along in this workshop, because we will start from scratch and learn how to set up a working Python environment for EEG analysis.

Overview

We will cover the following topics in this workshop:

• Installing and configuring MNE-Python
• Using a suitable development environment
• Importing data
• Metadata
• Events and annotations
• Using built-in data sets
• Renaming channels, re-referencing, assigning montages
• Filtering, interpolating channels
• Visualizing continuous data
• Manual artifact selection
• Removing ocular artifacts with ICA

Community resources

• Documentation
• Community forum
• Repository

Installation

There are dozens of ways to install Python and MNE-Python on your computer. If you are just beginning your journey with MNE-Python, we recommend the standalone installers, which contain everything you need to get started with analyzing EEG data. In particular, you will get

• a full-fledged Python environment with MNE-Python including all required and optional dependencies,
• Spyder, an integrated development environment (IDE) tailored towards scientific workflows,
• and some useful shortcuts (such as a command prompt with an activated MNE-Python environment).

Figure 1: MNE apps installed by the standalone installer.

Note

If you are a more experienced Pythonista and would like to customize your MNE-Python installation, we also support manual installations with pip and conda.

Although the standalone installers contain hundreds of useful packages, sometimes you still might want to use a package that is not available out of the box. For example, to import data from XDF files (a popular file format for biosignal data produced by devices compatible with LSL), we need to use the pyxdf package, which is currently not included in the standalone installers. To install additional packages, start the MNE command prompt and enter the following command:

mamba install pyxdf

That’s it – now you can use the pyxdf package in all your projects!

Spyder

Figure 2: Main window of Spyder, the scientific Python development environment.

Prerequisites

As with every third-party Python module, you need to import it before you can start using it. Typically, we import the entire base module like this:

import mne

However, sometimes it is convenient to only import specific submodules and/or functions, for example:

from mne.io import read_raw

Tip

If you want to check your current MNE-Python environment, run the following command:

mne.sys_info()

The output is also very useful for developers, so make sure to include it if you report an issue with MNE-Python.

Continuous, epoched, and evoked data

Let’s introduce some MNE-specific terminology before we start working on a first example (check out the glossary for more definitions). There are three different types that represent EEG data:

• Raw objects contain continuous data (official tutorial)
• Epochs objects contain epoched (discontinuous, segmented) data (official tutorial)
• Evoked objects contain evoked data (averaged epochs) (official tutorial)

Another core data type is Info (more info – pun intended – is available here), which contains metadata such as sampling frequency and channel properties. All three previously mentioned data types (Raw, Epochs, and Evoked) have associated Info attributes (available as info, for example raw.info, epochs.info, and evoked.info for objects called raw, epochs, and evoked, respectively).

Importing data

In the following example, we will use the EEG motor movement/imagery data set available on PhysioNet. Let’s download one particular file, namely S001R04.edf. In the next section, we’ll see that MNE-Python has a built-in importer for this data set, which makes it much easier to download this file (or any file which is part of this data set).

Important

All examples assume that external data files (such as S001R04.edf) are located in the working directory.

We can now import the data with the previously imported read_raw() function:

raw = read_raw("S001R04.edf")

Note

Most MNE commands ouput informative messages, which can be quite useful during interactive data exploration. However, if you would like to silence these messages, you can do this with the following command:

mne.set_log_level("ERROR")

Since the output can be rather verbose, we’ll only show messages when they are important for a particular example throughout this document.

https://cbrnr.github.io/blog/importing-eeg-data/

Using built-in data sets

The mne.datasets module provides convenient access to many public data sets (see this overview for a complete list of available data sets). Depending on the data set, use either data_path() or load_data() to download the entire data set or only a specific subset, respectively.

For example, let’s take a look at the EEG motor movement/imagery we’ve manually downloaded and imported previously. MNE-Python includes a dedicated importer in mne.datasets.eegbci. We can use it to download and import three data files for S001, namely runs 4, 8, and 12 (which contain data from a left versus right hand motor imagery task):

files = mne.datasets.eegbci.load_data(subject=1, runs=[4, 8, 12])

MNE-Python will download and store the requested files in a suitable location and return a list of paths. We can then use this list to actually import the data, for example with a list comprehension:

raws = [read_raw(file) for file in files]

Now raws is a list containing three Raw objects corresponding to the data from the three files. We can concatenate these objects into a single Raw instance, which will make subsequent analyses possible:

raw = mne.concatenate_raws(raws)

Visualizing continuous and epoched EEG data

• The MNE-Python signal browser

https://cbrnr.github.io/blog/visualizing-eeg-data/

Removing ocular artifacts with ICA

https://cbrnr.github.io/blog/removing-eog-ica/

Real-world examples

• Importing XDF
• Events and annotations
• Filtering (lowpass, highpass, bandpass, notch)
• Reference (and re-referencing)
• Interpolating bad channels
• Epoching
• Time–frequency analysis (ERD/ERS)
• Event-related potential (ERP) analysis

https://github.com/cbrnr/bci-event-2021