Deletions are marked like this.  Additions are marked like this. 
Line 107:  Line 107: 
MATHEMATICAL BACKGROUND  == MATHEMATICAL BACKGROUND == 
Line 138:  Line 138: 
The noise variance estimate (rvar) is computed as the sum of the squares of the residual error divided by the DOF. The DOF equals the number of rows of X minus the number of columns. 
For random effects analysis, the noise variance estimate (rvar) is computed as the sum of the squares of the residual error divided by the DOF. The DOF equals the number of rows of X minus the number of columns. For fixed effects analysis, the noise variance is estimated from the lowerlevel variances passed with yffxvar, and the DOF is the sum of the DOFs from the lower level. 
Index
Contents
Name
mri_glmfit
Synopsis
Arguments
glmdir dir 
save outputs to dir 


y inputfile 

fsgd FSGDF <gd2mtx> 
freesurfer descriptor file 
X design matrix file 

C contrast1.mat <C contrast2.mat ...> 

osgm 
construct X and C as a onesample group mean 
nocontrastsok 
do not fail if no contrasts specified 


pvr pvr1 <prv pvr2 ...> 
pervoxel regressors 
selfreg col row slice 
selfregressor from index col row slice 


wls yffxvar 
weighted least squares 
yffxvar yffxvar 
for fixed effects analysis 
ffxdof DOF 
dof for fixed effects analysis 
ffxdofdat ffxdof.dat 
text file with dof for fixed effects analysis 


w weightfile 
weight for each input at each voxel 
winv 
invert weights 
wsqrt 
sqrt of (inverted) weights 


fwhm fwhm 
smooth input by fwhm 
varfwhm fwhm 
smooth variance by fwhm 
nomasksmooth 
do not mask when smoothing 
noestfwhm 
turn off FWHM output estimation 


mask maskfile 
binary mask 
label labelfile 
use label as mask, surfaces only 
nomask 
do not use a mask (same as nocortex) 
nocortex 
do not use subjects ?h.cortex.label as label 
maskinv 
invert mask 
prune 
remove voxels that do not have a nonzero value at each frame 
noprune 
do not prune 
nology 
compute natural log of y prior to analysis 
logy 
compute natural log of y prior to analysis 
yhatsave 
save signal estimate (yhat) 
eressave 
save residual error (eres) 
yout y.out.mgh 
save input after preprocessing 
nopcc 
do not compute partial correlation coefficient 


surf subject hemi 
needed for some flags (uses white by default) 


sim nulltype nsim thresh csdbasename 
simulation perm, mcfull, mcz 
simsign signstring 
abs, pos, or neg. Default is abs. 
uniform min max 
use uniform distribution instead of gaussian 


skew 
compute skew and pvalue for skew 
kurtosis 
compute kurtosis and pvalue for kurtosis 
pca 
perform pca/svd analysis on residual 
tar1 
compute and save temporal AR1 of residual 
saveyhat 
flag to save signal estimate 
savecond 
flag to save design matrix condition at each voxel 
voxdump col row slice 
dump voxel GLM and exit 


seed seed 
used for synthesizing noise 
synth 
replace input with gaussian 


resynthtest niters 
test GLM by resynthsis 
profile niters 
test speed 


perform MRTM1 kinetic modeling 

perform MRTM2 kinetic modeling 



permforce 
force perumtation test, even when design matrix is not orthog 
diag Gdiag_no 
set diagnositc level 
diagcluster 
save sig volume and exit from first sim loop 
debug 
turn on debugging 
checkopts 
don't run anything, just check options and exit 
help 
print out information on how to use this program 
version 
print out version and exit 
nofixvertexarea 
turn off fixing of vertex area (for back comapt only) 
allowsubjrep 
allow subject names to repeat in the fsgd file (must appear before fsgd) 
allowzerodof 
mostly for ver special purposes 
illcond 
allow ill conditioned design matrices 
simdone SimDoneFile 
create DoneFile when simulation finished 
Description
Performs general linear model (GLM) analysis in the volume or the surface. Options include simulation for correction for multiple comparisons, weighted LMS, variance smoothing, PCA/SVD analysis of residuals, pervoxel design matrices, and 'self' regressors. This program performs both the estimation and inference. This program is meant to replace mris_glm (which only operated on surfaces). This program can be run in conjunction with mris_preproc.
MATHEMATICAL BACKGROUND
This brief intoduction to GLM theory is provided to help the user understand what the inputs and outputs are and how to set the various parameters. These operations are performed at each voxel or vertex separately (except with varfwhm).
The forward model is given by:
 y = W*X*B + n
where X is the NsbyNb design matrix, y is the NsbyNv input data set, B is the NbbyNv regression parameters, and n is noise. Ns is the number of inputs, Nb is the number of regressors, and Nv is the number of voxels/vertices (all cols/rows/slices). y may be surface or volume data and may or may not have been spatially smoothed. W is a diagonal weighing matrix.
During the estimation stage, the forward model is inverted to solve for B:
 B = inv(X'W'*W*X)*X'W'y
