MDM::VOICondAverage - extract and average VOI time courses for conditions

Just as statistical maps are useful to visualize whole-brain patterns of activity, it can be useful to inspect and visualize the time course properties of conditions in specific regions of the brain.

As this usually requires several, repetitive steps (data extraction, averaging across voxels of regions, removing nuisance variance, normalizing data to a baseline, averaging across trials within conditions, etc.), a comprehensive method is useful to perform these steps.

This function is currently implemented for BrainVoyager QX's MDM, PRT and VTC formats only. The following files must be available:

• MDM file referencing time course (VTC) as well as protocol (PRT) files containing the onsets of the conditions of interest
• referenced PRT and VTC files for all runs of all subjects
• optionally the realignment parameter files (supported formats: TXT for SPM rp*.txt files, SDM for BV's motion correction output)

Note: The same naming convention as for the ComputeGLM method is required!

 MDM::VOICondAverage  - average condition timecourses
 
 FORMAT:       [mtc, mtcse] = mdm.VOICondAverage(voi, conds [, options])
 
 Input fields:
 
       voi         VOI object
       conds       1xC cell array of condition names
       options     optional 1x1 struct with fields
        .avgtype   either of 'conv', 'deconv', or {'meanx'}
        .avgwin    length of averaging window in ms (default: 20000)
        .baseline  either of 'cond', 'run', or {'trial'} (only with meanx)
        .basewin   baseline window in ms (default: -4000:2000:0)
        .conds     list of conditions (default: first PRT)
        .group     either of 'ffx', {'off'}, 'raw', or 'rfx'
        .interp    interpolation method, (see flexinterpn_method, 'cubic')
        .motpars   motion parameters (Sx1 cell array with sdm/txt files)
        .motparsd  also add diff of motion parameters (default: false)
        .motparsq  also add squared motion parameters (default: false)
        .ndcreg    number of deconvolution time bins (default: 12)
        .remnuis   remove nuisance (only for 'meanx', default: true)
        .restcond  remove rest condition (rest cond. name, default: '')
        .robust    perform robust instead of OLS regression
        .samptr    upsample TR (milliseconds, if not given use first data)
        .sdse      either or {'SD'} or 'SE'
        .subsel    cell array with subject IDs to work on
        .subvois   subject specific VOIs, either 'sub_', '_sub', {'voi}
        .tfilter   add filter regressors (cut-off in secs)
        .tfilttype temporal filter type (either 'dct' or {'fourier'})
        .trans     either of {'none'}, 'psc', 'z'
        .unique    flag, only extract unique functional voxels (false)
        .voisel    cell array with sub-VOI selection to use
        .xconfound just as motpars, but without restriction on number
 
 Output fields:
 
       mtc         TxCxS numeric array (mean Time-x-Condition-x-Subject)
       mtcse       TxCxS numeric array (SD/SE Time-x-Condition-x-Subject)
 
 Note: this call is only valid if all model files in the MDM are PRTs!
 
       for conv and deconv, a GLM regression is performed and the
 
       the baseline window (basewin) must be evenly spaced!

The following steps are performed by the method:

• extracting region-averaged time courses (using the VOITimeCourses method, this already per-cent or z-transforms the data!)
• accessing (or collecting) the onsets for all time courses (using the ConditionOnsets method)
• accessing (or creating) the design matrices (for the removal of nuisance variance, using the SDMs method)
• applying a selecting of subjects, if desired
• allocating space in memory (for time course extracts and their standard deviation)
• removal of nuisance variance (plain regression for now)
• sampling the baseline window as well as the averaging window (in the desired temporal resolution, using cubic spline by default)
• subtracting the baseline of the data
• potentially collapsing across subjects (FFX)
• computing means and standard deviation across trials
• optionally computing mean and standard deviation across subjects (RFX)
• optionally re-scaling the standard deviation as standard error

The image below was created from one particular dataset, using cluster peaks of complex contrasts and the code below the image:

mdm_voiaverage_example.m

% load MDM
mdm = xff('*.mdm');
 
% load VOI
voi = xff('*.voi');
 
% get list of conditions from first protocol
prt = xff(mdm.XTC_RTC{1, 2});
conds = prt.ConditionNames;
 
% extract average timecourses for all conditions with options:
% - baseline window is from -2000 through 2000 milliseconds (sampled in 2s intervals)
% - motion parameters from mdm.RunTimeVars are used (if present) to remove nuisance variance
% - FFX grouping
% - the sampling of the average time courses is in 100ms steps
% - the error term returned is SE (SD / sqrt(N))
[fmtc, fmtcse] = mdm.VOICondAverage( ...
    voi, conds, struct( ...
        'basewin', [-2000:1000:2000], ...
        'motpars', true, ...
        'group',   'ffx', ...
        'samptr',  100, ...
        'sdse',    'se'));
 
% create list of colors
col = [1, 0, 0; 0.8, 0.2, 0.2; 0, 0, 1; 0.2, 0.2, 0.8];
 
% the plots were then created as follows:
% - get the VOI names
vn = voi.VOINames;
 
% loop over VOIs
for vc = 1:numel(vn)
 
    % create a figure and axes object
    f(vc) = figure;
    a = axes;
 
    % loop over condidions
    for x=1:numel(conds)
 
        % use tcplot to plot into the same axes
        l(x) = tcplot(a, 0:0.1:20, fmtc(:, x, vc), fmtcse(:, x, vc), fmtcse(:, x, vc), ...
            struct('color', col(x, :), 'spalpha', 0.2, 'lwidth', 3));
        end
 
        % add title and legend
        title(vn{vc});
        legend(l(:), conds{:});
    end
end
 
% set figures to same size
set(f, 'Position', [200, 200, 400, 300]);

In this case, figures were manually positioned on the screen and a screenshot was taken, but that can, naturally, be scripted as well :)