Want to get started with threshold free cluster enhancment using FSL's Randomise? Start here.
First, read the user guide. When you're done, return here.
- TFCE is a one-sided procedure. This means that you should specify t/Z-contrasts and their inverse (e.g.,
A - BandB - A) if you want to test two-sided hypotheses. The thresholding script assumes that you will be testing two-sided hypotheses and so uses a cutoff of1 - 0.025 = 0.975. In other words, the negative contrast has a false-positive error rate of 2.5%, as does the positive contrast, for a total error rate of the usual 5%. If your hypothesis is really one-sided, you should adjust this to .95. - Randomise runs all N permutations for every contrast that is defined in
design.con(because of how it deals with covariates). This means that if there are some contrasts you know you won't interpret, there's no reason to include them. That said, these permutatons don't take very long, and since they're running on the cluster, you shouldn't need to worry too much about it. Just make sure the sbatch file requests enough time. In one example run, with 10,000 permutations for each of 8 contrasts, the total wall-time was 18.5 hours, with 1.3 G maximum memory used. The defaults for thesbatchscript are based on these numbers, but yours may vary.
Permutation testing allows you to relax the assumptions underlying the parametric models used by FEAT/FLAME to derive p-values and test statistics. Randomise generates a null distribution from the data you have by mixing it up so that the expected association between your independent and dependent variables is 0. This allows you to derive a p-value that is not invalidated by violations of the parametric assumptions of other models. It is almost always the case that if the p-value differs between the parametric null and the permutation null distribution, it's the permutation distribution that is the correct reference. This means more confidence in the statistic, and often times greater statistical power
It also allows you to generate the spatial distribution of null test statistics, which further enables threshold free cluster enhancement (TFCE). Typical corrections for multiple comparisons do not take into account the spatial autocorrelation of test statistics, which often means that the adjustment is made for more tests than necessary. Cluster corrections for multiple comparisons take this spatial information into account. TFCE, specifically, combines information about the signal height (that is, that inverse of the size of the p-value) and extent (how big an area is occupied by p-values at least that big). The intuition is that you can infer that a set of p-values should be made more significant if there are more of them in one place than would be expected by chance (which you can tell by the permuted maps). The big inovation with TFCE is that it does this without having to set a particular p-value cutoff so you can find very small but, but very significant clusters and very big but not so significant clusters at the same time. This is almost a certainly garbled explanations, so you should go read the original paper.
If you've generated a group-level model with FEAT, you have all the information you need to run Randomise on Harvard's supercomputing cluster. At it's simplest, all you need to do is sbatch the run_randomise_tfce.bash script with your gfeat directory. The script copies the files specifying first-level model locations, contrasts, covariates, and group-dependence structure to the directory you're running the script from, and runs Randomise using 10,000 permutations. It might take a day to run, but at the end you get a pretty robust set of results.
(Assuming you're logged into ncf...)
Note well: The default is to run 10,000 permutations; this is done for each and every contrast you've requested.
- Clone this repository to your home directory, or wherever you keep your code:
git clone https://github.com/stressdev/randomise_tfce_helpers - Copy the bash script to the directory you want to store the results:
cd randomise_tfce_helpers; cp run_randomise_tfce.bash ~/folder/where/your/results/go - Travel to the results directory and edit the script if you want to change some of the options. If you expect the process to take a long time, for example, increase the allowed time at the top of the script (e.g., change
#SBATCH --time=1-00:00:00to#SBATCH --time=5-00:00:00if you think it might take 5 days to run):cd ~/folder/where/your/results/go; nano run_randomise_tfce.bash - Run the script, providing necessary arguments. For help, run:
bash run_randomise_tfce.bash -h. For a typical run, you only need to supply a single argument, which is the group-level feat directory like:sbatch run_randomise_tfce.bash -g /path/to/group.feat.
If your design.con and design.mat are set up to include a one-sample t-test, randomise will appropriately handle this case. However, you can also explicitly ask for a one-sample t-test using the first-level files specified in the design.fsf file, or in a user-suipplied 4d NIFTI.
The script threshold_and_cluster.bash is there to help you threshold your raw t-statistic image using the TFCE p-value image, which is really useful if you've requested a lot of contrasts.
To run it, simply execute: bash threshold_and_cluster.bash in the directory your TFCE images are. All it does is search that directory for all files that match "*tfce_corrp_tstat*", reconstructs the t-statistic filename, uses fslmaths to compute a new thresholded t-statistic image named *tstat*_thresh.nii.gz, and then runs cluster to get various cluster output.
run_randomise_tfce.bash
*tfce_corrp_tstat*.nii.gz TFCE 1-p images
*tstat*.nii.gz Raw t-statistic images
threshold_and_cluster.bash
*tstat*_thresh.nii.gz Thresholded t-statistic image (for figure-making, need to find min - see below)
*tstat*_cluster_index.nii.gz Cluster index image (intensities = # referring to that cluster)
*tstat*_cluster_size.nii.gz Cluster size image (intensities = # vox in that cluster)
*tstat*_lmax.txt Local maxima text file
*tstat*_clusters.txt Clusters table (for reporting in tables)
TFCE does not result in clean, consistent p-value minimum values for voxels across maps; this will change for every map. For best, consistent figures, set the min equal to the min intensity value of that given map (it likely will not automatically populate). To find that value, run:
3dBrickStat -min -non-zero *thresh.nii.gz
Depending on your program, you may need to specify a max value. You can find that with the -max flag instead of -min, but this throws the coloring off in some programs and your best bet may be a value that is twice your min.
For more details about options and how to interpret the output, see the Randomise user guide.