Skip to main content

MATLAB

MATLAB is a powerful numerical computing language and environment that is widely used in a wide variety of academic, research, and industry applications.

A few Matlab toolboxes have been created specifically for working with EEG and BCI. EEGLAB, BCILAB, ERPLAB, and FieldTrip are a few toolboxes that have helped OpenBCI users work in MATLAB.

This tutorial will walk through setting up your Matlab environment for use with OpenBCI hardware, as well as some basic uses and functionalities that Matlab offers for working with brain-computer interfaces.

Installation#

Go to the MathWorks website for MATLAB installation instructions.

Please note that MATLAB is commercial software. Licenses must either be purchased or acquired through academic or professional institutions.

Several useful MATLAB toolkits (EEGLAB, BCILAB, FieldTrip, etc) have been created for collecting and analyzing EEG data, so this tutorial will focus on using MATLAB through these toolkits.

Loading OpenBCI Data#

There are two main ways to get your OpenBCI data from the boards into MATLAB for analysis. The first is to import a CSV file from a recorded session, and the second is to use the Lab Streaming Layer (LSL) to stream the board data into MATLAB. We will go over both methods.

Method 1: Import CSV file from the OpenBCI GUI#

To get started, use your OpenBCI board (like the Cyton or Ganglion board) and the OpenBCI GUI to stream some data. Whenever you stream data to the GUI, it's also automatically saved in .csv format on your computer. GUI data and recordings are saved to /Documents/OpenBCI_GUI/Settings/ on all operating systems.

The OpenBCI Processing GUI saves data in text (txt) or comma separated value (csv) files. Import the CSV file into MATLAB as a matrix by using the "Import Data" wizard:

Select a saved OpenBCI data file. Once the data import screen is open, select the "Numeric Matrix" import option. Deselect all of the header rows. Also deselect the final column, the timestamp values, since the import wizard can only parse numeric values. Feel free to give your matrix a conveneint name, like "eeg_data":

Click "Import Selection". Your matrix should now appear as an object in your workspace! Keep reading to learn more about processing your data with MATLAB toolboxes.

Method 2: Stream OpenBCI data via LSL#

Stream the OpenBCI Data from the OpenBCI GUI#

You can also stream live OpenBCI data into MATLAB using the Lab Streaming Layer either from the OpenBCI GUI or from Python. Here, we will go over how to import data from the OpenBCI GUI.

Open the OpenBCI GUI and "Start System" with your setup as you would do. On the widget dropdown menu select "Networking". At the right upper corner of the Networking widget there is another dropdown menu, select LSL.

Now you can select the OpenBCI Data you want to send, the Name of the LSL stream, the data advertised by the LSL and the number of channels you will be sending. Once you select your parameters make sure to turn on your LSL stream at the bottom of the widget. Then click start and you are ready to go.

Import the LSL stream into MATLAB#

There are two ways to import an LSL using the liblsl-Matlab library to stream into MATLAB or using the BCILAB toolbox.

liblsl-Matlab#

Follow the instalation instructions on the liblsb-Matlab GitHub Repo. Once you successfully added the correct directories and files you can use the following script to stream the OpenBCI data from your LSL stream.


%% instantiate the librarydisp('Loading the library...');lib = lsl_loadlib();
% resolve a stream...disp('Resolving an EEG stream...');result = {};while isempty(result)    result = lsl_resolve_byprop(lib,'type','EEG'); end
% create a new inletdisp('Opening an inlet...');inlet = lsl_inlet(result{1});
disp('Now receiving data...');while true    % get data from the inlet    [vec,ts] = inlet.pull_sample();    % and display it    fprintf('%.2f\t',vec);    fprintf('%.5f\n',ts);end
BCILAB#

From the BCILAB wiki: "BCILAB is a MATLAB toolbox and EEGLAB plugin for the design, prototyping, testing, experimentation with, and evaluation of Brain-Computer Interfaces (BCIs), and other systems in the same computational framework."

BCILAB provides a GUI from which you can control the plugin, but batch scripting can be used for those well-versed in MATLAB programming.

Installation#

To install BCILAB, download the development version of BCILAB and extract it to any directory that is not your EEGLAB folder. Note: I found that the non-developer version (found here) had bugs that were fixed by using the BCILAB-devel version instead.

Open up MATLAB, and set your current MATLAB directory to the unzipped BCILAB file:


cd your/path/to/bcilab;

Once you're in the file, just type the command:


bcilab
Import LSL#

To start running BCILAB. After some console output, you should see the text "Welcome to the BCILAB toolbox!" and then a new GUI with the BCILAB menu should appear.

