SwE: Manual
Sandwich Estimator Toolbox for Longitudinal & Repeated Measures Data
A toolbox for SPM By Bryan Guillaume & Thomas Nichols 
This page...
News
Introduction
Manual
FMRI worked example
Download
References
Contact


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:
 Data & design setup (
swe_design )
 Computation of the model parameters (
swe_cp )
 Postprocessing & 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 postprocessing & 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 SPM12 must be previously installed and launched at least once. To install and launch the SwE toolbox:
 Unzip the
SwE.zip
file into the SPM toolboxes folder (i.e. {path to spm}/toolbox/
).
 Start Matlab and run SPM.
 In SPM navigate click on the "Batch" menu and select "SPM" from the Toolbar at the top of the Batch window. Under "Tools" In the drop down menu the 3 menu items for SwE should now be available.
Alternatively, to run the SwE toolbox in standalone mode, do the following:
 Unzip the
SwE.zip
file into the SPM toolboxes folder (i.e. {path to spm}/toolbox/
).
 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
 Launch the SwE toolbox by typing
swe
in the command window and the following GUI should appear:
This 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 "Specify Model" (see image below).
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/(Np)) 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 e_{ik}/sqrt(1h_{ik}) are used to compute the SwE, where e_{ik} corresponds to the residuals of subject i at visit category k, and h_{ik} is the diagonal element of the hat matrix H=X’(X’X)^{1}X corresponding to the residual e_{ik}.
 Type 3: The adjusted residuals e_{ik}/(1h_{ik}) 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 subdesign matrices such that their sets of allzero 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 subdesign matrices involved in the contrast tested and then naïvely estimates the degrees of freedom by the number of subject present in the involved subdesign matrices minus the number of nonzero pure between covariates present in the involved subdesign 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. In this setting, the entire design matrix must be specified by adding covariates one by one.
 Multiple Covariates:
 Allow the construction of the design matrix by entering a
`.txt`/`.mat`
file containing predefined covariates.
 Masking:
 NonParametric Wild Bootstrap:
 Select whether to do a NonParametric Wild Bootstrap (options are "Yes" or "No"). If "Yes" is selected, the following fields must be filled in:

Small sample adjustments:
 Small sample adjustment applied to the residuals before wild bootstrap resampling. The default of "type C2" is recommended.

Number of Bootstraps:
 This sets the number of bootstraps (nB). This will notably set the number of possible FWERcorrected pvalues to nB+1 and set the minimum possible FWERcorrected pvalue to 1/(nB+1).

Type of SwE:
 This offers a choice of unrestricted and restricted SwE respectively. An unrestricted SwE is obtained using the residuals of an unrestricted model (not imposing the null hypothesis), whilst a restricted SwE is obtained using a restricted model. An unrestricted SwE is the recommended default.

Statistic Type:
 The statistic type and contrast to be used when thresholding.

Inference type:

Voxelwise Inference: This will calculate voxelwise FWE p values using a bootstrap. If selected, no additional input is required.

Clusterwise Inference: This will calculate voxelwise and clusterwise FWE p values using a bootstrap. If selected, a cluster forming threshold will be required and a surface mask will be required if the input is surface data.

