Core functions

Model fitting

  • imapLMM - Core function of iMap4. It called Matlab class LinearMixedModel from Statistics Toolbox™ (R2013b or above) to estimate the LMM function.

Usage: [LMMmap, lmexample] = imapLMM(FixMap, PredictorM, Mask, opt, formula, varargin)

FixMap     - total number of items × xSize × ySize  
PredictorM - dataset format of condition Matrix, total number of items × number of predictor. 
             Categorical column must set to nominal  
Mask       - 2D mask, for reducing the number of computation  
opt        - structure. option to define parallel grid (opt.parallelname) 
             and option to compute each single categorical condition beta (opt.singlepredi)  
formula/varargin - same as fitlme, type '>>help fitlme' for more information    
  • imapGLMM - same usage as imapLMM, but instead of fitting a Linear Mixed Model it fits a Generalized Linear Mixed Model. It gives you the possibility to fit other distribution in the exponential family. However, you cannot perform spatial clustering on the output yet - we are still developing appropriate method for the statistical testing of spatial GLMM model.

Statistics and Hypothesis testing

  • imapLMMcontrast - It takes LMMmap and outputs the conventional model fitting parameters and model statistics in StatMap.

Usage: StatMap = imapLMMcontrast(LMMmap, opt)

opt is a structure specifying the statistics in StatMap.

opt.type     - model/fixed/random/model beta/predictor beta
opt.alpha    - default 0.05  
opt.c        - for coefficients and Catepredictors only, cell array containing contrast vector/matrix  
opt.h        - for coefficients and Catepredictors only, cell array containing hypothesis vector/matrix  
opt.onetail  - option to do onetail test, perform on two tail threshold for convenience (alpha/2)     - for coefficients and Catepredictors only, name of each contrast (for plotting)  
  • imapLMMmcc - We need to account for the Type I error resulting from massive univariate, pixel-wise testing before we can interpret the statistical output from imapLMMcontrast. Using imapLMMmcc, you can either 1) apply conventional multiple comparison correction on the p-value; 2) apply non-parametric statistics based on resampling that have good control for both Type I and II error. We highly recommend option 2). In iMap4 we developed and implemented two resampling algorithms: a) permutation, b) bootstrap spatial clustering. Resampling is performed in imapLMMresampling.

Usage: StatMap_c = imapLMMmcc(StatMap, LMMmap, mccopt, varargin)

mccopt is a structure specifying the method for multiple comparison problem.

mccopt.methods  - fdr/bonferroni/randomfield/cluster/bootstrap/permutation  
mccopt.bootopt  - 1 cluster mass, 2 cluster size, 3 both cluster mass and size, 4 cluster dense  
mccopt.bootgroup- grouping variable for bootstrap and permutation (to keep group variance constant). 
                  Input must be a cell specifying a Group variables in the PredictorM
mccopt.sbjvec   - subject vector for bootstrap. 
                  Input must be a cell specifying a Group variables in the PredictorM.
                  This is important when there are multiple grouping variables in the mixed model such as (1|subject) + (1|stimuli)
mccopt.nboot    - number of resampling for bootstrap or permutation  
mccopt.sigma    - smoothing parameter (for Random field test)  
mccopt.clustSize- cluster size threshold (for cluster test)  
mccopt.clustVal - cluster value threshold (for cluster test)  
mccopt.parametic- for FDR  
mccopt.tfce     - signal enhancement base on Threshold-free cluster enhancement developed by Smith & Nichols, 2009  

varargin - replace it with FixMap for resampling algorithm.

New statistics are save in the original StatMap as a updated output StatMap_c

  • imapLMMresample - It performs a nonparametric statistical test by calculating Monte-Carlo estimates of the significance probabilities and/or critical values from the resampling distribution.

    This function is called by imapLMMmcc internally with bootstrap or permutation option, but you can call it independently as well.

Usage: ResampStat = imapLMMresample(FixMap, LMMmap, c, h, effect, method, nboot, grouping, rmRE, varargin)

FixMap   - same one you used in imapLMM  
LMMmap   - output of imapLMM.  
c        - contrast matrix  
h        - hypothesis matrix   
effect   - fixed/random  
method   - permutation/bootstrap  
nboot    - number of resampling  
grouping - specify group index to keeping the group variance constant  
rmRE     - 1 remove random effect, 0 keeping subject variance  
varargin - Optional: specify a subject vector. This is important when 
           there are multiple grouping variables exist in the mixed model 
           such as (1|subject) + (1|stimuli)

ResampStat - A structure with field {parameters} {resampleTABLE} {resampleFvalue} {resamplePvalue} {resmapleBeta}

Figure output and Post-Hoc analysis

  • imapLMMdisplay - It displays output of imapLMMcontrast or imapLMMmcc.

Usage: imapLMMdisplay(StatMap, normalized, backgroundfile, colourmap, colormaprange, distplot, foldername)

normalized - colormap value will be normalized [1] as default for multiple contrast. 
backgroundfile could be [image path]/[matrix]/[empty]
colormap could be predefined. iMap4 implemented a red-blue map as default but looks not as good as the new colormap parula in Matlab
output distribution of statistic value (optional, default 0)
foldername - string to specify a foldername to save the output.
  • imapLMMreport - It prints the numerical report of StatMap on the MATLAB console.

Usage: imapLMMreport(StatMap, varargin)

Optional output of the conditional mean/beta
% a 4d matrix with (Npredictor,beta[95%CI],xSize,ySize)
betamaps  = varargin{1};
  • imapLMMposthoc - Post-hoc contrast on raw/smoothed data (total fixation duration or fixation number), based on significant linear contrast. An interface will allow you to select one or more significant clusters. Notice: mean fixation duration could be computed by total fixation duration./fixation number

Usage: PostHoc = imapLMMposthoc(StatMap, FixMap, LMMmap, method, flag, formula2)

method   - 'mean' or 'sum' value in the cluster  
flag     - 1 display result (default)  
formula2 - using another LMM formula other than the original model to perform posthoc  

You can find a visual example here.

results matching ""

    No results matching ""