## 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
opt        - structure. option to define parallel grid (opt.parallelname)
and option to compute each single categorical condition beta (opt.singlepredi)

• 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, 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.