BatchProcessing

Introduction

Most functions that operate on individual "patterns," or EEG datasets, can be easily applied to multiple subjects using the batch processing functions. These functions can be used to process multiple subjects in parallel using a cluster or using multiple cores on a computer.

Basics

Each of the batch processing functions is designed to take in a set of subject structures and return a (possibly altered) set of subject structures. They take a function handle that determines what is done to each subject. For example, we'll demonstrate using a simple function that works on one subject to add a new field containing that subject's age. This example uses an anonymous function to quickly specify a function handle.

f = @(subj, age) setfield(subj, 'age', age);

You can run this function on an individual subject by passing in a subj structure:

% set up a sample experiment with a few subjects
subj = [];
subj = addobj(subj, init_subj('subj01'));
subj = addobj(subj, init_subj('subj02'));
subj = addobj(subj, init_subj('subj03'));
exp = init_exp('my_experiment', 'subj', subj);

% get one of the subjects
subj = getobj(exp, 'subj', 'subj01');
% run the function
subj = f(subj, 23);
% update the subject on the experiment structure
exp = setobj(exp, 'subj', subj);
getobj(exp, 'subj', 'subj01')

Note that the subject has now been updated to have an "age" field, as we specified. To run a function like this on all subjects, you can use apply_to_subj.m. This function takes in a vector of subjects (typically stored in exp.subj), and runs the supplied function on all subjects. In apply_to_subj, the steps run for each subject are essentially the same as above; each subj struct is taken from the larger vector, run through the function, then added back to the subject vector.

% run the function on every subject
exp.subj = apply_to_subj(exp.subj, f, {23});

% inspect the modified subjects
getobj(exp, 'subj', 'subj01')
getobj(exp, 'subj', 'subj02')
getobj(exp, 'subj', 'subj03')

Note that the "age" field has now been set for all subjects (our very simple function just sets all subjects to have the same value for "age"). The third input to apply_to_subj is a cell array, which contains inputs to the supplied function to place after subj. This way, f is called as f(subj, 23). Any number of inputs can be passed in this way by adding elements to the cell array. However, for a function to work with apply_to_subj, the first input must always be a subject struct.

Batch processing patterns

In principle, apply_to_subj can do any number of operations on a subject's data, including associated events structures and patterns. However, for convenience, there are other functions, apply_to_pat and apply_to_ev, which are specialized for batch processing patterns and events structures. Here, we focus on patterns; apply_to_ev works in a similar manner.

Just as apply_to_subj runs a function that takes a subject as the first input, and passes out a modified subject, apply_to_pat runs a function on a pattern and gets a modified pattern. The modified pattern is then updated on the subject structure, so the set of subjects that is output is updated with information about the new patterns. The function call is similar, but you also must specify the name of the pattern to be modified. For example:

exp.subj = apply_to_pat(exp.subj, 'my_pat', @bin_pattern, {'eventbins', 'condition', 'overwrite', true});

This will run bin_pattern on each subject's pattern called "my_pat". The cell array (the fourth input to apply_to_pat) indicates additional inputs to the bin_pattern function, which specify what events to average over (in this example, we assume that there is a field on the events structure that indicates the experimental condition; an average is calculated for each different condition). The "overwrite" option is set to true, indicating that the "my_pat" patterns should be overwritten on disk. Functions that modify patterns, like bin_pattern in this case, support a number of options for saving modified patterns. The help comments for each function list the relevant options. The "save_as" option allows you to indicate a new name to save the modified pattern under. For example, to modify each subject's pattern and save as a new pattern:

exp.subj = apply_to_pat(exp.subj, 'my_pat', @bin_pattern, {'eventbins', 'condition', 'save_as', 'my_new_pat'});