Building custom scripts

The intuitive and easy-to-use GUI is not the only way to utilize this software. For those researchers looking for flexibility and automation, MVPAlab implements several high-level functions to easily set up a custom decoding analysis. The complete analysis pipeline can be divided into five main steps and runs as follows:

% [1] - Initialize MVPAlab toolbox:
cfg = mvpalab_init();

% [2] - Run the configuration file:
run cfg_file.m

% [3] – Import data and extract feature vectors:
[cfg,data,fv] = mvpalab_import(cfg);

% [4] – Compute a multivariate analysis:
[result,cfg] = mvpalab_mvpa(cfg,fv);

% [5] – Plot the results:
run plot_file.m

1. Initialize MVPAlab toolbox:

cfg = mvpalab_init();

First, the function mvpalab_init() initializes the toolbox. This function returns a default configuration structure cfg, which consist of all the required configuration parameters for an analysis. Please see the Material and Methods section for a detailed description of each field of the configuration variable.

2. Run the configuration file:

run cfg_file.m

For the sake of clarity and for maintaining a clean code organization, all the configuration code should be placed in an external configuration file cfg_file.m. This file will be executed after the toolbox initialization. Users should modify this configuration variable to set up the desired configuration for a specific decoding analysis.

The first required information that should be specified by the user is the working directory and the location of the dataset to be imported and analyzed. This includes, for each class or condition, the name of each individual subject data file and the complete path of the class folder. These parameters can be defined in the configuration file as follows:

cfg_file.m

% Working directory:
cfg.location = pwd;

% Conditions data paths:
cfg.study.dataPaths{1,1} = 'C:\...\class_a\'; % Condition A
cfg.study.dataPaths{1,2} = 'C:\...\class_b\'; % Condition B

% Subjects data files:
cfg.study.dataFiles{1,1} = { % Condition A
     ‘subject_01.mat’, 
     ‘subject_02.mat’, 
     ‘subject_03.mat’
};
cfg.study.dataFiles{1,2} = { % Condition B
     ‘subject_01.mat’, 
     ‘subject_02.mat’, 
     ‘subject_03.mat’
};

Before computing the multivariate decoding analysis, the MVPAlab Toolbox can be used to execute several preprocessing procedures that may improve the final results in different ways (e.g. increasing accuracy, avoiding skewed results, data normalization, data smoothing, etc.). The default configuration of each of these procedures is initialized when MVPAlab toolbox is launched. However, these procedures and their configuration parameters can be adjusted in this file to meet the required specific analysis conditions.

For example, different performance metrics can be enabled/disabled as follows:

cfg_file.m

cfg.classmodel.roc       = true;
cfg.classmodel.auc       = true;
cfg.classmodel.confmat   = false;
cfg.classmodel.precision = false;
cfg.classmodel.recall    = false;
cfg.classmodel.f1score   = false;
cfg.classmodel.wvector   = false;

In section Analysis configuration all of these preprocessing procedures and their configuration parameters will be meticulously described.

3. Import data and extract feature vectors:

[cfg,data,fv] = mvpalab_import(cfg);

Once the MVPAlab toolbox is initialized and a specific analysis configured, the function mvpalab_import(cfg) imports and preprocess the datasets provided, according to the configuration file cfg. This function returns a copy of the preprocessed data data, which can be omitted to save memory, and the extracted feature vectors fv, which will be the input for the classification models.

During the feature extraction step, feature vectors are defined as a selection/combination of variables of the original dataset. Typical multivariate analyses use the raw voltage of the signal as a feature for the classification, but other characteristics, such the power envelope of the signal, can also be used as features. These feature vectors are extracted as shown in the following figure:

For each participant, time-point and trial, two feature vectors (one for each condition or class) are generated, consisting of the raw potential (or any other feature such the power envelope) measured in all electrodes.

• The feature vector and data variables are cell arrays structured as follows: [1 x subjects].

• Each cell in fv contains a data matrix X - [trials x features x timepoints] with the feature vectors of individual subjects and a logical vector Y including the true labels of the subject's dataset.

• The data - [features x timepoints x trials] variable contains, for each condition, a data matrix including the preprocessed dataset .

4. Compute a multivariate decoding analysis:

[result,cfg] = mvpalab_mvpa(cfg,fv);

The MVPAlab Toolbox computes two main analyses: time-resolved Multivariate Pattern Analysis (TR-MVPA) and time-resolved Multivariate Cross-Classification (TR-MVCC). Different types of analyses such the Temporal Generalization, the Feature Contribution Analysis or the Frequency Contribution Analysis are derived from them.

Here, the function mvpalab_mvpa(cfg,fv) computes the multivariate pattern analysis. Other functions such as mvpalab_mvcc(cfg,fv) or mvpalab_sfilter(cfg,fv) are available for different analyses.

These functions return the variable result, which includes the time-resolved decoding performance for every performance metric enabled in the configuration file. In addition, the result files are automatically saved in separate folders in the project directory.

4.1 Statistical analysis

To compute the statistical analysis and draw statistical inferences at the group level, one additional step should be added to the former execution pipeline:

% Compute permutation test:
[permaps,cfg] = mvpalab_permaps(cfg,fv);
stats = mvpalab_permtest(cfg,result,permaps);

These functions implement a non-parametric cluster-based permutation test, returning the variable stats, which includes statistically significant clusters found in the data. Please, see Cluster-based permutation test for an exhaustive description of this approach.

5. Plot the result:

run plot_file.m

Finally, in addition to the graphic user interface, MVPAlab includes several plotting routines, allowing users to design customizable and ready-to-publish figures and animations. Several demo scripts for different types of analyses and result representations are included in the MVPAlab Toolbox folder.

In section Result representation pipelines all of the following configuration parameters and functions will be meticulously described.

Here you can find an example of a basic plot file:

plot_file.m

% Initialize and configure plots:
graph = mvpalab_plotinit();

% Load results and and statistics if needed:
load results/time_resolved/acc/result.mat
load results/time_resolved/acc/stats.mat

% Plot significant clusters (above and below chance):
graph.stats.above = true;
graph.stats.below = true;

% Significant indicator:
graph.sigh = .4;

% Title:
graph.title = 'Demo plot (statistical significance)';

% Axis limits:
graph.xlim = [-200 1500];
graph.ylim = [.3 .95];

% Axes labels and titles:
graph.xlabel = 'Time (ms)';
graph.ylabel = 'Classifier performance';
graph.title = 'Demo plot (no statistical significance)';

% Smooth results:
graph.smoothdata = 5; % (1 => no smoothing)

% Plot results:
figure;
hold on
mvpalab_plotdecoding(graph,cfg,result,stats);

This code produces the following plot: