---

USING randomise

A typical simple call to randomise uses the following syntax:

randomise -i <4D_input_data> -o <output_rootname> -d design.mat -t design.con -m <mask_image> -n 500 -D -T

design.mat and design.con are text files containing the design matrix and list of contrasts required; they follow the same format as generated by FEAT (see below for examples). The -n 500 option tells randomise to generate 500 permutations of the data when building up the null distribution to test against. The -D option tells randomise to demean the data before continuing - this is necessary if you are not modelling the mean in the design matrix. The -T option tells randomise that the test statistic that you wish to use is TFCE (threshold-free cluster enhancement - see below for more on this).

When using the demeaning option, -D, randomise will also demean the EVs in the design matrix, providing a warning if they initially had non-zero mean (and as long as this doesn't cause the matrix/contrasts to become rank deficient then this warning can be ignored).

There are two programs that make it easy to create the design matrix, contrast and exchangeability-block files design.mat / design.con / design.grp . The first is the Glm GUI which allows the specification of designs in the same way as in FEAT, and the second is a simple script to allow you to easily generate design files for the two-group unpaired t-test case, called design_ttest2.

randomise has the following thresholding/output options:

• Voxel-based thresholding, both uncorrected and corrected for multiple comparisons by using the null distribution of the max (across the image) voxelwise test statistic. Uncorrected outputs are: <output>_vox_p_tstat / <output>_vox_p_fstat. Corrected outputs are: <output>_vox_corrp_tstat / <output>_vox_corrp_fstat. To use this option, use -x.

• TFCE (Threshold-Free Cluster Enhancement) is a new method for finding "clusters" in your data without having to define clusters in a binary way. Cluster-like structures are enhanced but the image remains fundamentally voxelwise; you can use the -tfce option in fslmaths to test this on an existing stats image. See the TFCE research page for more information. The "E", "H" and neighbourhood-connectivity parameters have been optimised and should be left unchanged. These optimisations are different for different "dimensionality" of your data; for normal, 3D data (such as in an FSL-VBM analysis), you should just just the -T option, while for TBSS analyses (that is in effect on the mostly "2D" white matter skeleton), you should use the --T2 option.

• Cluster-based thresholding corrected for multiple comparisons by using the null distribution of the max (across the image) cluster size (so passé!): <output>_clustere_corrp_tstat / <output>_clustere_corrp_fstat.
  To use this option, use -c <thresh> for t contrasts and -F <thresh> for F contrasts, where the threshold is used to form supra-threshold clusters of voxels.

• Cluster-based thresholding corrected for multiple comparisons by using the null distribution of the max (across the image) cluster mass: <output>_clusterm_corrp_tstat / <output>_clusterm_corrp_fstat.
  To use this option, use -C <thresh> for t contrasts and -S <thresh> for F contrasts.

These filename extensions are summarized in table below.

"FWE-corrected" means that the family-wise error rate is controlled. If only FWE-corrected P-values less than 0.05 are accepted, the chance of one more false positives occurring over space space is no more than 5%. Equivalently, one has 95% confidence of no false positives in the image.

Note that these output images are 1-P images, where a value of 1 is therefore most significant (arranged this way to make display and thresholding convenient). Thus to "threshold at p<0.01", threshold the output images at 0.99 etc.

If your design is simply all 1s (for example, a single group of subjects) then randomise needs to work in a different way. Normally it generates random samples by randomly permuting the rows of the design; however in this case it does so by randomly inverting the sign of the 1s. In this case, then, instead of specifying design and contrast matrices on the command line, use the -1 option.

You can potentially improve the estimation of the variance that feeds into the final "t" statistic image by using the variance smoothing option -v <std> where you need to specify the spatial extent of the smoothing in mm.

Viewing and Reporting Results

When viewing the 1-p results in FSLView the min/max display range should be set to 0.95/1.0 so that values less than 0.95 (equivalent to p>0.05) are not shown. If these are corrected values (i.e. corrp) then the visible areas correspond to the statistically significant regions.

To report cluster results (size, maxima, locations, labels) you can use the cluster and atlasquery tools.

Parallelising Randomise

If you are have an SGE-capable system then a randomise job can be split in parallel with randomise_parallel which takes the same input options as the standard randomise binary and then calculates and batches an optimal number of randomise sub-tasks. The parallelisation has two stages - firstly the randomise sub-jobs are run, and then the sub-job results are combined in the final output.

Examples

One-Sample T-test

To perform a nonparametric 1-sample t-test (e.g., on COPEs created by FEAT FMRI analysis), create a 4D image of all of the images. There should be no repeated measures, i.e., there should only be one image per subject. Because this is a single group simple design you don't need a design matrix or contrasts. Just use:
randomise -i OneSamp4D -o OneSampT -1 -T
Note you do not need the -D option (as the mean is in the model), and omit the -n option, so that 5000 permutations will be performed.

If you have fewer than 20 subjects (approx. 20 DF), then you will usually see an increase in power by using variance smoothing, as in
randomise -i OneSamp4D -o OneSampT -1 -v 5 -T
which does a 5mm HWHM variance smoothing.

Note also that randomise will automatically select one-sample mode for appropriate design/contrast combinations.

Two-Sample Unpaired T-test

To perform a nonparametric 2-sample t-test, create 4D image of all of the images, with the subjects in the right order! Create appropriate design.mat and design.con files.

Once you have your design files run:
randomise -i TwoSamp4D -o TwoSampT -d design.mat -t design.con -m mask -T 

Two-Sample Unpaired T-test with nuisance variables

To perform a nonparametric 2-sample t-test in the presence of nuisance variables, create a 4D image of all of the images. Create appropriate design.mat and design.con files, where your design matrix has additional nuisance variables that are (appropriately) ignored by your contrast.

Once you have your design files the call is as before:
randomise -i TwoSamp4D -o TwoSampT -d design.mat -t design.con -m mask -T

Two-Sample Paired T-test (Paired Two-Group Difference)

We will follow the setup in the FEAT manual where we have a group of 8 subjects scanned under two different conditions, A and B. Condition A will be entered as the first 8 inputs, and condition B as the second 8 inputs, with the subjects in the same order in each case (ordering is, naturally, very important).

The design matrix (design.mat) looks like

 1 1 0 0 0 0 0 0 0 
 1 0 1 0 0 0 0 0 0
 1 0 0 1 0 0 0 0 0
 1 0 0 0 1 0 0 0 0
 1 0 0 0 0 1 0 0 0
 1 0 0 0 0 0 1 0 0
 1 0 0 0 0 0 0 1 0
 1 0 0 0 0 0 0 0 1
-1 1 0 0 0 0 0 0 0 
-1 0 1 0 0 0 0 0 0
-1 0 0 1 0 0 0 0 0 
-1 0 0 0 1 0 0 0 0
-1 0 0 0 0 1 0 0 0 
-1 0 0 0 0 0 1 0 0
-1 0 0 0 0 0 0 1 0 
-1 0 0 0 0 0 0 0 1

where the first column models the group difference, and the individual subject means are modelled by columns 2 to 9.

The t-contrast (design.con) for the group difference, A-B, is simply
1 0 0 0 0 0 0 0 0
and for B-A, just replace 1 with -1 in this contrast.

The exchangeability-block information (design.grp) can be entered via the "Group" column in the GLM Gui (see the example GLM setup here or, alternatively, it can be created independently as a simple text file). The values in this need to specify which data can be exchanged, that is, only condition A and B within the same subject (since the null hypothesis is that there is no difference between A and B, but each subject could have a different mean value and so we cannot exchange between subjects). Therefore there are eight different blocks and the file looks like

1
2
3
4
5
6
7
8
1
2
3
4
5
6
7
8

Once you have set up these design files you can run:
randomise -i PairedT4D -o PairedT -d design.mat -t design.con -e design.grp -m mask -T 

Note that a completely alternative way to do a paired analysis is to calculate the difference values within-subject initially (e.g., using fslmaths) and then do a simple one-group t-test (across subjects) on these within-subject differences.

Repeated measures ANOVA

Following the ANOVA: 1-factor 4-levels (Repeated Measures) example from the FEAT manual, assume we have 2 subjects with 1 factor at 4 levels. We therefore have eight input images and we want to test if there is any difference over the 4 levels of the factor. The design matrix looks like

1 0 1 0 0
1 0 0 1 0
1 0 0 0 1
1 0 0 0 0
0 1 1 0 0
0 1 0 1 0
0 1 0 0 1
0 1 0 0 0

where the first two columns model subject means and the 3rd through 5th column model the categorical effect (Note the different arrangement of rows relative to the FEAT example). Three t-contrasts for the categorical effect

0 0 1 0 0
0 0 0 1 0
0 0 0 0 1

are selected together into a single F-contrast

1 1 1

Modify the exchangeability-block information in design.grp to match

1
1
1
1
2
2
2
2

This will ensure that permutations will only occur within subject, respecting the repeated measures structure of the data. The number of permutations can be computed for each group, and then multiplied together to find the total number of permutations. We use the ANOVA computation for 4 levels, and hence (1+1+1+1)!/1!/1!/1!/1! = 24 possible permutations for one subject, and hence 24 × 24 = 576 total permutations. The call is then similar to the above examples:
randomise -i TwoSamp4D -o TwoSampT -d design.mat -t design.con -f design.fts -m mask -e design.grp -T

Getting Cluster and Peak Information from Randomise Output

Assuming that the best image to get the clusters and peak information from is the raw tstat image:

begin by masking this with the significant voxels from corrp:

fslmaths grot_tfce_corrp_tstat1 -thr 0.95 -bin -mul grot_tstat1 grot_thresh_tstat1

Now run cluster to extract the clusters and local maxima in several different outputs:

cluster --in=grot_thresh_tstat1 --thresh=0.0001 --oindex=grot_cluster_index --olmax=grot_lmax.txt --osize=grot_cluster_size

If the data is already in standard space (MNI152) and co-ordinate reporting is wanted in MNI (mm) values, add --mm to the end of the command.

If clusters need to be forced to be more highly split, the --thresh value can be raised to an appropriate level. Because the input image was already masked by the corrp image, regardless of the thresh value used in the cluster command, only significant voxels will ever be reported.

---

Two-pass mode

Currently this mode operates on cluster ( -c ) and TFCE statistics only.

---

Associated Tools

Lesion Masking

For many clinical studies there are pathologies present (we are calling them "lesions" here, but they could be anything) and it is desirable to exclude them from the analysis, since they are usually highly variable across patients. In order to make this task easier in randomise there is a script called setup_masks. This takes a set of user-defined masks (normally drawn by hand) and creates a suitable set of files that can be used in randomise, including modified design matrices and contrasts to include the mask-based EVs. The masks should be in the form that can be used directly in randomise; that is, in the same space and containing a value of 1 in the voxels to be excluded and 0 in all other voxels (so that a lesion would be filled with ones in this case).

Usage of the script is:

setup_masks <input matrix> <input contrast> <output basename> <mask1> <mask2> ...

The list of mask images (<mask1> <mask2> ...) must be from subjects in the same order as used in the design matrix

New versions of both the design matrix and contrasts are created (starting with the specified output basename). In addition, a set of images is created, suitable as voxelwise regressors for randomise, and a list file tailored for randomise.

The final output of the script is an example call to randomise (printed to the screen) that shows exactly how to use the output files in a call to randomise. Other options (as would have been used without the voxelwise regressors) can then be added at the end of the randomise command to easily form a complete randomise call.

---

CategoryRandomise