User Tools

Site Tools


mdm.voicondaverage

Differences

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

Link to this comparison view

mdm.voicondaverage [2011/03/15 03:44] (current)
jochen created
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 :)
mdm.voicondaverage.txt ยท Last modified: 2011/03/15 03:44 by jochen