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) opt.name - 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, 2009varargin - 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)Output:
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.