Manual for previous SnPM versions
|
|
SnPM99, SnPM2, SnPM3, SnPM5 and SnPM8 Manual
SnPM is an SPM toolbox developed by Andrew Holmes & Tom Nichols |
This page... overview getting started & SnPM GUI design setup computation viewing results SnPM pages... manual PET example fMRI example FSL users |
Toolbox overviewThe Statistical nonParametric Mapping toolbox provides an extensible framework for non-parametric permutation/randomisation tests using the General Linear Model and pseudo t-statistics for independent observations. This manual page describes how to use the package. Because the non-parametric approach is computationally intensive, involving the computation of a statistic image for every possible relabelling of the data, the toolbox has been designed to permit batch mode computation. An SnPM statistical analysis is broken into three stages:
A non-parametric analysis requires the specification of the possible relabellings, and the generation of the corresponding permutations matrix. This is design specific, so the setup stage of SnPM adopts a PlugIn architecture, utilising PlugIn M-files specific for each design that setup the permutations appropriately. (The PlugIn architecture is documented in
Interim communication between the stages is via MatLab Note: Please also read the main SnPM page!
|
Getting started
First install the SnPM software alongside an SPM99 installation, ensuring both packages are on the MATLABPATH.
GUI usage
SnPM runs on top of the SPM environment, and is launched from within MatLab by typing snpm in the command window. This will start the SPM environment if not already launched (or switch an existing SPM session to the PET modality), bring up the SnPM GUI, and display late breaking SnPM information in the SPM graphics window. SnPM99 prints status information to the MatLab command line for long computations, so it's a good idea to keep the MatLab window visible whilst using SnPM.
Command line & batch usage
SnPM can also be run in command-line mode. Start MatLab and type global CMDLINE; CMDLINE=1 in the MatLab command window to switch to interactive command line use. The postprocessing and results function spm_snpm_pp will open an SPM Graphics when required. (If you rely on the default header parameters, then you should also initialise the SPM global environment variables: Type spm('Defaults','PET') ) Thus, having setup a design, the SnPM computation engine routine spm_snpm can be run without windows, in batch mode, by providing the directory containing the appropriate SnPM_cfg.mat configuration file to use as an argument.
SnPM GUI
The SnPM GUI has buttons for launching the three stages of an SnPM analysis, with corresponding help buttons. This online help text is similar to that presented on this page, the "About SnPM" topic being the overview given above. Detailed instructions for the three modules are given below.
![[SnPMmenu]](SnPMmenu.gif)
Setting up the design & defining appropriate permutations
Derived from help text for spm_snpm_ui.m
spm_snpm_ui sets up the parameters for a non-parametric
permutation/randomisation analysis. The approach taken with SnPM
analyses differs from that of SPM. Instead of intiating the analysis
with one command, an analysis consists of 3 steps:
1. Configuration of Analysis --- interactive
2. Calculation of Raw Statistics --- noninteractive
3. Post Processing of Raw Statistics --- interactive
( In SPM, all of these steps are done with a click to the "Statistics" )
( button, though the 3rd step is often redone with "Results" or "SPM{Z}")
The first step is embodied in this function, spm_snpm_ui. spm_snpm_ui
configures the design matrix and calls "plug in" modules that specify
how the relabeling is to be done for particular designs.
The result of this function is a mat file, "SnPM_cfg.mat", written
to the present working directory. This file contains all the
parameters needed to perform the second step, which is in embodied in
spm_snpm. Design parameters are displayed in the SPM graphics window,
and are printed.
-----------------------------------------------------------------------
-The Prompts Explained
=======================================================================
'Select design type...': Choose from the available designs. Use the
'User Specifed PlugIn' option to supply your own PlugIn function. Use
the 'keyboard' option to manually set the required PlugIn variables
(as defined below under "PlugIn Must Supply the following").
- At this point you will be prompted by the PlugIn file;
- see help for the PlugIn file you selected.
'FWHM(mm) for Variance smooth': Variance smoothing gives the
nonparmetric approach more power over the parametric approach for
low-df analyses. If your design has fewer than 20 degrees of freedom
variance smoothing is advised. 10 mm FWHM is a good starting point
for the size of the smoothing kernal. For non-isotropic smoothing,
enter three numbers: FWHM(x) FWHM(y) FWHM(z), all in millimeters.
If there are enough scans and there is no variance smoothing in the z
direction, you will be asked...
'# scans: Work volumetrically?': Volumetric means that the entire
data set is loaded into memory; while this is more efficient than
iterating over planes it is very memory intensive.
( Note: If you specify variance smoothing in the z-direction, SnPM )
( (in spm_snpm.m) has to work volumetrically. Thus, for moderate to )
( large numbers of scans there might not be enough memory to complete )
( the calculations. This shouldn't be too much of a problem because )
( variance smoothing is only necesary at low df, which usually )
( corresponds to a small number of scans. Alternatively, specify only )
( in-plane smoothing. )
'Collect Supra-Threshold stats?': In order to use the permutation
test on supra-threshold cluster size you have to collect a
substantial amount of additional data for each permutation. If you
want to look at cluster size answer yes, but have lots of free space
(the more permutations, the more space needed). You can however
delete the SnPM_ST.mat file containing the supra-threshold cluster
data at a later date without affecting the ability to analyze at the
voxel level.
The remaining questions all parallel the standard parametric analysis
of SPM; namely
'Select global normalisation' - account for global flow confound
'Gray matter threshold ?' - threshold of image to determine gray matter
'Value for grand mean ?' - arbitrary value to scale grand mean to
PlugIns
PlugIns are provided for three basic designs:
Single subject simple (2 condition) activation
Derived from help text for spm_snpm_SSA2x PlugIn
spm_snpm_SSA2x is a PlugIn for the SnPM design set-up program, creating design and permutation matrix appropriate for single subject, two condition activation (with replication) experiments. -Number of permutations ======================================================================= There are nScan-choose-nRepl possible permutations, where nScan is the number of scans and nRepl is the number of replications (nScan = 2*nRepl). Matlab doesn't have a choose function but you can use this expression prod(1:nScan)/prod(1:nRepl)^2 -Prompts ======================================================================= '# replications per condition': Here you specify how many times each of the two conditions were repeated. 'Size of exchangability block': This is the number of adjacent scans that you believe to be exchangeable. The most common cause of non-exchangeability is a temporal confound. Exchangibility blocks are required to be the same size, a divisor of the number of scans. See snpm.man for more information and references. 'Select scans in time order': Enter the scans to be analyzed. It is important to input the scans in time order so that temporal effects can be accounted for. 'Enter conditions index: (B/A)': Using A's to indicate activation scans and B's to indicate baseline, enter a sequence of 2*nRepl letters, nRepl A's and nRepl B's, where nRepl is the number of replications. Spaces are permitted.
Single subject correlation (single covariate of interest)
Derived from help text for spm_snpm_SSC PlugIn
spm_snpm_SSC is a PlugIn for the SnPM design set-up program, creating design and permutation matrix appropriate for single- subject, correlation design. -Number of permutations ======================================================================= There are nScan! (nScan factoral) possible permutations, where nScan is the number of scans of the subject. You can compute this using the gamma function in Matlab: nScan! is gamma(nScan+1); or by direct computation as prod(1:nScan) -Prompts ======================================================================= 'Select scans in time order': Enter the scans to be analyzed. It is important to input the scans in time order so that temporal effects can be accounted for. 'Enter covariate values': These are the values of the experimental covariate. 'Size of exchangability block': This is the number of adjacent scans that you believe to be exchangeable. The most common cause of nonexchangeability is a temporal confound (e.g. while 12 adjacent scans might not be free from a temporal effect, 4 adjacent scans could be regarded as having neglible temporal effect). See snpm.man for more information and references. '### Perms. Use approx. test?': If there are a large number of permutations it may not be necessary (or possible!) to compute all the permutations. A common guideline is that 1000 permutations are sufficient to characterize the permutation distribution well. More permutations will probably not change the results much. If you answer yes you will be prompted for the number... '# perms. to use?'
Multi subject simple activation (2 conditions, randomisation)
Derived from help text for spm_snpm_MSA2x PlugIn
spm_snpm_MSA2x is a PlugIn for the SnPM design set-up program,
creating design and permutation matrix appropriate for multi-
subject, two condition with replication design, where where
the condition labels are permuted over subject.
This PlugIn is only designed for studies where there are two
sets of labels, each the A/B complement of the other
(e.g. ABABAB and BABABA), where half of the subjects have one
labeling and the other half have the other labeling. Of course,
there must be an even number of subjects.
-Number of permutations
=======================================================================
There are (nSubj)-choose-(nSubj/2) possible permutations, where
nSubj is the number of subjects. Matlab doesn't have a choose
function but you can use this expression
prod(1:nSubj)/prod(1:nSubj/2)^2
-Prompts
=======================================================================
'# subjects': Number of subjects to analyze
'# replications per condition': Here you specify how many times
each of the two conditions were repeated.
For each subject you will be prompted:
'Subject #: Select scans in time order': Enter this subject's scans.
It is important to input the scans in time order so that temporal
effects can be accounted for.
'Enter conditions index: (B/A)': Using A's to indicate activation
scans and B's to indicate baseline, enter a sequence of 2*nRepl
letters, nRepl A's and nRepl B's, where nRepl is the number of
replications. Spaces are permitted.
There can only be two possible condition indicies: That of the
first subject and the A<->B flip of the first subject.
'### Perms. Use approx. test?': If there are a large number of
permutations it may not be necessary (or possible!) to compute
all the permutations. A common guideline is that 1000 permutations
are sufficient to characterize the permutation distribution well.
More permutations will probably not change the results much.
If you answer yes you will be prompted for the number...
'# perms. to use?'
Computing the nonParametric permutation distributions
Derived from help text for spm_snpm.m
spm_snpm is the engine of the SnPM toolbox and implements the general linear model for a set of design matrices, each design matrix constituting one permutation. First the "correct" permutation is calculated in its entirety, then all subsequent permutations are calculated, possibly on a plane-by-plane basis. The output of spm_snpm parallels spm_spm: for the correct permutation .mat files containing parameter estimates, adjusted values, statistic values, and F values are saved; the permutation distribution of the statistic interest and (optionally) suprathreshold stats are also saved. All results are written to the directory that CfgFile resides in. IMPORTANT: Existing results are overwritten without prompting. Unlike spm_spm, voxels are not discarded on the basis of the F statistic. All gray matter voxels (as defined by the gray matter threshold) are retained for analysis; note that this will increase the size of all .mat files. ----------------------------------------------------------------------- Output File Descriptions: SPMF.mat contains a 1 x S vector of F values reflecting the omnibus significance of effects [of interest] at each of the S voxels in brain (gray matter) *for* the correct permutation. XYZ.mat contains a 3 x N matrix of the x,y and z location of the voxels in SPMF in mm (usually referring the the standard anatomical space (Talairach and Tournoux 1988)} (0,0,0) corresponds to the centre of the voxel specified by ORIGIN in the *.hdr of the original and related data. BETA.mat contains a p x S matrix of the p parameter estimates at each of the S voxels for the correct permutation. These parameters include all effects specified by the design matrix. XA.mat contains a q x S matrix of adjusted activity values for the correct permutations, where the effects of no interest have been removed at each of the S voxels for all q scans. SnPMt.mat contains a 1 x S matrix of the statistic of interest (either t or pseudo-t if variance smoothing is used) supplied for all S voxels at locations XYZ. SnPM.mat contains a collection of strings and matrices that pertain to the analysis. In contrast to spm_spm's SPM.mat, most of the essential matrices are in the any of the matrices stored here in the CfgFile and hence are not duplicated here. Included are the number of voxels analyzed (S) and the image and voxel dimensions [V]. See below for complete listing. ----------------------------------------------------------------------- As an "engine", spm_snpm does not produce any graphics; if the SPM windows are open, a progress thermometer bar will be displayed. If out-of-memory problems are encountered, the first line of defense is to run spm_snpm in a virgin matlab session with out first starting SPM.
Examining the results
Derived from help text for spm_snpm_pp.m
spm_snpm_pp is the PostProcessing function for the SnPM nonParametric
statistical analysis. SnPM statistical analyses are split into three
stages; Setup, Compute & Assess. This is the third stage.
Nonparametric randomisation distributions are read in from MatLab
*.mat files, with which the observed statistic image is assessed
according to user defined parameters. It is the SnPM equivalent of
the "Results" section of SPM, albeit with reduced features.
Voxel level corrected p-values are computed from the permutation
distribution of the maximal statistic. If suprathreshold cluster
statistics were collected in the computation stage (and the large
SnPM_STC.mat file hasn't been deleted!), then assessment by
suprathreshold cluster size is also available, using a user-specified
primary threshold.
Instructions:
=======================================================================
You are prompted for the following:
(1) ResultsDir: If the results directory wasn't specified on the command
line, you are prompted to locate the SnPM results file SnPM.mat.
The directory in which this file resides is taken to be the
results directory, which must contain *all* the files listed
below ("SnPM files required").
Results (spm.ps & any requested image files) are written in the
present working directory, *not* the directory containing the
results of the SnPM computations.
----------------
(2) +/-: Having located and loaded the results files, you are asked to
chosse between "Positive or negative effects?". SnPM, like SPM,
only implements single tailed tests. Choose "+ve" if you wish to
assess the statistic image for large values, indicating evidence
against the null hypothesis in favour of a positive alternative
(activation, or positive slope in a covariate analysis).
Choose "-ve" to assess the negative contrast, i.e. to look for
evidence against the null hypothesis in favour of a negative
alternative (de-activation, or a negative slope in a covariate
analysis). The "-ve" option negates the statistic image and
contrast, acting as if the negative of the actual contrast was
entered.
A two-sided test may be constructed by doing two separate
analyses, one for each tail, at half the chosen significance
level, doubling the resulting p-values.
( Strictly speaking, this is not equivalent to a rigorous two-sided )
( non-parametric test using the permutation distribution of the )
( absolute maximum statistic, but it'll do! )
----------------
(3) WriteFiles: After a short pause while the statistic image SnPMt.mat
is read in and processed, you have the option of writing out the
complete statistic image as an Analyze file. If the statistic is
a t-statistic (as opposed to a pseudo-t computed with smoothed
variance estimator) you are given the option of "Gaussianising"
the t-statistics prior to writing, replacing each t-statistic
with an equivalently extreme standard Gaussian ordinate. (This
t->z conversion does *not* result in "Z-scores" a la Cohen, as is
commonly thought in the SPM community.)
The image is written to the present working directory, as
SPMt.{hdr,img} or SPMt_neg.{hdr,img}, "_neg" being appended when
assessing the -ve contrast. (So SPMt_neg.{hdr,img} is basically
the inverse of SPMt.{hdr,img}!) These images are 16bit, scaled by
a factor of 1000. All voxels surviving the "Grey Matter
threshold" are written, remaining image pixels being given zero
value.
Similarly you are given the option of writing the complete
single-step adjusted p-value image. This image has voxel values
that are the non-parametric corrected p-value for that voxel (the
proportion of the permutation distribution for the maximal
statistic which exceeds the statistic image at that voxel). Since
a small p indicates strong evidence, 1-p is written out. So,
large values in the 1-p image indicate strong evidence against
the null hypothesis. This image is 8bit, with p=1 corresponding
to voxel value 0, p=0 to 255. The image is written to the
present working directory, as SnPMp_SSadj.{img,hdr} or
SnPMp_SSadj_neg.{img,hdr}. This image is computed on the fly, so
there may be a slight delay...
Note that voxel level permutation distributions are not
collected, so "uncorrected" p-values cannot be obtained.
----------------
Next come parameters for the assessment of the statistic image...
(4) alpha: (Corrected p-value for filtering)
Next you enter the \alpha level, the statistical significance
level at which you wish to assess the evidence against the null
hypothesis. In SPM this is called "filtering by corrected
p-value". SnPM will only show you voxels (& suprathreshold
regions if you choose) that are significant (accounting for
multiple comparisons) at level \alpha. I.e. only voxels (&
regions) with corrected p-value less than \alpha are shown to
you.
Setting \alpha to 1 will show you all voxels with a positive statistic.
(5) SpatEx: If you collected supra-threshold cluster statistics during
the SnPM computation phase, you are offered the option to assess
the statistic image by supra-threshold cluster size (spatial
extent). Note that SnPM99 assesses suprathreshold clusters by
their size, whilst SPM99 uses a bivariate test based on size &
height (Poline et al., 1996), the framing of which cannot be
exactly mimicked in a non-parametric manner.
5a) ST_Ut: If you chose to asses spatial extent, you are now prompted
for the primary threshold. This is the threshold applied to the
statistic image for the identification of supra-threshold
clusters.
The acceptable range is limited. SnPM has to collect
suprathreshold information for every relabelling. Rather that
pre-specify the primary threshold, information is recorded for
each voxel exceeding a low threshold (set in spm_snpm) for every
permutation. From this, suprathreshold cluster statistics can be
generated for any threshold higher than the low recording
threshold. This presents a lower limit on the possible primary
threshold.
The upper limit (if specified) corresponds to the statistic value
at which voxels become individually significant at the chosen
level (\alpha). There is little point perusing a suprathreshold
cluster analysis at a threshold at which the voxels are
individually significant.
If the statistics are t-statistics, then you can also specify the
threshold via the upper tail probability of the t-distribution.
(NB: For the moment, \alpha=1 precludes suprathreshold analysis, )
( since all voxels are significant at \alpha=1. )
That's it. SnPM will now compute the appropriate significances,
reporting its progress in the MatLab command window. Note that
computing suprathreshold cluster size probabilities can take a long
time, particularly for low thresholds or large numbers of
relabellings. Eventually, the Graphics window will come up and the
results displayed.
- Results
========================================================================
The format of the results page is similar to that of SPM:
A Maximum Intensity Projection (MIP) of the statistic image is shown
top left: Only voxels significant (corrected) at the chosen level
\alpha are shown. (If suprathreshold cluster size is being assessed,
then clusters are shown if they have significant size *or* if they
contain voxels themselves significant at the voxel level.) The MIP is
labelled SnPM{t} or SnPM{Pseudo-t}, the latter indicating that
variance smoothing was carried out.
On the top right a graphical representation of the Design matrix is
shown, with the contrast illustrated above.
The lower half of the output contains the table of p-values and
statistics, and the footnote of analysis parameters. As with SPM, the
MIP is tabulated by clusters of voxels, showing the maximum voxel
within each cluster, along with at most three other local maxima
within the cluster. The table has the following columns:
* region: The id number of the suprathreshold. Number 1 is assigned to
the cluster with the largest maxima.
* size{k}: The size (in voxels) of the cluster.
* P(Kmax>=k): P-value (corrected) for the suprathreshold cluster size.
This is the probability (conditional on the data) of the experiment
giving a suprathreshold cluster of size as or more extreme anywhere
in the statistic image. This is the proportion of the permutation
distribution of the maximal suprathreshold cluster size exceeding
(or equalling) the observed size of the current cluster. This
field is only shown when assessing "spatial extent".
* t / Pseudo-t: The statistic value.
* P(Tmax>=t): P-value (corrected) for the voxel statistic.
This is the probability of the experiment giving a voxel statistic
this extreme anywhere in the statistic image. This is the
proportion of the permutation distribution of the maximal
suprathreshold cluster size exceeding (or equalling) the observed
size of the current cluster.
* (uncorrected): If the statistic is a t-statistic (i.e. variance smoothing
was *not* carried out, then this field is computed by comparing the
t-statistic against Students t-distribution of appropriate degrees
of freedom. Thus, this is a parametric uncorrected p-value. If
using Pseudo-t statistics, then this field is not shown, since the
data necessary for computing non-parametric uncorrected p-values is
not computed by SnPM.
* {x,y,z} mm: Locations of local maxima.
The SnPM parameters footnote contains the following information:
* Primary threshold: If assessing "spatial extent", the primary
threshold used for identification of suprathreshold clusters is
printed. If using t-statistics (as opposed to Pseudo-t's), the
corresponding upper tail probability is also given.
* Critical STCS: The critical suprathreshold cluster size. This is
size above which suprathreshold clusters have significant size at
level \alpha It is computed as the 100(1-alpha)%-ile of the
permutation distribution of the maximal suprathreshold cluster
size. Only shown when assessing "spatial extent".
* alpha: The test level specified.
* Critical threshold: The critical statistic level. This is the value
above which voxels are significant (corrected) at level \alpha. It
is computed as the 100(1-alpha)%-ile of the permutation
distribution of the maximal statistic.
* df: The degrees of freedom of the t-statistic. This is printed even
if
variance smoothing is used, as a guide.
* Volume & voxel dimensions:
* Design: Description of the design
* Perms: Description of the exchangability and permutations used.
- Next SnPM page: Example
-
SnPM by Andrew Holmes of the Astra Zeneca
& Tom Nichols of University of Michigan Biostatistics department
- SnPMauthors at <snpm-authors at umich.edu>
Neuroimaging
Statistics
Contact Info
Room D0.03
Deptment of Statistics
University of Warwick
Coventry
CV4 7AL
United Kingdom
Tel: +44(0)24 761 51086
Email: t.e.nichols 'at' warwick.ac.uk
Web: http://nisox.org
Blog: NISOx blog
![[Book Cover]](https://warwick.ac.uk/fac/sci/statistics/staff/academic-research/nichols/publications/books/handbookfmri_cover.jpg?maxWidth=125)
Handbook of fMRI Data Analysis by Russ Poldrack, Thomas Nichols and Jeanette Mumford