• Swe
• UserGuide

Using swe for parametric inference

A typical simple call to swe for parametric inference uses the following syntax:

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image>

design.mat, design.con and design.sub are text files containing the design matrix, the list of t-contrasts required and some information about the subjects, respectively; they follow the same format as generated by FEAT and used in randomise. Note that, per default, the call above will output nothing. Any type of outputs must be requested by using specific options (see Specifying the outputs of swe).

Using swe for non-parametric inference

A typical simple call to swe for non-parametric inference uses the following syntax:

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --wb -n 999

The non-parametric inference is enabled by adding the option --wb and is based on a Wild Bootstrap procedure. The -n 999 option tells swe to generate 999 bootstraps of the data when building up the null distribution to test against (it is important to note that this number does not include the original data, which is also used to compute the non-parametric p-values). Note that, per default, the call above will output nothing. Any type of outputs must be requested by using specific options (see Specifying the outputs of swe).

Using the modified Sandwich Estimator

A typical call of swe using the modified version of the Sandwich Estimator uses the following syntax:

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --modified

Per default, swe is using the classic Sandwich Estimator (SwE) that allows full heteroskadisticity between subjects (i.e. it allows the subject covariance matrices to vary across subjects). While this is a nice feature of this estimator, it is unfortunately challenging to accurately estimate the effective number of degrees of freedom (edf) used in the statistical tests when using this version of the Sandwich Estimator. More precisely, with the classic Sandwich Estimator, swe tends to underestimate the edf, which, in turn, tends to penalise the power of the tests. A way around this issue is to use a modified version of the Sandwich Estimator that assumes that the subjects can be classified into homogeneous groups of subjects, in each of which, the subjects share a common subject covariance matrix. This allows to pool information across several subjects to get less variable estimates of the subject covariance matrices. This, in turn, improves the estimation of the edfs, consequently yielding more powerful tests. This modified version of the Sandwich Estimator can be enabled in swe by using the --modified option and by adding some additional subject information in the design.sub file (see Specification of design.sub for the modified Sandwich Estimator).

Specifying the outputs of swe

Per default, swe does not output anything and your swe call should great you with a warning message like "Warning! No relevant output options selected. Exiting.". Each type of outputs must be requested by adding a specific option to the swecall. Below, we summarise the different types of outputs that are currently available with swe.

Voxel-wise uncorrected p-values

To output voxel-wise uncorrected p-values, it suffices to add the option --uncorrp to the swe call. For example,

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --uncorrp

or

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --wb -n 999 --uncorrp

The voxel-wise uncorrected p-values will be outputted as images labelled <output_rootname>_vox_p_[tf]stat*.nii.gz or <output_rootname>_vox_lp_[tf]stat*.nii.gz (if the option --logp was also used). If the option --wb was used, the p-values will correspond to non-parametric voxel-wise uncorrected p-values. Otherwise, they will correspond to parametric voxel-wise uncorrected p-values based on the parametric test labelled Test III in Guillaume (2015; see Section 3.2.4).

Non-parametric voxel-wise FWER-corrected p-values

To output non-parametric voxel-wise Family-Wise Error Rate (FWER) corrected p-values, it is needed to add the option --corrp or -x to the swe call. For example,

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --wb -n 999 --corrp

or

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --wb -n 999 -x

The non-parametric voxel-wise FWER-corrected p-values will be outputted as images labelled <output_rootname>_vox_corrp_[tf]stat*.nii.gz or <output_rootname>_vox_lcorrp_[tf]stat*.nii.gz (if the option --logp was also used). This option is only useful for non-parametric inference i.e. when the option --wb is also used. If this option is used when parametric inference is considered (i.e. without the --wb option), it will have no effect on the swe call. Internally, these p-values are computed based on the distribution of the maximum equivalent parametric Normal or chi^2 score for each contrast (based on the parametric test labelled Test III in Guillaume (2015; see Section 3.2.4)).

Non-parametric cluster-extent FWER-corrected p-values

To conduct a cluster-extent based inference, it is needed to add the option -c <thresh> for t-contrasts and -F <threshold> for f-contrasts to the swe call. For example,

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --wb -n 999 -c 0.001 -F 0.001

would output the cluster extents of each contrast obtained after using a cluster-forming parametric uncorrected p-value threshold of 0.001 (based on Test III in Guillaume (2015; see Section 3.2.4)) saved as images labelled <output_rootname>_clustere_[tf]stat*.nii.gz and the corresponding non-parametric cluster-extent FWER-corrected p-values saved as images labelled <output_rootname>_clustere_corrp_[tf]stat*.nii.gz or <output_rootname>_clustere_lcorrp_[tf]stat*.nii.gz (if the option --logp was also used).

Non-parametric cluster-mass FWER-corrected p-values

