Developer Guide - The Format Of GLM Files (v4)

The table below describes the order of values stored in version 4 of GLM files. Note that a GLM file's structure partially depends on the type of data (FMR-STC, VMR-VTC, SRF-MTC data) that was originally used to calcualte the GLM, which is stored in the second entry "Type of GLM". The GLM format is also different for RFX-GLMs as compared to standard GLMs (entry 3 "RFX-GLM flag"). The data itself is stored at the end of the file and needs to use provided header information to know how many voxels are stored and how many values are stored for each voxel. Note that provided axis/bounding box names are not in DICOM convention but in internal (BV) convention.

BYTESTYPEDESCRIPTION
2 int File version
1 byte Type of GLM flag (0 - FMR-STC, 1 - VMR-VTC, 2 - SRF-MTC)
1 byte RFX-GLM flag (0 - std, 1 - RFX)
 
-- begin: only if RFX-GLM flag is 1 --
4 int No. of subjects ("NSubjects", see explanations after table)
4 int No. of predictors per subject ("NPredictorsPerSubject", see below)
-- end: only if RFX-GLM flag is 1 --
 
4 int No. of time points ("NTimePoints", see explanations after table)
4 int No. of all predictors ("NAllPredictors", see explanations after table)
4 int No. of confound predictors
4 int No. of studies
 
-- begin: only if more than 1 study --
4 int No. of studies with confound info - for loop below (can be 0, if not info provided)
N x 4 int Loop over no. of studies (N) providing no. of confounds per study
-- end: only if more than 1 study --
 
1 byte Separate predictors flag (0 -> no, 1 -> seperate study, 2 -> sepearate subject predictors)
1 byte Time course normalization flag (1 -> z transf, 2 - baseline z, 3 -> perc-change)
2 int Resolution (1, 2, 3… with respect to anatomical resolution)
1 byte Serial correlation performed flag (0 -> no, 1 -> AR(1), 2 -> AR(2))
4 float Mean serial correlation before correction
4 float Mean serial correlation after correction
 
-- begin: if type of GLM flag 0 (FMR-STC GLM) --
2 int DimX (no. of slice columns)
2 int DimY (no. of slice rows)
2 int DimZ (no. of slices)
-- end: if type of GLM flag 0 (FMR-STC GLM) --
 
-- begin: if type of GLM flag 1 (VMR-VTC GLM) --
2 int Bounding box: StartX
2 int Bounding box: EndX
2 int Bounding box: StartY
2 int Bounding box: EndY
2 int Bounding box: StartZ
2 int Bounding box: EndZ
-- end: if type of GLM flag 1 (VMR-VTC GLM) --
 
-- begin: if type of GLM flag 2 (SRF-MTC GLM) --
4 int No. of vertices
-- end: if type of GLM flag 2 (SRF-MTC GLM) --
 
1 byte Cortex-based mask flag (1 -> (grey matter) mask has been used)
4 int No. of voxels in mask (e.g. for adjusted Bonferroni correction)
N x 1 char Name of cortex-based mask file
 
++ begin: loop over no. of studies ++
4 int No. of time points (volumes) in study
N x 1 char Name of study data file
-- begin: only if type of GLM 2 (cg-aligned SRF-MTC GLM) --
N x 1 char Name of SSM file (cortex-based alignment data)
-- end: only if type of GLM 2 (cg-aligned SRF-MTC GLM) --
N x 1 char Name of SDM file (study design matrix file)
++ end: loop over no. of studies ++
 
-- begin: only if RFX-GLM flag is 0 --
N x M float Design matrix (outer loop: N rows (time points); inner loop: M cols (predictors))
M x M float M rows, cols (predictors): Inverted X'X matrix (inv(transposed DM x DM))
-- end: only if RFX-GLM flag is 0 --
 
N x M float The actual data (outer loop: N values (e.g. betas); inner loop: M voxels/vertices), for details, see below

The last row in the table above refers to the actual data that follows the header information. The data is stored as a series of volumes each containing a map for a specific beta (or other) value for each voxel/vertex. The number of voxels/vertices is calculated based on the provided dimensions for the type of GLM. For FMR-STC GLMs, the number of voxels is:

NVoxels = DimX (no. of slice columns) x DimY (no. of slice rows) x DimZ (no. of slices)

For VMR-VTC GLMs, the number of voxels is:

NVoxels = (EndX - StartX)/Resolution * (EndY - StartY)/Resolution *(EndZ - StartZ)/Resolution

For SRF-MTC GLMs, the number of "voxels" is the number of vertices. The number of values (and, thus, the number of volume maps) differs with respect to the type of GLM. For a RFX-GLM (RFX-GLM flag equals 1), the number of values per voxel is simply:

NValuesPerVoxel = 1 + NSubjects * NPredictorsPerSubject

In case of a standard GLM, the number depends mainly on the number of overall predictors (see "NAllPredictors" entry in the header) but differes with respect to the performed serial correlation approach (if any). In case that no serial correlation correction has been performed, the number of values per voxel is:

NValuesPerVoxel = 2 * NAllPredictors + 2

If a AR(1) approach (first-order autoregressive model) has been used to correct serial correlations, 1 additional volume is stored (NValuesPerVoxel = 2*NAllPredictors+3), and in case of a AR(2) approach (second-order autoregressive model) has been used, two additional values are stored (NValuesPerVoxel = 2*NAllPredictors + 4).

The first value (volume) of the data contains the multiple correlation coefficient R indicating the goodness-of-fit for the respective voxel's time course and to allow to calculate the proportion of explained (R2) and unexplained (1 - R2) variance. The second stored value per voxel contains the overall sum-of-squares term (SStotal) that can be used together with the R value to calculate the variance of the residuals (see below). Following the first two values, the estimated beta values are stored, i.e. one value for each predictor of the design matrix (NAllPredictors values). Following the beta values, another set of NAllPredictors values follows containing the sum-of-squares indicating the covariation of each predictor with the time course data (SSXiY). These values are stored to allow easy calculation of explained variance terms for restricted models (i.e. to allow application of the extra-sum-of-squares principle); these values may be probably ignored (not stored) for custom processing. The next volume contains the mean value of the (normalized) fMRI time course. Only in case that serial correlation correction has been performed, one or two more values are stored. In case that the AR(1) model has been used (serial correlation flag equals 1, see table above), the estimated order 1 autocorrelation value (ACF(1) term) is stored for each voxel. In case that the AR(2) model has been used (serial correlation flag equals 2, see table above), the two estimated ACF terms are stored, i.e. the data contains one value more than in the case of the AR(1) model. With the proper number of values per voxel, the number of overall values to be read at the end of the file can finally calculated as:

NValues = NValuesPerVoxel * NVoxels

Calculating standard errors for beta and contrast values

The (non-RFX) GLM file stores enough values to allow calculation of standard errors for beta and contrast values for each voxel, if desired. The stored multiple correlation coefficient R together with the overall sum-of-squares term (SStotal) can be used to calculate the variance of the residuals as follows:

VARresiduals = SStotal * (1 - R2) / (NTimePoints - NAllPredictors)

Together with the stored inverted X'X matrix, this allows calculating the standard error for any beta or contrast t value using the usual equation (c is the contrast vector and b is the voxel's vector of stored beta values):

t = c'b / sqrt(VARresidualsc'(X'X)-1c)

Note, however, that in case of performed serial correlation correction, the inverted X'X matrix needs to be recalculated for each voxel from the stored design matrix X using the voxel-specific autocorrelation function term(s); furthermore the number of time points (NTimePoints) needs to be corrected (subtraction of 1 for AR(1) model, subtraction of 2 for AR(2) model).