TFCE Inference: This will calculate voxelwise and TFCE FWE p values and TFCE uncorrected P values using a bootstrap. If selected, TFCE E and H values will be required.
 Global calculation:
 Global normalisation:
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.
Postprocessing & display of results
Once the computation is done, press the "Results" button of the SwE GUI and select the appropriate SwE.mat
file. For a parametric analysis, the toolbox should then open a SwE contrast manager allowing the test of several contrasts. For a wild bootstrap analysis, the toolbox will display the positive contrast which was computed.
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 Zscore or 1degreeoffreedom chisquared image are displayed instead of the traditional tscore or Fscore image (note that, for each parametric contrast, the t or Fscore 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 for parametric inference.
A full list of files output files, alongside a brief description of each file are given in the tables below:
Parametric Voxelwise analyses
For parametric voxelwise analyses run on input given as '.mat' files, the below files are output.
Filename 
Description 
swe_vox_mask.mat 
This is the mask used during the analysis. (In previous versions of the toolbox this map was known as mask.mat .) 
swe_vox_beta_bb.mat 
This the the beta map for this analyis. (In previous versions of the toolbox this map was known as beta.mat .) 
swe_vox_cov.mat 
This is the covariance map for the beta values given in swe_vox_beta_bb.mat . (In previous versions of the toolbox this map was known as cov_beta.mat .) 
swe_vox_cov_vv.mat 
This is the covariance map for between visits. (In previous versions of the toolbox this map was known as cov_vis.mat .) 
swe_vox_cov_g_bb.mat 
This contains the between beta covariance maps for each group. (In previous versions of the toolbox this map was known as cov_beta_g.mat .) 
swe_vox_{TF}stat_c{c#}.mat 
This is the voxelwise parametric statistic map (T or F) for contrast {c#} . (In previous versions of the toolbox this map was not recorded.) 
swe_vox_{zTxF}stat_c{c#}.mat 
This is the voxelwise parametric equivalent statistic map (Z or 1DF Chisquared) for contrast {c#} . (In previous versions of the toolbox this map was known as score.mat .) 
swe_vox_{TF}stat_lp_c{c#} 
This is the log10 map of the voxelwise uncorrected P values for contrast {c#} . (In previous versions of the toolbox this map was known as spmUncP_{#}.mat .) 
swe_vox_edf_c{c#}.mat 
This is the error degrees of freedom map for contrast {c#} . (In previous versions of the toolbox this map was known as edf_{c#}.mat .) 
swe_vox_beta_c{c#}.mat 
This is the beta map for contrast {c#} . (In previous versions of the toolbox this map was known as con_{c#}.mat .) 
For parametric analyses run on input given as '.img' or '.nii' files, the below files are output.
Filename 
Description 
swe_vox_mask.nii 
This is the mask used during the analysis. (In previous versions of the toolbox this map was known as mask.nii .) 
swe_vox_beta_b{b#}.nii 
This the the {b#} th beta map for this analyis. (In previous versions of the toolbox this map was known as beta_{b#}.nii .) 
swe_vox_resid_y{y#}.nii 
This is the parametric residual map calculated for scan {y#} . (In previous versions of the toolbox this map was known as ResI_{y#}.nii .) 
swe_vox_cov_b{b1#}_b{b2#}.nii 
This is the covariance map between beta {b1#} and beta {b2#} . (In previous versions of the toolbox this map was known as cov_beta_{b1#}_{b2#}.nii .) 
swe_vox_cov_g{g#}_b{b1#}_b{b2#}.nii 
This is the covariance map for group {#g} between beta {#b1} and beta {#b2} . (In previous versions of the toolbox this map was known as cov_beta_g_{g#}_{b1#}_{b2#}.nii .) 
swe_vox_cov_g{g#}_v{v1#}_v{v2#}.nii 
This is the covariance map for group {#g} between visit {#v1} and visit {#v2} . (In previous versions of the toolbox this map was known as cov_vis_{g#}_{v1#}_{v2#}.nii .) 
swe_vox_edf_c{c#}.nii 
This is the error degrees of freedom map for contrast {c#} . (In previous versions of the toolbox this map was known as edf_{c#}.nii .) 
swe_vox_{TF}stat_lp_c{c#}.nii 
This is the log10 map of the voxelwise uncorrected P values for contrast {c#} . (In previous versions of the toolbox this map was known as spmUncP_{c#}.nii .) 
swe_vox_{TF}stat_c{c#}.nii 
This is the voxelwise parametric statistic map (T or F) for contrast {c#} . (In previous versions of the toolbox this map was known as spm?_{c#}.nii .) 
swe_vox_{zTxF}stat_c{c#}.nii 
This is the voxelwise parametric equivalent statistic map (Z or 1DF ChiSquared) for contrast {c#} . (In previous versions of the toolbox this map was known as score.nii .) 
swe_vox_beta_c{c#}.nii 
This is the beta map for contrast {c#} . (In previous versions of the toolbox this map was known as con_{c#}.nii .) 
NonParametric Clusterwise analyses
For nonparametric clusterwise analyses run on input given as '.mat' files, the below files are output.
Filename 
Description 
swe_vox_mask.mat 
This is the mask used during the analysis. (In previous versions of the toolbox this map was known as mask.mat .) 
swe_vox_beta_bb.mat 
This is the beta map. (In previous versions of the toolbox this map was known as beta.mat .) 
swe_vox_{TF}stat_c{c#}.mat 
This is the voxelwise parametric statistic map (T or F) for contrast {c#} . (In previous versions of the toolbox this map was not recorded.) 
swe_vox_{zTxF}stat_c{c#}.mat 
This is the voxelwise parametric equivalent statistic map (Z or 1DF ChiSquared) for contrast {c#} . (In previous versions of the toolbox this map was known as score.mat for {c#}=001 .) 
swe_vox_{zTxF}statWB_c{c#}.mat 
This is the voxelwise nonparametric equivalent statistic map (Z or 1DF ChiSquared) for contrast {c#} , derived from the nonparametric uncorrected P values in swe_vox_{TF}stat_lpWB_c{c#}.mat . (In previous versions of the toolbox this map was not recorded.) 
swe_vox_{TF}stat_lpWB_c{c#}.mat 
This is the log10 map of the voxelwise uncorrected P values for contrast {c#} . (In previous versions of the toolbox this map was known as luncP_{pn}.mat *.) 
swe_vox_{TF}stat_lpFWEWB_c{c#}.mat 
This is the log10 map of the voxelwise bootstrapcalculated FWE P values for contrast {c#} . (In previous versions of the toolbox this map was known as lfwerP_{pn}.mat *.) 
swe_vox_{TF}stat_lpFDRWB_c{c#}.mat 
This is the log10 map of the voxelwise bootstrapcalculated FDR P values for contrast {c#} . (In previous versions of the toolbox this map was known as lfdrP_{pn}.mat *.) 
swe_clustere_{TF}stat_lpFWEWB_c{c#}.mat 
This is the log10 map of the clusterwise bootstrapcalculated FWE P values for contrast {c#} . (In previous versions of the toolbox this map was known as lclusterFwerP_{pn}_perElement.mat .) 
swe_vox_resid_y{y#}.mat ✝ 
These are the wildbootstrap generated residuals obtained for scan {y#} . (In previous versions of the toolbox this map was known as ResWB_{y#}.mat .) 
swe_vox_fit_y{y#}.mat ✝ 
These are the fitted values obtained for scan {y#} calculated using the wildbootstrap generated residuals given in swe_vox_resid_y{y#}.mat . (In previous versions of the toolbox this map was known as YfittedWB_{y#}.mat .) 
For nonparametric clusterwise analyses run on input given as '.img' or '.nii' files, the below files are output.
Filename 
Description 
swe_vox_mask.nii 
This is the mask used during the analysis. (In previous versions of the toolbox this map was known as mask.nii .) 
swe_vox_{TF}stat_c{c#}.nii 
This is the voxelwise parametric statistic map (T or F) for contrast {c#} . (In previous versions of the toolbox this map was not recorded.) 
swe_vox_{zTxF}stat_c{c#}.nii 
This is the voxelwise parametric equivalent statistic map (Z or 1DF ChiSquared) for contrast {c#} . (In previous versions of the toolbox this map was known as score.nii for {c#}=001 .) 
swe_vox_{zTxF}statWB_c{c#}.nii 
This is the voxelwise nonparametric equivalent statistic map (Z or 1DF ChiSquared) for contrast {c#} , derived from the nonparametric uncorrected P values in swe_vox_{TF}stat_lpWB_c{c#}.nii . (In previous versions of the toolbox this map was not recorded.) 
swe_vox_{TF}stat_lpWB_c{c#}.nii 
This is the log10 map of the voxelwise uncorrected P values for contrast {c#} . (In previous versions of the toolbox this map was known as lP{+}.nii *.) 
swe_vox_{TF}stat_lpFWEWB_c{c#}.nii 
This is the log10 map of the voxelwise bootstrapcalculated FWE P values for contrast {c#} . (In previous versions of the toolbox this map was known as lP_FWE{+}.nii *.) 
swe_vox_{TF}stat_lpFDRWB_c{c#}.nii 
This is the log10 map of the voxelwise bootstrapcalculated FDR P values for contrast {c#} . (In previous versions of the toolbox this map was known as lP_FDR{+}.nii *.) 
swe_clustere_{TF}stat_lpFWEWB_c{c#}.nii 
This is the log10 map of the clusterwise bootstrapcalculated FWE P values for contrast {c#} . (In previous versions of the toolbox this map was known as lP_clusterFWE{+}.nii *.) 
swe_vox_resid_y{y#}.nii ✝ 
These are the wildbootstrap generated residuals obtained for scan {y#} . (In previous versions of the toolbox this map was known as ResWB_{y#}.nii .) 
swe_vox_fit_y{y#}.nii ✝ 
These are the fitted values obtained for scan {y#} calculated using the wildbootstrap generated residuals given in swe_vox_resid_y{y#}.nii . (In previous versions of the toolbox this map was known as YfittedWB_{y#}.nii .) 
NonParametric TFCE analyses
For nonparametric TFCE analyses run on input given as '.img' or '.nii' files, the below files are output.
Filename 
Description 
swe_vox_mask.nii 
This is the mask used during the analysis. (In previous versions of the toolbox this map was known as mask.nii .) 
swe_vox_{TF}stat_c{c#}.nii 
This is the voxelwise parametric statistic map (T or F) for contrast {c#} . (In previous versions of the toolbox this map was not recorded.) 
swe_vox_{zTxF}stat_c{c#}.nii 
This is the voxelwise parametric equivalent statistic map (Z or 1DF ChiSquared) for contrast {c#} . (In previous versions of the toolbox this map was known as score.nii for {c#}=001 .) 
swe_vox_{zTxF}statWB_c{c#}.nii 
This is the voxelwise nonparametric equivalent statistic map (Z or 1DF ChiSquared) for contrast {c#} , derived from the nonparametric uncorrected P values in swe_vox_{TF}stat_lpWB_c{c#}.nii . (In previous versions of the toolbox this map was not recorded.) 
swe_vox_{TF}stat_lpWB_c{c#}.nii 
This is the log10 map of the voxelwise uncorrected P values for contrast {c#} . (In previous versions of the toolbox this map was known as lP{+}.nii *.) 
swe_vox_{TF}stat_lpFWEWB_c{c#}.nii 
This is the log10 map of the voxelwise bootstrapcalculated FWE P values for contrast {c#} . (In previous versions of the toolbox this map was known as lP_FWE{+}.nii *.) 
swe_vox_{TF}stat_lpFDRWB_c{c#}.nii 
This is the log10 map of the voxelwise bootstrapcalculated FDR P values for contrast {c#} . (In previous versions of the toolbox this map was known as lP_FDR{+}.nii *.) 
swe_tfce_c{c#}.nii 
This is the parametric TFCE statistic for contrast {c#} . 
swe_tfce_lpWB_c{c#}.nii 
This is the log10 map of the TFCE bootstrapcalculated uncorrected P values for contrast {c#} . 
swe_tfce_lpFWEWB_c{c#}.nii 
This is the log10 map of the TFCE bootstrapcalculated FWE P values for contrast {c#} . 
swe_vox_resid_y{y#}.nii ✝ 
These are the wildbootstrap generated residuals obtained for scan {y#} . (In previous versions of the toolbox this map was known as ResWB_{y#}.nii .) 
swe_vox_fit_y{y#}.nii ✝ 
These are the fitted values obtained for scan {y#} calculated using the wildbootstrap generated residuals given in swe_vox_resid_y{y#}.nii . (In previous versions of the toolbox this map was known as YfittedWB_{y#}.nii .) 
*Note: For nonparametric analyses
{c#}
is
001
for activation and
002
for deactivation. In previous versions of the toolbox these were represented with either a +/ or p/n.
✝ These maps will be removed once an analysis has been run. They will only be retained if an analysis is ended prematurely.