*SPM User's Ultimate Guide: For Alpha Males, By Alpha Males*. The title was perhaps a little ambitious, since I stopped updating it after only a few dozen pages. In particular I remember a section where I attempted to tease apart everything contained within the SPM.mat files output after first- and second-level analyses. To me this was the most important section, since complex model setups could be executed fairly easily by someone with a good understanding of Matlab code, but I never completed it.

Fortunately, however, there is someone out there who already vivisected the SPM.mat file and publicly displayed its gruesome remains in the online piazza. Researcher Nikki Sullivan has written an excellent short summary of what each field means, broken down into neat, easily digestible categories. You can find it on her website here, and I have also copied and pasted the information below. It makes an excellent shorthand reference, especially if you've forgotten, for example, where contrast weights are stored in the structure, and don't want to go through the tedium of typing SPM, then SPM.xY, then SPM.xY.VY, and so on.

But if you've forgotten how to rock that body? Girl, ain't no remedy for

*that.*

========================

### details on experiment:

### SPM.xY.RT - TR length (RT ="repeat time")

SPM.xY.P - matrix of file names

SPM.xY.VY - # of runs x 1 struct array of mapped image volumes (.img file info)

SPM.modality - the data you're using (PET, FMRI, EEG)

SPM.stats.[modality].UFp - critical F-threshold for selecting voxels over which the non-sphericity is estimated (if required) [default: 0.001]

SPM. stats.maxres - maximum number of residual images for smoothness estimation

SPM. stats.maxmem - maximum amount of data processed at a time (in bytes)

SPM.SPMid - version of SPM used

SPM.swd - directory for SPM.mat and img files. default is pwd

### basis function:

### SPM.xBF.name - name of basis function

SPM.xBF.length - length in seconds of basis

SPM.xBF.order - order of basis set

SPM.xBF.T - number of subdivisions of TR

SPM.xBF.T0 - first time bin (see slice timing)

SPM.xBF.UNITS - options: 'scans'|'secs' for onsets

SPM.xBF.Volterra - order of convolution

SPM.xBF.dt - length of time bin in seconds

SPM.xBF.bf - basis set matrix

### Session Stucture:

