Table of Contents

SPM2 structure


The SPM structure is a Matlab structure that contains the all the data necessary for the operation of SPM (the software). It is stored in SPM.mat files.


NB: There is some duplication among the descriptions, though I have attempted to start with more general overviews descriptions first.

Copied from spm_fmri_spm_ui.m1):

        xY: [1x1 struct] - data stucture
     nscan: [double]     - vector of scans per session
       xBF: [1x1 struct] - Basis function stucture   (see spm_fMRI_design)
      Sess: [1x1 struct] - Session stucture          (see spm_fMRI_design)
        xX: [1x1 struct] - Design matric stucture    (see spm_fMRI_design)
       xGX: [1x1 struct] - Global variate stucture
       xVi: [1x1 struct] - Non-sphericity stucture
        xM: [1x1 struct] - Masking stucture
     xsDes: [1x1 struct] - Design description stucture
              P: [n x ? char]   - filenames
             VY: [n x 1 struct] - filehandles
             RT: Repeat time
        iGXcalc: {'none'|'Scaling'} - Global normalization option    
        sGXcalc: 'mean voxel value' - Calculation method
         sGMsca: 'session specific' - Grand mean scaling
             rg: [n x 1 double]     - Global estimate
             GM: 100                - Grand mean
            gSF: [n x 1 double]     - Global scaling factor
             Vi: {[n x n sparse]..}   - covariance components
           form: {'none'|'AR(1)'} - form of non-sphericity
              T: [n x 1 double]  - Masking index
             TH: [n x 1 double]  - Threshold
              I: 0
             VM:                 - Mask filehandles
             xs: [1x1 struct]    - cellstr description

Copied from spm_spm.m2):

required fields of SPM:

xY.VY - nScan x 1 struct array of mapped image volumes
        Images must have the same orientation, voxel size and data type
      - Any scaling should have already been applied via the image handle

xX    - Structure containing design matrix information
      - Required fields are:
        xX.X      - Design matrix (raw, not temporally smoothed)   - cellstr of parameter names corresponding to columns
                    of design matrix
      - Optional fields are:
        xX.K      - cell of session-specific structures (see spm_filter)
                  - Design & data are pre-multiplied by K
                    (K*Y = K*X*beta + K*e)
                  - Note that K should not smooth across block boundaries
                  - defaults to speye(size(xX.X,1))
        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 estimtes maximum likelihood
                    i.e. W*W' = inv(xVi.V).

xVi   - structure describing intrinsic temporal non-sphericity
      - required fields are:
        xVi.Vi    - array of non-sphericity components
                  - defaults to {speye(size(xX.X,1))} - i.i.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
      - Optional fields are:
        xX.V      - Optional non-sphericity matrix.  Cov(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)

