3. R package
Installation - Usage - Command line utility
The latest developer version of pTFCE can always be installed from GitHub:
Step 1. To be able to install pTFCE R-package from GitHub, first make sure you have the devtools package installed.
Type the followings into the R console to install and load devtools:
install.packages("devtools")
library(devtools)
install_github("spisakt/pTFCE@v0.2.2.1")
Make sure to change the version number after the @ sign to the latest one (or the preferred one) from the releases. Then load the installed package:
library(pTFCE)
citation("pTFCE")
Now, you are ready for cluster-based belief boosting!
pTFCE will be soon also available on CRAN...
Click here for the usage instructions of the R-based command line utility
Installing pTFCE automatically installed its dependencies, the mmand and the oro.nifti R-packages. The latter one is needed to read NIfTI files. We must load it, and also the pTFCE package:
library(oro.nifti)
library(pTFCE)
- in FSL this will be something like <your_gfeat_folder>/cope.feat/stats/zstat.nii.gz
- in SPM, by default you have only your T-score map, called spmT_.nii (or .hdr/.img pair) at hand. In R, after loading this image with "readNIfTI" (see below) you can convert it to a Z-score map by the command "Z=qnorm( pt(Tmap, df=degrees_of_freedom, log.p = T), log.p = T )", where your degrees-of-freedom can be found in your SPM.mat.
- or you can download and use this simulated sample file to continue with this tutorial: https://github.com/spisakt/pTFCE/blob/master/inst/extdata/example.nii.gz
Z=readNIfTI("path/to/your/z-score-map.nii.gz")
- in FSL this will be something like <your_feat_folder>/mask.nii.gz
- in SPM this will be the file called mask.nii (or .hdr/.img pair) in your SPM analysis folder.
- or you can download and use this simulated sample file to continue with this tutorial: http://github.com/spisakt/pTFCE/blob/master/inst/extdata/test02_mask.nii.gz
MASK=readNIfTI("path/to/your/mask.nii.gz")
pTFCE=ptfce(Z, MASK)
Image smoothness is estimated based on the data and enhancement is performed. For more information on estimating image smoothness click here.
Now, the enhanced image is in the returned pTFCE object. E.g. the enhanced Z-score map is available as pTFCE$Z.
Let's compare the pTFCE enhanced image to the original one:
orthographic(Z, zlim=c(0, max(pTFCE$Z)), crosshair=F) #original
orthographic(pTFCE$Z, zlim=c(0, max(pTFCE$Z)), crosshair=F) #pTFCE
In case you used the simulated sample files, you should see something like:
Alternatively, you can save the enhanced image as NIfTI with:
writeNIfTI(pTFCE$Z, "path/to/your/pTFCE-z-score-map.nii.gz")
And use your favourite NIfTI image viewer.
In general, it is valid to threshold your enhanced Z-score image with the same Z-score threshold you would have applied for the original (unenhanced) Z-score image. E.g. you can threshold the enhanced Z-score image for an uncorrected p<0.001 with the corresponding Z-score value of Z>3.1. Or you can perform a correction for multiple comparisons on the original (unenhanced) Z-score map via controlling for the voxel-level family-wise error rate, then get the Z-threshold and use it on the pTFCE-enhanced Z-score image.
If you don't know and can't extract the proper threshold from the software of your choice, there are still several ways to get the the voxel-level GRF threshold:
- with FSL's ptoz:
ptoz 0.05 -g <number_of_resels>
- The pTFCE R-package also provides some functionality to perform image thresholding with GRF theory-based multiple comparison.
To apply the common p<0.05 corrected statistical threshold, simply use the 'fwer0.05.Z' field of the ptfce output:
orthographic(pTFCE$Z, zlim=c(pTFCE$fwer0.05.Z, max(pTFCE$Z)), crosshair=F)
This displays the pTFCE enhanced Z-score image thresholded at p<0.05, corrected for multiple comparisons via GRF Theory-based maximum height thresholding.
- To apply corrected p-value threshold other than 0.05, you might also consider using the fwe.p2z() and fwe.z2p() functions of the pTFCE R-package.
fwer0.01.Z=fwe.p2z(pTFCE$number_of_resels, 0.01)
orthographic(pTFCE$Z, zlim=c(fwer0.01.Z, max(pTFCE$Z)), crosshair=F)
- Alternatively, check out the command line utility (scroll down), which does everything automatically.
Never use the enhanced Z-score map as an input for GRF-based multiple correction techniques. Instead, use the original Z-score map to compute the Z-score threshold and then use this threshold on the enhanced image.
Never use cluster-level thresholding on the pTFCE-enhanced image. It already incorporates the cluster information, thus thresholding it based on cluster-extent (of the original image) would be double-dipping.
Note that there are different methods for estimating the Z-threshold. The method implemented in the R-package might be overly conservative in certain cases. In theory, you are always free to use the same Z-score threshold that you used for the unenhanced image, computed by e.g. FSL (GLM or randomise), SPM or other software tools.
After installing the R-package, download the bash-wrapper.
Link (or copy) it to your "bin" directory (e.g. ~/bin, added to the PATH environmental variable) if you wish:
ln -s ~/Downloads/ptfceR.sh ~/bin/ptfceR
Then use it like:
ptfceR -h
ptfceR -r my_res4d.nii -d $DOF my_zstat.nii my_mask.nii
It will create the following output in the same directory:
- pTFCE_Z_my_zstat.nii.gz - enhanced Z-stat image.
- thres_z_my_zstat.txt - GRF-based Z-score threshold for a p<0.05 corrected significance thresholding
- smoothness_my_zstat.txt and smoothness_full_my_zstat.txt - smoothness information
- Rd_my_zstat.txt - Rd value of smoothness
- numRESELs_my_zstat.txt - number of resels