To conduct a cluster-mass based inference, it is needed to add the option -C <thresh> for t-contrasts and -S <threshold> for f-contrasts to the swe call. For example,

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --wb -n 999 -C 0.001 -S 0.001

would output the cluster mass statistics of each contrast obtained after using a cluster-forming parametric uncorrected p-value threshold of 0.001 (based on Test III in Guillaume (2015; see Section 3.2.4)) saved as images labelled <output_rootname>_clusterm_[tf]stat*.nii.gz and the corresponding non-parametric cluster-mass FWER-corrected p-values saved as images labelled <output_rootname>_clusterm_corrp_[tf]stat*.nii.gz or <output_rootname>_clusterm_lcorrp_[tf]stat*.nii.gz (if the option --logp was also used).

Non-parametric Threshold-Free Cluster Enhancement (TFCE) p-values

To output non-parametric Threshold-Free Cluster Enhancement (TFCE) p-values, it suffices to add the option -T to the swe call. For example,

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --wb -n 999 -T

However, currently, the call above will not output anything unless you also request voxel-wise inference through --corrp, -x or --uncorrp. The latter behaviour was not initially intended and is likely to change in a future release of swe. Thus, to you currently get TFCE p-values, it is needed to use a call like

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --wb -n 999 -T --uncorrp

Currently, this will enable the output of the TFCE statistics, the non-parametric TFCE uncorrected p-values and the non-parametric TFCE FWER-corrected p-values (this behaviour may also change in the future). The TFCE statistics will be outputted as images labelled <output_rootname>_tfce_[tf]stat*.nii.gz, the non-parametric TFCE uncorrected p-values will be outputted as images labelled <output_rootname>_tfce_p_[tf]stat*.nii.gz or <output_rootname>_tfce_lp_[tf]stat*.nii.gz (if the option --logp was also used) and the non-parametric TFCE FWER-corrected p-values will be outputted as images labelled <output_rootname>_tfce_corrp_[tf]stat*.nii.gz or <output_rootname>_tfce_lcorrp_[tf]stat*.nii.gz (if the option --logp was also used).

PEs, COPEs and VARCOPEs

It is possible to additionally output the parameter estimates (PEs), the contrasts of the parameter estimates (COPEs) and the variances of the contrasts of the parameter estimates (VARCOPEs) by adding the option --glm_output to the swe call. For example,

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --wb -n 999 --uncorrp --glm_output

would notably output the parameter estimates saved as an image labelled <output_rootname>_glm_pe.nii.gz, the contrasts of the parameter estimates saved as images labelled <output_rootname>_glm_cope_[tf]stat*.nii.gz and the variances of the contrasts of the parameter estimates saved as images labelled <output_rootname>_glm_varcope_[tf]stat*.nii.gz.

Raw voxel-wise statistics

The raw voxel-wise t- of f-statistic images can be obtained using the option -R or --raw. For example,

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -f design.fts -s design.sub -m <mask_image> -R

The raw statistics will be saved as images labelled <output_rootname>_tstat*.nii.gz for t-contrasts and <output_rootname>_fstat*.nii.gz for f-contrasts.

Equivalent voxel-wise statistics

The equivalent voxel-wise normal- or chi^2-statistic images can be obtained using the option -E or --equivalent. For example,

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -f design.fts -s design.sub -m <mask_image> -E

These statistics are obtained using a parametric transformation of the raw t- of f-statistics into equivalent normal- or chi^2-statistics, respectively, based on the parametric test labelled Test III in Guillaume (2015; see Section 3.2.4) and will be saved as images labelled <output_rootname>_z_tstat*.nii.gz for t-contrasts and <output_rootname>_x_fstat*.nii.gz for f-contrasts.

Effective numbers of degrees of freedom

The effective numbers of degrees of freedom estimated according to the parametric test labelled Test III in Guillaume (2015; see Section 3.2.4) can be also obtained by using the option -R or --dof. For example,

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -f design.fts -s design.sub -m <mask_image> --uncorrp -R

would output the effective numbers of degrees of freedom saved as images labelled <output_rootname>_dof_[tf]stat*.nii.gz. It is worth noting that using this output option alone does not currently output these images. It is currently necessary to combined this option with other output options to output them (this should be fixed in a future release).

Maximum statistic null distributions

When conducting a non-parametric analysis (i.e. when using the option --wb) and when a FWER-corrected inference is requested (i.e. when using at least one of the following options: -x, -T, -c <thresh>, -C <thresh>, -F <thresh> or -S <thresh>), swe can also output, for each contrast and type of FWER-corrected inference, a text file that contains the maximum statistic of interest for each bootstrap by adding the option -N to the swe call. For example,

swe -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -s design.sub -m <mask_image> --wb -n 999 -xN

would notably output some text files labelled <output_rootname>_vox_corrp_[tf]stat*.txt. The first entry in each of these files would correspond to the maximum statistics in the original equivalent parametric normal- or chi^{2-statistic images and the other entries would correspond to the maximum normal- or chi}2-statistic observed for each of the 999 bootstraps requested.