xM    - Structure containing masking information, or a simple column vector
        of thresholds corresponding to the images in VY.
      - If a structure, the required fields are:
        xM.TH - nVar x nScan matrix of analysis thresholds, one per image
        xM.I  - Implicit masking (0=>none, 1 => implicit zero/NaN mask)
        xM.VM - struct array of mapped explicit mask image volumes
		- (empty if no explicit masks)
              - Explicit mask images are >0 for valid voxels to assess.
              - Mask images can have any orientation, voxel size or data
                type. They are interpolated using nearest neighbour
                interpolation to the voxel locations of the data Y.
      - Note that voxels with constant data (i.e. the same value across
        scans) are also automatically masked out.

  The following SPM.fields are set by spm_spm (unless specified)
      xVi.V      - estimated non-sphericity trace(V) = rank(V)
      xVi.h      - hyperparameters  xVi.V = xVi.h(1)*xVi.Vi{1} + ...
      xVi.Cy     - spatially whitened <Y*Y'> (used by ReML to estimate h)
      xVi.CY     - <(Y - <Y>)*(Y - <Y>)'>    (used by spm_spm_Bayes)
      Vbeta     - struct array of beta image handles (relative)
      VResMS    - file struct of ResMS image handle  (relative)
      VM        - file struct of Mask  image handle  (relative)
      xX.W      - if not specified W*W' = inv(x.Vi.V)
      xX.V      - V matrix (K*W*Vi*W'*K') = correlations after K*W is applied
      xX.xKXs   - space structure for K*W*X, the 'filtered and whitened'
                  design matrix
                - given as spm_sp('Set',xX.K*xX.W*xX.X) - see spm_sp
      xX.pKX    - pseudoinverse of K*W*X, computed by spm_sp
      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)    )
      xX.trRV   - trace of R*V, computed efficiently by spm_SpUtil
      xX.trRVRV - trace of RVRV
      xX.erdf   - effective residual degrees of freedom (trRV^2/trRVRV)
      xX.nKX    - design matrix (xX.xKXs.X) scaled for display
                  (see spm_DesMtx('sca',... for details)
      xVol.M    - 4x4 voxel->mm transformation matrix
      xVol.iM   - 4x4 mm->voxel transformation matrix
      xVol.DIM  - image dimensions - column vector (in voxels)
      xVol.XYZ  - 3 x S vector of in-mask voxel coordinates
      xVol.S    - Lebesgue measure or volume       (in voxels)
      xVol.R    - vector of resel counts           (in resels)
      xVol.FWHM - Smoothness of components - FWHM, (in voxels)

Copied from spm_spm_ui.m3):

  xY.VY         - nScan x 1 struct array of memory mapped images
                  (see spm_vol for definition of the map structure)
  xX            - structure describing design matrix
  xX.D          - design definition structure
                  (See definition in main body of spm_spm_ui.m)
  xX.I          - nScan x 4 matrix of factor level indicators
                  I(n,i) is the level of factor i corresponding to image n
  xX.sF         - 1x4 cellstr containing the names of the four factors
                  xX.sF{i} is the name of factor i
  xX.X          - design matrix
  xX.xVi        - correlation constraints for non-spericity correction
  xX.iH         - vector of H partition (condition effects) indices,
                  identifying columns of X correspoding to H
  xX.iC         - vector of C partition (covariates of interest) indices
  xX.iB         - vector of B partition (block effects) indices
  xX.iG         - vector of G partition (nuisance variables) indices     - p x 1 cellstr of effect names corresponding to columns
                  of the design matrix
  xC            - structure array of covariate details
  xC(i).rc      - raw (as entered) i-th covariate
  xC(i).rcname  - name of this covariate (string)
  xC(i).c       - covariate as appears in design matrix (after any scaling,
                  centering of interactions)
  xC(i).cname   - cellstr containing names for effects corresponding to
                  columns of xC(i).c
  xC(i).iCC     - covariate centering option
  xC(i).iCFI    - covariate by factor interaction option
  xC(i).type    - covariate type: 1=interest, 2=nuisance, 3=global
  xC(i).cols    - columns of design matrix corresponding to xC(i).c
  xC(i).descrip - cellstr containing a description of the covariate
  xGX           - structure describing global options and values
  xGX.iGXcalc   - global calculation option used
  xGX.sGXcalc   - string describing global calculation used
  xGX.rg        - raw globals (before scaling and such like)
  xGX.iGMsca    - grand mean scaling option
  xGX.sGMsca    - string describing grand mean scaling
  xGX.GM        - value for grand mean (/proportional) scaling
  xGX.gSF       - global scaling factor (applied to xGX.rg)
  xGX.iGC       - global covariate centering option
  xGX.sGC       - string describing global covariate centering option
  xGX.gc        - center for global covariate
  xGX.iGloNorm  - Global normalisation option
  xGX.sGloNorm  - string describing global normalisation option
  xM            - structure describing masking options
  xM.T          - Threshold masking value (-Inf=>None,
                  real=>absolute, complex=>proportional (i.e. times global) )
  xM.TH         - nScan x 1 vector of analysis thresholds, one per image
  xM.I          - Implicit masking (0=>none, 1=>implicit zero/NaN mask)
  xM.VM         - struct array of explicit mask images
                  (empty if no explicit masks)
  xM.xs         - structure describing masking options
                  (format is same as for xsDes described below)
  xsDes         - structure of strings describing the design:
                  Fieldnames are essentially topic strings (use "_"'s for
                  spaces), and the field values should be strings or cellstr's
                  of information regarding that topic. spm_DesRep.m
                  uses this structure to produce a printed description
                  of the design, displaying the fieldnames (with "_"'s 
                  converted to spaces) in bold as topics, with
                  the corresponding text to the right
  SPMid         - String identifying SPM and program versions

Copied from spm_fMRI_design.m4):

 1st level
        xY: [1x1 struct] - data structure
     nscan: [1xs double] - nscan(s) = number of scans in session s
       xBF: [1x1 struct] - Basis function structure
      Sess: [1xs struct] - Session structure array
        xX: [1x1 struct] - Design matrix structure
     2nd level
            RT: - repetition time {seconds)
             T: - number of time bins per scan
            T0: - first time bin (see slice timing)
         UNITS: - 'scans'|'secs' - units in which onsets are specified
      Volterra: - 1|2 - order of [Volterra] convolution
            dt: - length of time bin {seconds}
          name: - name of basis set
        length: - support of basis set {seconds}
         order: - order of basis set
            bf: - basis set matrix 
             U: - Input structure array
             C: - User specified covariate structure
           row: - scan   indices for session s
           col: - effect indices for session s
            Fc: - F Contrast information for input-specific effects
             X: - design matrix
            iH: - vector of H partition (indicator variables) indices
            iC: - vector of C partition (covariates)       indices
            iB: - vector of B partition (block effects)       indices
            iG: - vector of G partition (nuisance variables)  indices
          name: - cellstr of names for design matrix columns
         3rd level
                dt: - time bin length {seconds}
              name: - {1 x j} cell of names for each input or cause
               ons: - (q x 1) onsets for q  trials {in UNITS}
               dur: - (q x 1) durations for trials {in UNITS}
                 P: - Parameter stucture
                 u: - (t x j) inputs or stimulus function matrix
               pst: - (1 x k) peristimulus times (seconds)
                 C: - [kx1 double] of user specified regressors
              name: - {1xk} cellstr of regressor names
                 i: - F Contrast colums for input-specific effects
              name: - F Contrast names  for input-specific effects
             4th level
                  name: - parameter name
                     P: - (q x 1) parameter matrix
                     h: - order of polynomial expansion (0 = none)
                     i: - sub-indices of U(i).u for plotting

