====== MDM::VOICondAverage - extract and average VOI time courses for conditions ======
===== Motivation =====
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.
===== Requirements =====
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, [[xff - SDM format|SDM]] for BV's motion correction output)
**Note: The same naming convention as for the [[mdm.ComputeGLM|ComputeGLM]] method is required!**
===== Reference / mdm.Help('VOICondAverage') =====
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!
===== Algorithm =====
The following steps are performed by the method:
* extracting region-averaged time courses (using the [[mdm.VOITimeCourses|VOITimeCourses]] method, this already per-cent or z-transforms the data!)
* accessing (or collecting) the onsets for all time courses (using the [[mdm.ConditionOnsets|ConditionOnsets]] method)
* accessing (or creating) the design matrices (for the removal of nuisance variance, using the [[mdm.SDMs|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
===== Usage example =====
The image below was created from one particular dataset, using cluster peaks of complex contrasts and the code below the image:
{{:mdm_voicondaverage_fccr_voiextracts.png?800|condition-averaged time courses for 4 conditions in 12 VOIs}}
% 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 :)