*user-specified covariates/regressors (e.g. motion)*SPM.Sess([sesssion]).C.C - [nxc double] regressor (c#covariates,n#sessions)

SPM.Sess([sesssion]).C.name - names of covariates

*conditions & modulators specified - i.e. input structure array*SPM.Sess([sesssion]).U(condition).dt: - time bin length {seconds}

SPM.Sess([sesssion]).U(condition).name - names of conditions

SPM.Sess([sesssion]).U(condition).ons - onset for condition's trials

SPM.Sess([sesssion]).U(condition).dur - duration for condition's trials

SPM.Sess([sesssion]).U(condition).u - (t x j) inputs or stimulus function matrix

SPM.Sess([sesssion]).U(condition).pst - (1 x k) peri-stimulus times (seconds)

*parameters/modulators specified*SPM.Sess([sesssion]).U(condition).P - parameter structure/matrix

SPM.Sess([sesssion]).U(condition).P.name - names of modulators/parameters

SPM.Sess([sesssion]).U(condition).P.h - polynomial order of modulating parameter (order of polynomial expansion where 0none)

SPM.Sess([sesssion]).U(condition).P.P - vector of modulating values

SPM.Sess([sesssion]).U(condition).P.P.i - sub-indices of U(i).u for plotting

*scan indices for sessions*SPM.Sess([sesssion]).row

*effect indices for sessions*SPM.Sess([sesssion]).col

*F Contrast information for input-specific effects*SPM.Sess([sesssion]).Fc

SPM.Sess([sesssion]).Fc.i - F Contrast columns for input-specific effects

SPM.Sess([sesssion]).Fc.name - F Contrast names for input-specific effects

SPM.nscan([session]) - number of scans per session (or if e.g. a t-test, total number of con*.img files)

### global variate/normalization details

### SPM.xGX.iGXcalc - either "none" or "scaling." for fMRI usually is "none" (no global normalization). if global normalization is "Scaling", see spm_fmri_spm_ui for parameters that will then appear under SPM.xGX.

### design matrix information:

### SPM.xX.X - Design matrix (raw, not temporally smoothed)

SPM.xX.name - cellstr of parameter names corresponding to columns of design matrix

SPM.xX.I - nScan x 4 matrix of factor level indicators. first column is the replication number. other columns are the levels of each experimental factor. SPM.xX.iH - vector of H partition (indicator variables) indices

SPM.xX.iC - vector of C partition (covariates) indices

SPM.xX.iB - vector of B partition (block effects) indices

SPM.xX.iG - vector of G partition (nuisance variables) indices

SPM.xX.K - cell. low frequency confound: high-pass cutoff (secs)

SPM.xX.K.HParam - low frequency cutoff value

SPM.xX.K.X0 - cosines (high-pass filter)

SPM.xX.W - Optional whitening/weighting matrix used to give weighted least squares estimates (WLS).

- if not specified spm_spm will set this to whiten the data and render the OLS estimates maximum likelihood i.e. W*W' inv(xVi.V).

SPM.xX.xKXs.X - Mtx - matrix of trials and betas (columns) in each trial

SPM.xX.xKXs.tol - tolerance

SPM.xX.xKXs.ds - vectors of singular values

SPM.xX.xKXs.u - u as in X u*diag(ds)*v'

SPM.xX.xKXs.v - v as in X u*diag(ds)*v'

SPM.xX.xKXs.rk - rank

SPM.xX.xKXs.oP - orthogonal projector on X

SPM.xX.xKXs.oPp - orthogonal projector on X'

SPM.xX.xKXs.ups - space in which this one is embedded

SPM.xX.xKXs.sus - subspace

SPM.xX.pKX - pseudoinverse of K*W*X, computed by spm_sp

SPM.xX.Bcov - xX.pKX*xX.V*xX.pKX - variance-covariance matrix of parameter estimates (when multiplied by the voxel-specific hyperparameter ResMS of the parameter estimates (ResSS/xX.trRV ResMS) )

SPM.xX.trRV - trace of R*V

SPM.xX.trRVRV - trace of RVRV

SPM.xX.erdf - effective residual degrees of freedom (trRV^2/trRVRV)

SPM.xX.nKX - design matrix (xX.xKXs.X) scaled for display (see spm_DesMtx('sca',... for details) SPM.xX.sF - cellstr of factor names (columns in SPM.xX.I, i think) SPM.xX.D - struct, design definition SPM.xX.xVi - correlation constraints (see non-sphericity below) SPM.xC - struct. array of covariate info

### header info

### SPM.P - a matrix of filenames

SPM.V - a vector of structures containing image volume information.

SPM.V.fname - the filename of the image.

SPM.V.dim - the x, y and z dimensions of the volume

SPM.V.dt - A 1x2 array. First element is datatype (see spm_type). The second is 1 or 0 depending on the endian-ness.

SPM.V.mat- a 4x4 affine transformation matrix mapping from voxel coordinates to real world coordinates.

SPM.V.pinfo - plane info for each plane of the volume.

SPM.V.pinfo(1,:) - scale for each plane

SPM.V.pinfo(2,:) - offset for each plane The true voxel intensities of the jth image are given by: val*V.pinfo(1,j) + V.pinfo(2,j)

SPM.V.pinfo(3,:) - offset into image (in bytes).If the size of pinfo is 3x1, then the volume is assumed to be contiguous and each plane has the same scalefactor and offset.

### structure describing intrinsic temporal non-sphericity

### SPM.xVi.I - typically the same as SPM.xX.I SPM.xVi.h - hyperparameters

SPM.xVi.V xVi.h(1)*xVi.Vi{1} + ...

SPM.xVi.Cy - spatially whitened

SPM.xVi.CY - <(Y -

SPM.xVi.Vi - array of non-sphericity components

- defaults to {speye(size(xX.X,1))} - i.ii.d.
- specifying a cell array of contraints ((Qi)
- These contraints invoke spm_reml to estimate hyperparameters assuming V is constant over voxels that provide a high precise estimate of xX.V

SPM.xX.V - Optional non-sphericity matrix. CCov(e)sigma^2*V.

- If not specified spm_spm will compute this using a 1st pass to identify signifcant voxels over which to estimate V. A 2nd pass is then used to re-estimate the parameters with WLS and save the ML estimates (unless xX.W is already specified)

### filtering information

### SPM.K - filter matrix or filtered structure:

- SPM.K(s) - struct array containing partition-specific specifications
- SPM.K(s).RT - observation interval in seconds
- SPM.K(s).row - row of Y constituting block/partitions
- SPM.K(s).HParam - cut-off period in seconds
- SPM.K(s).X0 - low frequencies to be removed (DCT)
- SPM.Y - filtered data matrix

### masking information

### SPM.xM - Structure containing masking information, or a simple column vector of thresholds corresponding to the images in VY.

SPM.xM.T - [n x 1 double] - Masking index

SPM.xM.TH - nVar x nScan matrix of analysis thresholds, one per image

SPM.xM.I - Implicit masking (0 --> none; 1 --> implicit zero/NaN mask)

SPM.xM.VM - struct array of mapped explicit mask image volumes

SPM.xM.xs - [1x1 struct] cellstr description

### design information (self-explanatory names, for once)

### SPM.xsDes.Basis_functions - type of basis function

SPM.xsDes.Number_of_sessions

SPM.xsDes.Trials_per_session

SPM.xsDes.Interscan_interval

SPM.xsDes.High_pass_Filter

SPM.xsDes.Global_calculation

SPM.xsDes.Grand_mean_scaling

SPM.xsDes.Global_normalisation

### details on scannerdata (e.g. smoothness)

### SPM.xVol - structure containing details of volume analyzed

SPM.xVol.M- 4x4 voxel --> mm transformation matrix

SPM.xVol.iM - 4x4 mm --> voxel transformation matrix

SPM.xVol.DIM - image dimensions - column vector (in voxels)

SPM.xVol.XYZ - 3 x S vector of in-mask voxel coordinates

SPM.xVol.S- Lebesgue measure or volume (in voxels)

SPM.xVol.R- vector of resel counts (in resels)

SPM.xVol.FWHM - Smoothness of components - FWHM, (in voxels)

### info on beta files:

### SPM.Vbeta - struct array of beta image handles

SPM.Vbeta.fname - beta img file names

SPM.Vbeta.descrip - names for each beta file

### info on variance of the error

### SPM.VResMS - file struct of ResMS image handle

SPM.VResMS.fname - variance of error file name

### info on mask

### SPM.VM - file struct of Mask image handle

SPM.VM.fname - name of mask img file

### contrast details (added after running contrasts)

### SPM.xCon - Contrast definitions structure array

- (see also spm_FcUtil.m for structure, rules &handling)

SPM.xCon.STAT - Statistic indicator character ('T', 'F' or 'P')

SPM.xCon.c - Contrast weights (column vector contrasts)

SPM.xCon.X0 - Reduced design matrix data (spans design space under Ho)

- Stored as coordinates in the orthogonal basis of xX.X from spm_sp
- (Matrix in SPM99b)
- Extract using X0 spm_FcUtil('X0',...

- If by columns for reduced design matrix then iX0 contains the column indices.
- Otherwise, it's a string containing the spm_FcUtil 'Set' action: Usually one of {'c','c+','X0'} defines the indices of the columns that will not be tested. Can be empty.

- Stored as coordinates in the orthogonal basis of xX.X from spm_sp (Matrix in SPM99b) Extract using X1o spm_FcUtil('X1o',...

- Or effect-size threshold for Posterior probability

SPM.xCon.Vspm - Name of SPM image

Hi, I want to create a SPM.mat file to create a model to compare.

ReplyDeleteI have already the time series form a DCM.mat file

Thank ypu

Where the time-series sotered in a DCM.mat file so that I can fetch it out for other purposes/techniques ? Thank you

ReplyDeleteHey there,

DeleteI haven't done DCM yet, so I can't say. Possibly sometime in the future, but until then, your best bet is checking the SPM listserv.

Best,

-Andy

Hi, I was wondering if this *.mat file also stores information on the fixation conditions? I am specifically interested in the onsets and durations of the fiction conditions. If yes, could you point me towards the right fields to access? Right now I can get all the condition names from 'SPM.Sess.U fields and sub-fields but nothing about the fixation conditions. Thanks!

ReplyDeleteHey there,

DeleteYou would need to model them explicitly, i.e. enter onset times and durations each time there was a fixation. Anything that isn't modeled explicitly is considered part of the implicit baseline.

-Andy

Hi Andy!

ReplyDeleteI learnt so much from your blog and its helping my research a lot so thank you!

I have another question for you. After my SPM analysis I am ready to see my results by uploading the SPM.mat file. Is there a way to extract the coordinates, the corresponding time series and maybe the fitting model of ALL the activated voxels (after inserting the threshold for the p-value)? I know that I could get the time series by looking at the raw BOLD fMRI signal, but I would like to work with the time series that SPM uses after generating the design matrix and after defining the contrast. If I do plot -> fitted and adjusted response -> define the contrast -> plot against scan or time this plots me what I want for a certain voxel but how do I put this information in a txt file?

Thank you again for your help

-Jess

Hi Jess,

DeleteYou can get the location of each voxel (in MNI coordinates, assuming you've warped to MNI space) by typing xSPM.XYZmm.

Unfortunately, I don't know how to extract the fitted time series across all the voxels. I've seen scripts for extracting the PSTH from individual voxels; maybe it can be adapted for your needs: https://www.jiscmail.ac.uk/cgi-bin/webadmin?A2=ind1611&L=spm&P=R92577&1=spm&9=A&J=on&d=No+Match%3BMatch%3BMatches&z=4

-Andy

Hi Andy,

ReplyDeleteI'm using code to design, estimate and create contrasts for a matrix that is modified. The batch works perfectly designing and estimating the matrix, but when it comes time to create the contrasts for it, matlab spits out the following error:

Error using spm_FcUtil (line 209)

not contrast dim. in spm_FcUtil c

Error in make_consVC (line 48)

SPMest.xCon =

spm_FcUtil('Set',cname{il},'T','c',cons{il}',SPMest.xX.xKXs);

Error in spm_batchTimecourse (line 218)

make_consVC(sub, 1, gwd, blocks, nblocks, nrois, roi_name, TR,

incmoves,timecourseModel, resultsfolder);

I'm guessing it's something quite simple to fix, but I don't even know where to begin. Any suggestion would be great.

Many thanks

Hi Anrew,

ReplyDeleteI done 1st level specification and spm create spm.mat file but estimation did not run. Error is that

Running 'Model estimation'

SPM12: spm_spm (v6842) 09:31:47 - 23/08/2017

========================================================================

SPM12: spm_est_non_sphericity (v6827) 09:31:48 - 23/08/2017

========================================================================

Chunk 2/2 : ...done

Failed 'Model estimation'

Error using spm_est_non_sphericity (line 208)

Please check your data: There are no significant voxels.

In file "C:\Users\Taji zewi\Desktop\matlab\spm12\spm12\spm_est_non_sphericity.m" (v6827), function "spm_est_non_sphericity" at line 208.

In file "C:\Users\Taji zewi\Desktop\matlab\spm12\spm12\spm_spm.m" (v6842), function "spm_spm" at line 431.

In file "C:\Users\Taji zewi\Desktop\matlab\spm12\spm12\config\spm_run_fmri_est.m" (v5809), function "spm_run_fmri_est" at line 33.

The following modules did not run:

Failed: Model estimation

I'm guessing each voxel not same orientation but when try to correction each fmri they comeout .mat file

Any suggestions fixing this error?

Thank you again for your help

-Bermal

This a a great list!

ReplyDeleteDo you also know where to find the information on design orthogonality?

Thanks, Marieke

Hey Marieke,

DeleteI don't know where that is in the SPM.mat file (though you could probably find it with a little digging); however, you can get it through the GUI. Click on Review, then Design -> Design Orthogonality. You will see a covariance matrix, with darker colors representing higher correlation between the regressors. If you right click on the design matrix, it will return the correlation matrix numbers to the Matlab command line.

Best,

-Andy