Scalable and reproducible M/EEG pipelines
meegpipe is a collection of MATLAB tools for building advanced processing pipelines for high density physiological recordings. It is especially suited for the processing of high-density EEG and MEG, but can also handle other modalities such as ECG, temperature, actigraphy, light exposure, etc.
If you are working at somerengrid (our lab's private computing grid), then all the pre-requisites are already there and you can go directly to the installation instructions.
EEGLAB is required mostly for input/output of data from/to various data formats, and for plotting. Please ensure that EEGLAB is in your MATLAB search path.
The engine responsible for generating data processing reports in HTML relies on several Python packages and on Inkscape. meegpipe will be fully functional without these dependencies, but the processing reports will be generated in a plain text format (using Remark syntax). Inspecting plain text reports with embedded images is very inconvenient so please consider installing these highly recommended dependencies.
You are encouraged to install a few additional components that can enhance meegpipe's functionality in terms of high-throughput computing.
Copy and paste the following code in the MATLAB command window:
% installDir is your installation directory
installDir = [pwd filesep 'meegpipe'];
url = 'https://github.com/meegpipe/meegpipe/zipball/master';
unzip(url, installDir);
addpath(genpath('meegpipe'));
meegpipe.initialize;
% Initialize meegpipe every time that MATLAB starts
addpath(userpath);
fid = fopen(which('startup'), 'a');
fprintf(fid, [...
'%%Added by meegpipe (http://germangh.com/meegpipe)' ...
'\naddpath(genpath(''%s''));' ...
'\nmeegpipe.initialize;\n'], installDir);
fclose(fid);
Notice that the code above will install meegpipe in directory meegpipe
under your current working directory. Notice also that EEGLAB needs to be
part of your MATLAB search path for the meegpipe.initialize command to
succeed. This means that you either add EEGLAB permanently to your MATLAB
search path, or you add the following command to your startup.m file,
before the meegpipe.initialize command:
addpath(genpath('/path/to/your/eeglab/installation'));
meegpipe allows you to build processing pipelines by definining what you want to do with your data in terms of processing nodes. There are processing nodes for a variaty of tasks: importing from disk, filtering, bad channel rejection, removing artifacts, feature extraction, etc. You can also easily define your own nodes that will integrate seamlessly with the meegpipe framework.
For convenience, we bring package meegpipe to the current name space:
import meegpipe.*;
Generate a physioset object from a MATLAB matrix using a physioset_import node:
myImporter = physioset.import.matrix('SamplingRate', 250);
n0 = node.physioset_import.new('Importer', myImporter);
% Run it! import the data!
data = run(n0, randn(15, 10000));
Use a filter node to detrend the imported data using a 10th order polynomial:
n1 = node.filter.new('Filter', filter.polyfit('Order', 10));
run(n1, data);
Use a bad_channels node to reject bad channels:
n2 = node.bad_channels.new;
run(n2, data);
Apply a band pass filter between 0.1 and 70 Hz:
myFilter = @(sr) filter.bpfilt('Fp', [0.1 70]/(sr/2));
n3 = node.filter.new('Filter', myFilter);
run(n3, data);
Remove powerline noise using Blind Source Separation (BSS), i.e. using a bss node:
n4 = node.bss.pwl;
run(n4, data);
Reject ocular artifacts using BSS:
n5 = node.bss.eog;
run(n5, data);
Export to EEGLAB format using a physioset_export node:
myExporter = physioset.export.eeglab;
n6 = node.physioset_export.new('Exporter', myExporter);
run(n6, data);
For more information and a list of available processing nodes, see the documentation.
A pipeline is just a concatenation of nodes. With the exception of
physioset_import nodes, all other node classes always
take a physioset as input. And with the exception of
physioset_export nodes, all other node classes produce a
physioset object as output.
The five processing steps that we performed above when illustrating how nodes work could have been grouped into a pipeline:
import meegpipe.*;
import physioset.import.*;
myPipe = node.pipeline.new(...
'NodeList', {n0, n1, n2, n3, n4, n5, n6});
% Will produce an output file in EEGLAB format
run(myPipe, randn(15, 10000));
Every processing node (or pipeline) generates a comprehensive HTML report for every data file that is processed. Namely, if you ran the pipeline example above, you will find the corresponding HTML report under:
[input_file_name].meegpipe/[pipe_name]_[blahblah]/index.htm
NOTE: Neither Firefox nor Google Chrome are able to display local .svg files, when running under Windows 8. Whenever trying to do so, both browsers attempt to download the file and thus the file is not displayed. Read the document on known issues and limitations for ways to overcome this problem.
NOTE: The HTML reports will be generated only if you have installed all the recommended dependencies on your system.
See the practical tutorials for some typical use cases of meegpipe. A high-level description of the API components can be found in the documentation. The documentation is still work in progress.
For convenience, meegpipe ships together with code from third-parties. You can find a comprehensive list here.
Any code that is not part of any of the bundled third-party dependencies (see the list), is released under the Creative Commons Attribution-NonCommercial-ShareAlike licence.