Skip to main content Skip to navigation

Department of Statistics

SwE Manual

The goal of this manual is to explain how to use the SwE toolbox. If something is unclear or if you think more explanations are needed, please do not hesitate to contact Bryan Guillaume or Tom Nichols. The manual will be updated accordingly. Note that an example of the use of the toolbox on a real dataset can be found here. Note that this manual does not account for the new features of the last release of the toolbox. It will be updated soon.

Toolbox overview

The SwE toolbox implements the Sandwich Estimator (SwE) method described in Guillaume et al. (in submission) allowing the analysis of longitudinal and repeated measures data in neuroimaging. An analysis with the SwE toolbox can be decomposed into three stages:

  1. Data & design setup (swe_design)
  2. Computation of the model parameters (swe_cp)
  3. Post-processing & display of results (swe_result_ui)

Each stage is handled by a separate function, callable either from the command line or the SwE GUI, as described below. Interim communication between the stages is done via SwE.mat files, similar to SPM.mat files. The setup stage (swe_design) launches the batch system and saves the configuration information in a SwE.mat. Note that the filenames of the input and created images are coded into the SwE.mat file, so moving or deleting the images may cause issues. The computation stage (swe_cp) asks you to locate a SwE.mat file, computes the model parameters and updates the SwE.mat file. Finally the post-processing & results stage (swe_result_ui) asks you to locate a SwE.mat file and launch an interface allowing you to make inferences and display the results.

Getting started

Prior to using the SwE toolbox, a version of SPM8 or SPM12 must be previously installed and launched at least once. To install and launch the SwE toolbox:

  1. Unzip the SwE.zip file into a folder of your choice (e.g., …/whatever).
  2. Start MATLAB and add the folder "SwE" into your path, either using:
    • For old MATLAB versions, File > Set Path > Add Folder
    • For recent MATLAB versions, HOME > ENVIRONMENT > Set Path > Add Folder
    • MATLAB command pathtool > Add Folder
    • MATLAB command addpath …/whatever/SwE
  3. Launch the SwE toolbox by typing swe in the command window and the following GUI should appear:swe_gui.pngThis SwE GUI has three buttons allowing to launch the three stages of an SwE analysis. Each of these stages is detailed below.

Data & design setup

To start specifying the data and design, press the button "Specify model" in the SwE GUI. This will call the SPM batch system, add the SwE tab to it and load the SwE module "Data & Design" (see image below).

SwE batch

This module contains several fields that have to be filled in:

  • Directory:
    • Select the directory where the files of the analysis will be created.
  • Scans:
    • Select all the input images. Note that the ordering is important as other variables (Groups, Visits and Subjects) must follow the same ordering.
  • SwE type:
    • Select between the classic or modified SwE. The classic SwE assumes that the subjects have all different covariance matrices. The modified SwE assumes that the subjects can be gathered into groups in which they share a common covariance matrix.
    • If the modified version is selected, a numerical vector of group categories must be specified in the ordering of the scans. It defines in which group the subjects belong and share a common covariance matrix.
    • If the modified version is selected, a numerical vector of visit (or repeated measures) categories must be specified in the ordering of the scans. For each group, the visit (or repeated measures) categories must be consistent across subjects.
    • For both versions, a small samples bias adjustment must be selected. The toolbox currently offers the choice between 4 types of adjustments:
      • Type 0: The raw residuals are used to compute the SwE (no adjustments used).
      • Type 1: The raw residuals multiplied by sqrt(N/(N-p)) are used to compute the SwE, where N is the total number of input images and p is the number of covariates in the model.
      • Type 2: The adjusted residuals eik/sqrt(1-hik) are used to compute the SwE, where eik corresponds to the residuals of subject i at visit category k, and hik is the diagonal element of the hat matrix H=X’(X’X)-1X corresponding to the residual eik.
      • Type 3: The adjusted residuals eik/(1-hik) are used to compute the SwE.
      Note that the simulations in Guillaume et al. (in submission) seems to favour the use of the "Type 3" adjustment.
    • For both versions, a degrees of freedom estimation type must be selected. Before detailing the two options offered by the toolbox, it is important to note here that some design matrices can actually be separated into sub-design matrices such that their sets of all-zero columns are pairwise disjoints. This has an important impact on the degrees of freedom of the null distribution of the test statistics used in the SwE method and is taken into account by the toolbox for two types of estimation offered by the toolbox:
      • Naïve: The toolbox first detects the inseparable sub-design matrices involved in the contrast tested and then naïvely estimates the degrees of freedom by the number of subject present in the involved sub-design matrices minus the number of non-zero pure between covariates present in the involved sub-design matrices.
      • Approx: The estimate proposed in Guillaume et al. (in submission) is used.
    Note that the simulations in Guillaume et al. (in submission) seems to show that the "Approx" option is the best option if the modified SwE is selected. Nevertheless, if the classic SwE is selected, the "Approx" option generally underestimates the degrees of freesom leading to conservative test and the option "Naïve" option may overestimate the degrees of freedom leading to liberal test. Note also that the "Approx" option requires saving a lot of images in the working directory, specifically if the classis SwE is selected, so make sure you have enough space available.
  • Subjects:
    • Enter the vector of subjects (numerical values) in the ordering of the scans.
  • Covariates:
    • Allow the construction of the design matrix by entering several covariates in the ordering of the scans. Note that the toolbox does not currently offer an automatic construction of the design matrix. The entire design matrix must be specified by adding covariates one by one.
  • Masking:
    • Similar to a SPM design.
  • Global calculation:
    • Similar to a SPM design.
  • Global normalisation:
    • Similar to a SPM design.

Once the model is specified, the SwE job can be run by pressing the green "Run Batch" button. The toolbox will then create a SwE.mat file containing all the configuration information needed for the estimation of the model parameters.

Computation of the model parameters

To start estimating the parameters of a specified model, press the button "Run model" of the SwE GUI and select the appropriate SwE.mat file. The toolbox should then compute all the estimates needed for the analysis. This may take several minutes.

Post-processing & display of results

Once the computation is done, press the "Results" button of the SwE GUI and select the appropriate SwE.mat file. The toolbox should then open a SwE contrast manager allowing the test of several contrasts. Note that the SwE interface is very similar to the interface of a classic SPM analysis and can be used in a similar way. Nevertheless, there are some differences important to note. First, as the degrees of freedom with the SwE method may vary across voxels, for each contrast, the equivalent Z-score or chi-squared-score image are displayed instead of the traditional t-score or F-score image (note that, for each contrast, the t- or F-score image is saved in the working directory alongside the degrees of freedom image). Second, as Random Field Theory inferences have not been yet validated with the SwE method, only False Discovery Rate and uncorrected inferences are currently available in the SwE toolbox.