The signal estimate is computed as
 yhat = B*X
The residual error is computed as
 eres = y  yhat
For random effects analysis, the noise variance estimate (rvar) is computed as the sum of the squares of the residual error divided by the DOF. The DOF equals the number of rows of X minus the number of columns. For fixed effects analysis, the noise variance is estimated from the lowerlevel variances passed with yffxvar, and the DOF is the sum of the DOFs from the lower level.
A contrast matrix C has J rows and as many columns as columns of X. The contrast is then computed as:
 G = C*B
The Fratio for the contrast is then given by:
 F = G'*inv(C*inv(X'W'*W*X))*C')*G/(J*rvar)
The F is then used to compute a pvalue. Note that when J=1, this reduces to a twotailed ttest.
COMMANDLINE ARGUMENTS
glmdir dir
Directory where output will be saved. Not needed with sim.
The outputs will be saved in mgh format as:
 mri_glmfit.log  execution parameters (send with bug reports) beta.mgh  all regression coefficients (B above) eres.mgh  residual error rvar.mgh  residual error variance rstd.mgh  residual error stddev (just sqrt of rvar) y.fsgd  fsgd file (if one was input) wn.mgh  normalized weights (with w) yhat.mgh  signal estimate (with saveyhat) mask.mgh  final mask (when a mask is used) cond.mgh  design matrix condition at each voxel (with savecond) contrast1name/  directory for each contrast (see C)
 C.dat  copy of contrast matrix gamma.mgh  contrast (G above) F.mgh  Fratio sig.mgh  significance from Ftest (actually log10(p))
y inputfile
Path to input file with each frame being a separate input. This can be volume or surfacebased, but the file must be one of the 'volume' formats (eg, mgh, img, nii, etc) accepted by mri_convert. See mris_preproc for an easy way to generate this file for surface data.
fsgd fname <gd2mtx>
Specify the global design matrix with a FreeSurfer Group Descriptor File (FSGDF). See http://surfer.nmr.mgh.harvard.edu/docs/fsgdf.txt for more info. The gd2mtx is the method by which the group description is converted into a design matrix. Legal values are doss (Different Offset, Same Slope) and dods (Different Offset, Different Slope). doss will create a design matrix in which each class has it's own offset but forces all classes to have the same slope. dods models each class with it's own offset and slope. In either case, you'll need to know the order of the regressors in order to correctly specify the contrast vector. For doss, the first NClass columns refer to the offset for each class. The remaining columns are for the continuous variables. In dods, the first NClass columns again refer to the offset for each class. However, there will be NClass*NVar more columns (ie, one column for each variable for each class). The first NClass columns are for the first variable, etc. If neither of these models works for you, you will have to specify the design matrix manually (with X).
X design matrix file
Specify the design matrix in matlab4 format. Within matlab, you can save a matrix with save('X.mat','X','v4');
C contrast1.mat <C contrast2.mat ...>
Specify one or more contrasts to test. The contrast.mat file is an ASCII text file with the contrast matrix in it (make sure the last line is blank). The output will be saved in glmdir/contrast1, glmdir/contrast2, etc. Eg, if C normvcont.mat, then the ouput will be glmdir/normvcont.
osgm
Construct X and C as a onesample group mean. X is then a onecolumn matrix filled with all 1s, and C is a 1by1 matrix with value 1. You cannot specify both X and osgm. A contrast cannot be specified either. The contrast name will be osgm.
pvr pvr1 <prv pvr2 ...>
Pervoxel (or vertex) regressors (PVR). Normally, the design matrix is 'global', ie, the same matrix is used at each voxel. This option allows the user to specify voxelspecific regressors to append to the design matrix. Note: the contrast matrices must include columns for these components.
selfreg col row slice
Create a 'selfregressor' from the input data based on the waveform at index col row slice. This waveform is residualized and then added as a column to the design matrix. Note: the contrast matrices must include columns for this component.
w weightfile winv wsqrt
Perform weighted LMS using pervoxel weights from the weightfile. The data in weightfile must have the same dimensions as the input y file. If winv is flagged, then the inverse of each weight is used as the weight. If wsqrt is flagged, then the square root of each weight is used as the weight. If both are flagged, the inverse is done first. The final weights are normalized so that the sum at each voxel equals 1. The normalized weights are then saved in glmdir/wn.mgh. The winv and wsqrt flags are useful when passing contrast variances from a lower level analysis to a higher level analysis (as is often done in fMRI).
fwhm fwhm
Smooth input with a Gaussian kernel with the given fullwidth/halfmaximum (fwhm) specified in mm. If the data are surfacebased, then you must specify surf, otherwise mri_glmfit assumes that the input is a volume and will perform volume smoothing.
varfwhm fwhm
Smooth residual variance map with a Gaussian kernel with the given fullwidth/halfmaximum (fwhm) specified in mm. If the data are surfacebased, then you must specify surf, otherwise mri_glmfit assumes that the input is a volume and will perform volume smoothing.
mask maskfile label labelfile maskinv
Only perform analysis where mask=1. All other voxels will be set to 0. If using surface, then labelfile will be converted to a binary mask (requires surf). If maskinv is flagged, then performs analysis only where mask=0. If performing a simulation (sim), map maximums and clusters will only be searched for in the mask. The final binary mask will automatically be saved in glmdir/mask.mgh
prune
Remove voxels from the analysis if the ALL the frames at that voxel do not have an absolute value that exceeds zero (actually FLT_MIN). This helps to prevent the situation where some frames are 0 and others are not. If no mask is supplied, a mask is created and saved. If a mask is supplied, it is pruned, and the final mask is saved. Do not use with sim. Rather, run the nonsim analysis with prune, then pass the created mask when running simulation. It is generally a good idea to prune (though the default is not to). noprune will turn off pruning if it had been turned on.
surf subject hemi
Specify that the input has a surface geometry from the hemisphere of the given FreeSurfer subject. This is necessary for smoothing surface data (fwhm or varfwhm), specifying a label as a mask (label), or running a simulation (sim) on surface data. If surf is not specified, then mri_glmfit will assume that the data are volumebased and use the geometry as specified in the header to make spatial calculations.
pca
Flag to perform PCA/SVD analysis on the residual. The result is stored in glmdir/pcaeres as v.mgh (spatial eigenvectors), u.mat (frame eigenvectors), sdiag.mat (singular values). eres = u*s*v'. The matfiles are just ASCII text. The spatial EVs can be loaded as overlays in tkmedit or tksurfer. In addition, there is stats.dat with 5 columns:
 (1) component number (2) variance spanned by that component (3) cumulative variance spanned up to that component (4) percent variance spanned by that component (5) cumulative percent variance spanned up to that component