Copied from spm_get_ons.m5):

  s  - session number (used by batch system)
  U     - (1 x n)   struct array of (n) trial-specific structures
   U(i).name   - cell of names for each input or cause
   U(i).u      - inputs or stimulus function matrix
   U(i).dt     - time bin (seconds)
   U(i).ons    - onsets    (in SPM.xBF.UNITS)
   U(i).dur    - durations (in SPM.xBF.UNITS)
   U(i).P      - parameter struct.
       U(i).P(p).name - parameter name
       U(i).P(p).P    - parameter vector
       U(i).P(p).h    - order of polynomial expansion
       U(i).P(p).i    - sub-indices of u pertaining to P

Copied from spm_getSPM.m6):

 [SPM,xSPM] = spm_getSPM;
  xSPM      - structure containing SPM, distribution & filtering details
  .swd      - SPM working directory - directory containing current SPM.mat
  .title    - title for comparison (string)
  .Z        - minimum of statistic images {filtered on u and k}
  .n        - conjunction number <= number of contrasts        
  .STAT     - distribution {Z, T, X, F or P}     
  .df       - degrees of freedom [df{interest}, df{residual}]
  .STATstr  - description string     
  .Ic       - indices of contrasts (in SPM.xCon)
  .Im       - indices of masking contrasts (in xCon)
  .pm       - p-value for masking (uncorrected)
  .Ex       - flag for exclusive or inclusive masking
  .u        - height threshold
  .k        - extent threshold {voxels}
  .XYZ      - location of voxels {voxel coords}
  .XYZmm    - location of voxels {mm}
  .S        - search Volume {voxels}
  .R        - search Volume {resels}
  .FWHM     - smoothness {voxels}     
  .M        - voxels -> mm matrix
  .iM       - mm -> voxels matrix
  .VOX      - voxel dimensions {mm} - column vector
  .DIM      - image dimensions {voxels} - column vector
  .Vspm     - Mapped statistic image(s)
  .Ps       - list of P values for voxels at SPM.xVol.XYZ (used by FDR)
  Required fields of SPM
  xVol   - structure containing details of volume analysed
  xX     - Design Matrix structure
         - (see spm_spm.m for structure)
  xCon   - Contrast definitions structure array
         - (see also spm_FcUtil.m for structure, rules & handling)
  .name  - Contrast name
  .STAT  - Statistic indicator character ('T', 'F' or 'P')
  .c     - Contrast weights (column vector contrasts)
  .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',...
  .iX0   - Indicates how contrast was specified:
           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'}
  .X1o   - Remaining design space data (X1o is orthogonal to X0)
           Stored as coordinates in the orthogonal basis of xX.X from spm_sp
           (Matrix in SPM99b)  Extract using X1o = spm_FcUtil('X1o',...
  .eidf  - Effective interest degrees of freedom (numerator df)
         - Or effect-size threshold for Posterior probability
  .Vcon  - Name of contrast (for 'T's) or ESS (for 'F's) image
  .Vspm  - Name of SPM image

Copied from spm_regions.m7):

  Y      - first scaled eigenvariate of VOI {i.e. weighted mean}
  xY     - VOI structure          - centre of VOI {mm}         - name of VOI
        xY.Ic           - contrast used to adjust data (0 - no adjustment)
        xY.Sess         - session index
        xY.def          - VOI definition
        xY.spec         - VOI definition parameters
        xY.XYZmm        - Co-ordinates of VOI voxels {mm}
        xY.y            - [whitened and filtered] voxel-wise data
        xY.u            - first eigenvariate {scaled - c.f. mean response}
        xY.v            - first eigenimage
        xY.s            - eigenvalues
        xY.X0           - [whitened] confounds (including drift terms)
1) , 2) , 3) , 4) , 5) , 6) , 7) Current as of SPM2
help/fmri_help/spm/spm2_structure.txt · Last modified: 2010/07/20 07:44 (external edit)
CC Attribution-Noncommercial-Share Alike 3.0 Unported Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0