## Core functions

### Model fitting

**imapLMM**- Core function of*i*Map4. 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*i*Map4 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)`

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.