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 the grouping variables in the PredictorM  
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)

Input:
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

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. *i*Map4 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.

• imapLMMposthoc - Post-hoc contrast on raw/smoothed data (total fixation duration or fixation number), based on significant linear contrast. A 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.