no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.

@@ Line 1: / Line 1: @@
+====== 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') =====
+<file> 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!</file>
+===== 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}}
+<code matlab 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]);</code>
+In this case, figures were manually positioned on the screen and a screenshot was taken, but that can, naturally, be scripted as well :)