Once a stream has been started on your computer, open BCILAB within MATLAB (>> cd your/path/to/bcilab; bcilab) and from the menu, select Online Analysis > Read input from... > Lab streaming layer...

Analyzing OpenBCI data#

There are many ways in which you can use MATLAB to analyze the data from the OpenBCI board, we will go over a few common ones to get started.

EEGLAB#

From the EEGLAB wiki: "EEGLAB is an interactive Matlab toolbox for processing continuous and event-related EEG, MEG and other electrophysiological data using independent component analysis (ICA), time/frequency analysis, and other methods including artifact rejection."

Setup#

Go to the EEGLAB downloads page and follow the instructions for your operating system.

Download the zip file of the most current version of EEGLAB and extract it into a directory on your system. Then, make this toolbox accessible from Matlab by adding a path to this directory (the steps to do this vary by OS - see the "EEGLAB downloads page" link above).

To check if EEGLAB is correctly set up, go to the Matlab prompt and type:

>> eeglab

If the toolkit is not yet correctly implemented, the console should output: "Undefined function or variable 'eeglab'."

If it is set up correctly, a pop-up window should appear with the EEGLAB GUI.

Preparing OpenBCI Datasets for EEGLAB Use#

OpenBCI saves data in the opposite orientation from what EEGLAB needs. So, after importing your OpenBCI data to MATLAB as described above, perform a simple matrix transposition:


eeg_data = eeg_data'

Your data matrix is now ready to use with EEGLAB.

Using EEGLAB#

If EEGLAB isn't already running, enter "eeglab" into the Matlab command line to start the program. Import your matrix into EEGLAB using the EEGLAB GUI: File -> Import Data -> Using EEGLAB functions and plugins -> From ASCII/float file or Matlab array

In the pop-up window that appears, enter information about the data set. Select "Matlab variable", and enter the name of the variable where your matrix is stored. Enter the Data Sampling rate (it should be commented in at the top of the txt file - usually 250 Hz by default in the OpenBCI GUI). The other fields can be left at default, and EEGLAB will automatically fill in the information from the data set.

Channel locations are useful for plotting EEG scalp maps in 2-D or 3-D format. OpenBCI uses the standard 10-20 format for the 8 and 16 channel models, which can be found within these sfp files: 8 channel and 16 channel. You can then import channel data by click "Browse" next to "Channel location file or info" and locating the OpenBCI sfp file you downloaded.

The data is now imported into EEGLAB and ready to use!

Plotting Data in EEGLAB#

To double check your data is imported correctly, and to get familiar with EEGLAB's interface, try plotting your data. Select Plot -> Channel data (scroll) from the EEGLAB pop-up window.

Your data should appear in a window like the image below:

Check out the links in the Further Reading section to learn more about processing data with EEGLAB!

Streaming into EEGLAB#

From what we can tell, EEGLAB seems to work primarily with datasets and recorded data.

ERPLAB#

From the ERPLAB homepage: "ERPLAB Toolbox is a free, open-source Matlab package for analyzing ERP data. It is tightly integrated with EEGLAB Toolbox, extending EEGLAB’s capabilities to provide robust, industrial-strength tools for ERP processing, visualization, and analysis. A graphical user interface makes it easy for beginners to learn, and Matlab scripting provides enormous power for intermediate and advanced users."

Setup#

Download and extract the latest ERPLAB release to the "plugins" folder of your EEGLAB directory (if you have an old release of EEGLAB, you will also have to enter the path to this directory in MATLAB by File > Set Path)

Next time your launch EEGLAB, the ERPLAB menu should appear in the EEGLAB GUI:

Analyzing EEG Data Sets#

To use ERPLAB for analyzing EEG datasets, import your data set as seen in the [Using EEGLAB Section](#Using EEGLAB). After the EEG data is imported into EEGLAB, you can then use ERPLAB functions to analyze your data. Read more on using ERPLAB on their website

FieldTrip#

From the FieldTrip homepage: "The toolbox offers advanced analysis methods of MEG, EEG, and invasive electrophysiological data, such as time-frequency analysis, source reconstruction using dipoles, distributed sources and beamformers and non-parametric statistical testing."

Setup#

Download the latest version of FieldTrip from the download page (you will have to provide an email address and descriptiption of research).

Add the FieldTrip directory to your MATLAB path and check out FieldTrip's getting started guide.

Further Reading#

EEGLAB Wiki

BCILAB Wiki

ERPLAB Homepage and ERPLAB Original Publication in Frontiers in Human Neuroscience.

FieldTrip Homepage