Patterns

Patterns

Creation

Patterns hold segmented EEG data, either raw traces or time-frequency decompositions. A pattern can be created using create_voltage_pattern or create_power_pattern. These functions support some preprocessing options, including frequency-domain filtering (e.g. notch filtering to remove 60 Hz noise). Alternatively, an EEGLAB or !FieldTrip segmented data structure could be converted to pattern format according to the pattern specification listed below.

Operations

A number of functions transform existing patterns. Type help patterns/operations to see a list of the functions available and a brief description of what they do.

All pattern operation functions support a number of save options, including renaming or overwriting existing patterns. They can also be used to return patterns to the workspace rather than saving them to disk. If no save options are specified, patterns will be returned to the workspace. When storing patterns in the workspace, take care when processing multiple subjects and/or large patterns; if you're getting out of memory errors, specify either the save_as option to save each subject's pattern to a new file or set overwrite to true to overwrite the input pattern.

Common Tasks

bin_pattern can be used to accomplish averaging across events to calculate event-related potentials (ERPs) and can also average across any other dimension. grand_average can be used to average across subjects. filter_pattern is used to return a subset of a pattern, for example a set of events matching a given condition or a specific set of channels.

There are a number of functions for combining patterns by concatenating them. cat_pattern is a generic function that can be used on any vector of pattern objects. cat_subj_patterns can concatenate multiple patterns within a subject. cat_all_subj_patterns concatenates a pattern over multiple subjects.

Batch Processing

As with all toolbox operations, pattern operations can be run on all subjects in batch. Use apply_to_pat to do this. For example:

exp.subj = apply_to_pat(exp.subj, 'my_pat_name', @bin_pattern, {'eventbins', 'overall'});

Will run bin_pattern on each subject, with the pattern as the first input, and 'eventbins' and 'overall' as additional inputs. This is equivalent to running:

for i = 1:length(exp.subj)
  pat = getobj(exp.subj(i), 'pat', 'my_pat_name');
  pat = bin_pattern(pat, 'eventbins', 'overall');
  exp.subj(i) = setobj(exp.subj(i), 'pat', pat);
end

However, using apply_to_pat, rather than writing your own for loop, allows you to use the Mathworks distributed computing toolbox to process each subject in parallel. Set the dist flag in to 1 (a separate task is submitted for each subject) or 2 (uses a loop; must open a matlabpool first) to run subjects in parallel.

Writing Your Own Operations

All toolbox operations function call to handle saving out pattern matrices and associated dimensions information. Your function should contain a subfunction that is input to as a function handle. will run the function and handle the saving/renaming of the output pattern. See for an example of how to write an operation function.

Specification

Here is the specification for patterns. Also see the downloads page for an example of a pattern that meets the specifications.

Patterns consist of two parts: a pat object, which contains metadata about the pattern, including a name that identifies the pattern, and information about dimensions; and a pattern matrix, which contains the actual data. The pat object includes a reference to the pattern, which is normally stored on the hard drive, but may also be stored in a subfield called mat.

Field	Type	Description
name	string	unique identifier for the pattern
file	string	path to a MAT-file containing the pattern matrix
source	string	identifier of the subject these data were collected from
params	struct	(optional) structure containing the options used to create the pattern
dim	struct	structure containing information about each dimension of the pattern (see below)
modified	logical	(optional) indicates whether the pattern has been modified since it was last saved
mat	numeric	(optional) when the pattern is stored in the workspace, it is placed here

Dimensions

Dimensions of the pattern matrix must have the following order: events X channels X time X frequency. Any of these dimensions may be singleton, but they must be in the standard order. Metadata about each dimension is stored in pat.dim. Dimensions have a similar format to pat objects; they include a structure which contains basic information, and a larger structure on the hard drive which contains detailed information. The dimensions are stored in pat.dim.ev, pat.dim.chan, pat.dim.time, and pat.dim.freq. The standard fields for any dimension are:

Field	Type	Description
type	string	'ev', 'chan', 'time', or 'freq'
file	string	path to a MAT-file containing the full dimension structure
len	numeric	integer giving the length of the dimension
modified	logical	(optional) indicates whether the dimension has been modified since it was last saved
mat	numeric	(optional) when the dimension structure is stored in the workspace, it is placed here

Events

The events dimension contains information about what was happening in the experiment at a given time. It has no required fields, but can have any number of fields containing information about the experiment, such as trial, stimulus, etc.

Channels

This dimension generally contains information about different electrodes. There are two required fields:

Field	Type	Description
number	numeric	unique integer identifying the channel
label	string	unique string identifier for the channel

Time

This dimension describes times in milliseconds relative to the start of a given event. There are three required fields:

Field	Type	Description
range	numeric	1 X 2 array giving the start and end times of this time bin (start and end may be the same)
avg	numeric	scalar giving the center of this time bin
label	string	label for this time bin

Frequency

This dimension is used in patterns containing power values, but not for voltage patterns (for voltage patterns, init_freq() can be used to generate an empty frequency dimension). The required fields are the same as for time, but the values represent frequencies in Hz.