saveyhat
Flag to save the signal estimate (yhat) as glmdir/yhat.mgh. Normally, this pis not very useful except for debugging.
savecond
Flag to save the condition number of the design matrix at eaach voxel. Normally, this is not very useful except for debugging. It is totally useless if not using weights or PVRs.
seed seed
Use seed as the seed for the random number generator. By default, mri_glmfit will select a seed based on timeofday. This only has an effect with sim or synth.
synth
Replace input data with whise gaussian noise. This is good for testing.
voxdump col row slice
Save GLM data for a single voxel in directory glmdir/voxdumpcolrowslice. Exits immediately. Good for debugging.
MONTE CARLO SIMULATION AND CORRECTION FOR MULTIPLE COMPARISONS
One method for correcting for multiple comparisons is to perform simulations under the null hypothesis and see how often the value of a statistic from the 'true' analysis is exceeded. This frequency is then interpreted as a pvalue which has been corrected for multiple comparisons. This is especially useful with surfacebased data as traditional random field theory is harder to implement. This simulator is roughly based on FSLs permuation simulator (randomise) and AFNIs nullz simulator (AlphaSim). Note that FreeSurfer also offers False Discovery Rate (FDR) correction in tkmedit and tksurfer.
The estimation, simulation, and correction are done in three distinct phases:
 Estimation: run the analysis on your data without simulation.
 At this point you can view your results (see if FDR is sufficient:).
 Simulation: run the simulator with the same parameters
 as the estimation to get the Cluster Simulation Data (CSD).
 Clustering: run mri_surfcluster or mri_volcluster with the CSD
 from the simulator and the output of the estimation. These programs will print out clusters along with their pvalues.
The Estimation step is described in detail above. The simulation is invoked by calling mri_glmfit with the following arguments:
sim nulltype nsim thresh csdbasename simsign sign
It is not necessary to specify glmdir (it will be ignored). If you are analyzing surface data, then include surf.
nulltype is the method of generating the null data. Legal values are:
 (1) perm  perumation, randomly permute rows of X (cf FSL randomise) (2) mcfull  replace input with white gaussian noise (3) mcz  do not actually do analysis, just assume the output
is zdistributed (cf ANFI AlphaSim)
nsim  number of simulation iterations to run (see below) thresh  threshold, specified as log10(pvalue) to use for clustering csdbasename  base name of the file to store the CSD data in. Each
 contrast will get its own file (created by appending the contrast name to the base name). A '.csd' is appended to each file name.
Multiple simulations can be run in parallel by specifying different csdbasenames. Then pass the multiple CSD files to mri_surfcluster and mri_volcluster. The Full CSD file is written on each iteration, which means that the CSD file will be valid if the simulation is aborted or crashes.
In the cases where the design matrix is a single columns of ones (ie, onesample group mean), it makes no sense to permute the rows of the design matrix. mri_glmfit automatically checks for this case. If found, the design matrix is rebuilt on each permutation with randomly selected +1 and 1s. Same as the 1 option to FSLs randomise.
simsign sign
sign is either abs (default), pos, or neg. pos/neg tell mri_glmfit to perform a onetailed test. In this case, the contrast matrix can only have one row.
Examples
Example 1
command foo i f o out
description
Example 2
command foo i f o out f fvalue
description
Bugs
None
See Also
Links
Methods Description
description description
References
Reporting Bugs
Report bugs to <analysisbugs@nmr.mgh.harvard.edu>