Specification of the subject information file: design.sub

swe requires the specification of a file containing subject information using the option -s design.sub. Its specification is not the same for the classic SwE and the modified SwE and their specification is separately described in the two subsections below:

Specification of design.sub for the classic Sandwich Estimator

When the classic SwE is used (default version), the contents of design.sub should contains a single column of integer values indicating to which subject each scan in <4D_input_data> belongs to. Below is an example of the content of such a file in a fictive study with 12 subjects and a maximum of 3 visits per subject (24 scans in total):

/NumWaves       1
/NumPoints      24
/Matrix
1
2
3
4
5
6
7
8
9
10
3
5
6
7
9
10
11
12
2
4
6
8
9
11 

In this example, swe will treat the 10th and 16th scans as belonging both to the 10th subject.

Specification of design.sub for the modified Sandwich Estimator

When using the modified SwE (option --modified), the file design.sub must contain more information than with the classic SwE. It must contains 3 columns. The first column must contain integer values indicating to which subject each scan in <4D_input_data> belongs to. The second column must contains integer values indicating to which visit (or repeated measures) category each scan belongs to and the third column must contains integer values indicating to which homogeneous group each subject belongs to. Below is an example of the content of such a file in a fictive study with 12 subjects, three visit categories and two homogeneous groups for a total of 24 scans:

/NumWaves       3
/NumPoints      24
/Matrix
     1     1     1
     2     1     1
     3     1     1
     4     1     1
     5     1     1
     6     1     1
     7     1     2
     8     1     2
     9     1     2
    10     1     2
     3     2     1
     5     2     1
     6     2     1
     7     2     2
     9     2     2
    10     2     2
    11     2     2
    12     2     2
     2     3     1
     4     3     1
     6     3     1
     8     3     2
     9     3     2
    11     3     2

For example, from this file, the toolbox will infer that the last scan belongs to Subject 11 and corresponds to the third visit (or repeated measures) category of the second homogeneous group.

Specification of the design matrix with swe

The design matrix is specified using the option -d design.mat, where design.mat is a vest file containing the design matrix. It is important to note that subject indicator variables must not be added with swe. These indicator variables are often added to an OLS model to account for the correlation between measures from the same subject. This is only valid if the within-subject covariance structure is common for all subjects and is compound symmetric, a state of all equal variances and all equal covariances. With more than two measures per subject, this assumption is unlikely to hold. With two measures per subject, it is more likely to hold provided that there is no heteroskedasticity between and within subjects (i.e. the variance of each measure is the same between and within-subject). The latter may not be the case because the variance in one group of subjects (the patient group) is different from the variance in another group of subjects (e.g., the control group) or because the variance may vary with time (e.g., the variance may increase after taking a drug) or across conditions (the variance may vary across fMRI tasks). swe models the within-subject covariance structure in a totally different way and thus does not need these subject indicator variables. In fact, adding them with swe would cause an overfitting of the within-subject covariances and thus would likely yield very bad results. An advantage of not adding these subject indicator variables with swe is that pure between-subject covariates, such as gender, can easily be added to the design matrix.

Specification of covariates varying within and between subjects

One should be very careful when adding a covariate that varies within and between subjects. It is actually recommended to split them into two components, one representing the pure between-subject component and the other one representing the pure within-subject component. There might be different way to achieve this splitting. One of them is to extract, for each subject, the average of the covariate and create a between-subject covariate with these average values (in general, it is also recommended to centre this resulting covariate). The within-subject covariate can then be created as the variation around the within-subject averages by simply subtracting the obtained non-centred between-subject covariate from the original covariate (by construction, this covariate is already centred). Very often, the effects of these two covariates can be different. One of the reason for this is due to the fact that they are likely to be affected differently by confound variables.

Format of p-value image outputs

Per default, the p-value images are saved as (1 - p-value) images (like in randomise). Therefore, more a value in the p-value images is close to 1, more it is significant. To threshold the images at 5% significance, the output image needs to be thresholded at 1-0.05 = 0.95. One issue with this format is that it is very difficult to visually differentiate very small p-values. For example, a p-value of 10^-10 and another one of 10^-11 would be represented by the values 1-10^-10 and 1-10^-11, respectively, which is is almost impossible to distinguish visually on a colour scale between 0 and 1. A more convenient way to represent very small p-values is to use a -log10(p-value) transformation instead of a (1 - p-value) transformation. Indeed, in the example above, the p-values of 10^-10 and 10^-11 would be represented by the transformed values -log10(10^-10) = 10 and -log10(10^-11) = 11, which can be more easily differentiated on an image. This format for saving the p-values can be enabled in swe by using the option --logp. The thresholding of these images must account for this transformation and, for example, thresholding at 1% significance can be done by thresholding the images with the value -log10(0.01) = 2.