Differences between revisions 2 and 3
Deletions are marked like this. Additions are marked like this.
Line 17: Line 17:
--name mypalm-twotail-1.3 means to create a folder called mypalm-twotail-1.3 in glmdir where the PALM output will be stored --name mypalm-twotail-1.3 : create a folder called mypalm-twotail-1.3 in glmdir for PALM output
Line 21: Line 21:
Line 25: Line 24:
The main One-tailed or two? The "tailedness" of the analysis refers to whether you expect the contrast to be positive or negative or you have no expectation. If you have an expectation, then you should use a one-tailed test, otherwise use a two-tailed test. The one-tailed will be more powerful but you must have an a priori reason for using a one-tailed test. When selecting a two-tailed test, the CFT is increased by 0.3 behind the scenes because uncorrected, voxel-wise p-values in PALM are always one-tailed. Increasing the (log10) CFT by 0.3 is the same halving the p-value threshold. Eg, if you wanted a voxel-wise threshold of 0.05, the CFT would be -log10(.05)=1.3. For a two-tailed test, this would be changed to 1.6 which corresponds to .025. So you would specify --cft 1.3 --twotail and fspalm will automatically use 1.6. In some ways, this added complication is perhaps unnecessary because the CFT is mostly arbitrary anyway. But this is the way that mri_glmfit-sim behaves and we wanted to be consistent.

fspalm is a FreeSurfer script written to aid in the use of Permutation Analysis of Linear Models (PALM) for the correction of multiple comparisons on the surface and in the volume. PALM, written by Anderson Winkler, offers a huge number of analysis options for permutation. See fsl.fmrib.ox.ac.uk/fsl/fslwiki/PALM for more details. The purpose of fspalm is to make it relatively easy to interface with PALM, though it is still up to the user to make most of the decisions. Those using PALM should cite the appropriate articles, eg:

Winkler AM, et al. Non-Parametric Combination and related permutation tests for neuroimaging. Hum Brain Mapp. 2016 Apr;37(4):1486-511.
Winkler AM, et al, . Multi-level block permutation. Neuroimage. 2015;123:253-68.
Winkler AM, et al, . Faster permutation inference in brain imaging. Neuroimage. 2016 Jun 7;141:502-516

Before using fspalm, download PALM from fsl.fmrib.ox.ac.uk/fsl/fslwiki/PALM and add it to your matlab path. You must also have these two FreeSurfer paths in your matlab path (if not there already): $FREESURFER_HOME/matlab and $FREESURFER_HOME/fsfast/toolbox

To use fspalm, first run mri_glmfit to get a glm folder. This folder will contain the contrasts as specified with the --C option to mri_glmfit as well as all the other mri_glmfit output. You can use fspalm with both volume- and surface-based analyses; it will figure everything out. The configuration and output is meant to mimic the FreeSurfer mri_glmfit-sim program, which can also be used to perform permutation-based correction for multiple comparisons (though without all the options of PALM).

An example fspalm command line is

fspalm --glmdir glmdir --cft 1.3 --twotail --name palm-twotail-1.3 --iters 1000 --2spaces --cwp .05 
--glmdir is the output folder of mri_glmfit
--cft 1.3 is the voxel-wise cluster forming threshold (CFT) as -log10(p). for cft = 1.3, p=.05
--name mypalm-twotail-1.3 : create a folder called mypalm-twotail-1.3 in glmdir for PALM output 
--iters 1000 means to run 1000 permutation iterations
--2spaces : bonferroni correct clusterwise pvalues for two-spaces (eg, left and right hemispheres)
--cwp .05  : filter out all clusters that have p>.05 (after any bonferroni correction)

This command will do several things. First it will convert the design and contrast matrices to design.mat and design.con files expected by PALM. It will create a matlab file called run_palm.m where it will create a palm command line. It will then run 1000 permutations and save the output with a base name of fsp (eg, fsp_clustere_tstat_fwep_c2.mgz). It will then create summary files as well as annotations (surface) or segmentations (volumes). For example, if there were a contrast called g1-g2, then it would create g1-g2.pv.clustertable.summary with a list of the surviving clusters, their size, the location of the peak voxel in MNI305 space, and the segmentation/annotation that the peak voxel was located in. The clusterwise p-value is located in g1-g2.clustertable.summary. This file also has location information, but the values from the pv cluster table will be better. There will also be a file called g1-g2.y.ocn.dat. This is a text file with mean input values for each subject and cluster (ie, each row is a subject, each column is a cluster). There will be a filed called g1-g2.ocn.{mgz,nii} that will be a segmentation (ie, the value of the voxel is the cluster number). For surface-based analyses, there will also be a file called g1-g2.ocn.annot which will be an annotation of the clusters.

One-tailed or two? The "tailedness" of the analysis refers to whether you expect the contrast to be positive or negative or you have no expectation. If you have an expectation, then you should use a one-tailed test, otherwise use a two-tailed test. The one-tailed will be more powerful but you must have an a priori reason for using a one-tailed test. When selecting a two-tailed test, the CFT is increased by 0.3 behind the scenes because uncorrected, voxel-wise p-values in PALM are always one-tailed. Increasing the (log10) CFT by 0.3 is the same halving the p-value threshold. Eg, if you wanted a voxel-wise threshold of 0.05, the CFT would be -log10(.05)=1.3. For a two-tailed test, this would be changed to 1.6 which corresponds to .025. So you would specify --cft 1.3 --twotail and fspalm will automatically use 1.6. In some ways, this added complication is perhaps unnecessary because the CFT is mostly arbitrary anyway. But this is the way that mri_glmfit-sim behaves and we wanted to be consistent.


Another use case is to have fspalm just prepare the design and command line files so that the user can then customize the run_palm.m file to his/her liking. To do this, just add --monly.

FsPalm (last edited 2022-03-27 17:21:25 by DougGreve)