10074
Comment:

← Revision 4 as of 20130307 21:23:54 ⇥
9946
converted to 1.6 markup

Deletions are marked like this.  Additions are marked like this. 
Line 5:  Line 5: 
[[TableOfContents]]  <<TableOfContents>> 
Line 13:  Line 13: 
The following section gives detailed and basic instructions on installing and using the code. The last section (Notes on the implementation) gives some details of the algorithms and rules for creating an image to define your region of interest.'''WARNING  this software is in BETA testing. Please be careful in using it, and report any bugs to me at the address below.'''  The following section gives detailed and basic instructions on installing and using the code. The last section (Notes on the implementation) gives some details of the algorithms and rules for creating an image to define your region of interest. 
Line 17:  Line 17: 
I have tested this code on Sun Solaris, and Windows NT for PC. It should run with matlab 5.x, and maybe later versions. The mex files were compiled using gcc on Solaris, and gcc on the PC (with command mex DWIN32 [filename] ). See [http://gnumex.sourceforge.net the Cygwin / Windows gcc mex files page] for instructions for setting up gcc compiles on the PC.The code will, in matlab 5, be able to read SPM99 results files (see below).  I have tested this code on Sun Solaris, and Windows NT for PC. It should run with matlab 5.x, and maybe later versions. The mex files were compiled using gcc on Solaris, and gcc on the PC (with command mex DWIN32 [filename] ). See [[http://gnumex.sourceforge.netthe Cygwin / Windows gcc mex files page]] for instructions for setting up gcc compiles on the PC.The code will, in matlab 5, be able to read SPM99 results files (see below). 
Line 21:  Line 21: 
Obtain the archive file, [http://imaging.mrccbu.cam.ac.uk/downloads/Corr_p/corr_p.tar.gz corr_p.tar.gz], and unpack the archive into a directory on your matlab path. To do this, follow the instructions on the [wiki:UnpackCompressedFiles archive extraction page].If you are running the program on a machine other than a PC, Sun or SGI64, you will need to recompile two matlab mex routines. These are:  Obtain the archive file, [[http://imaging.mrccbu.cam.ac.uk/downloads/Corr_p/corr_p.tar.gzcorr_p.tar.gz]], and unpack the archive into a directory on your matlab path. To do this, follow the instructions on the [[UnpackCompressedFilesarchive extraction page]].If you are running the program on a machine other than a PC, Sun or SGI64, you will need to recompile two matlab mex routines. These are: 
Line 23:  Line 23: 
mat_vstats.c read_image.c 
1. mat_vstats.c 1. read_image.c 
Line 32:  Line 31: 
Line 37:  Line 37: 
Line 40:  Line 41: 
Line 44:  Line 46: 
First specify whether you want a corrected p value for an F field (SPM{F}) or a Z field (SPM{Z}(t)). Note that the SPM Z field is actually a simulated Z field by conversion from a t field  hence SPM{Z}(t). This has implications for the calculations (see below). There are also options for t statistics (which are produced by SPM99 and later) and true Z score corrections. SPM does not produce true Z scores, although the p values for Z(t) and true Z converge as degrees of freedom increase  see W96 (referred to in SmallVolumeCorrection).  First specify whether you want a corrected p value for an F field (SPM{F}), a t field (SPM{t}), a true Z score, or a SPM Z field (SPM{Z}(t)). The SPM Z field is an old option from the days of SPM96. SPM96 created Z field which were actually a simulated Z field by conversion from a t field  hence SPM{Z}(t). This has implications for the calculations (see below). Note that SPM does not produce true Z scores, although the p values for Z(t) and true Z converge as degrees of freedom increase  see [[SmallVolumeCorrection#W96]]. 
Line 54:  Line 56: 
You can define the search region in one of two basic ways. The first is to specify a box, or sphere, that contains the region that you are interested in. For this you choose the Box or Sphere buttons from the menu. For example, if your search region is box shaped, of about 40mm x 40mm x 20mm, then you would specify a box by choosing the Box option, and typing "40 40 20" in the "Box size (mm in XYZ)" input box. If your search region is roughly spherical, with radius 20mm, you would choose "Sphere" and enter the radius into the input box.Alternatively you could create an image of the region that you are interested in, containing nonzero values in the region, and zeros elsewhere  defining a Voxel Volume of Interest (VVOI). For example, let's say you are interested in the dorsolateral prefrontal cortex, and that your statistical map, say of Z scores, has 2x2x2mm voxel sizes. You might then get an MRI template in the same space as your statistic image, and edit out the whole brain apart from (say) the left dorsolateral prefrontal cortex. See the [#DefVVOI Creating VVOI images] section for details on creating such an image.  You can define the search region in one of two basic ways. The first is to specify a box, or sphere, that contains the region that you are interested in. For this you choose the Box or Sphere buttons from the menu. For example, if your search region is box shaped, of about 40mm x 40mm x 20mm, then you would specify a box by choosing the Box option, and typing "40 40 20" in the "Box size (mm in XYZ)" input box. If your search region is roughly spherical, with radius 20mm, you would choose "Sphere" and enter the radius into the input box.Alternatively you could create an image of the region that you are interested in, containing nonzero values in the region, and zeros elsewhere  defining a Voxel Volume of Interest (VVOI). For example, let's say you are interested in the dorsolateral prefrontal cortex, and that your statistical map, say of Z scores, has 2x2x2mm voxel sizes. You might then get an MRI template in the same space as your statistic image, and edit out the whole brain apart from (say) the left dorsolateral prefrontal cortex. See the [[#DefVVOICreating VVOI images]] section for details on creating such an image. 
Line 93:  Line 95: 
The calculations of corrected p values for SPM{Z} values used here are based on t fields rather than Z fields. This is because SPM generates simulated Z statistics from the calculated t field (see SPM course notes, and my [wiki:PrinciplesStatistics SPM statistics page] ). As W96 notes, using Gaussian RF results for simulated Z scores gives lower thresholds (and higher false positive rate) than using the t RF results on the underlying t statistics. This code therefore converts Z scores back to t statistics, calculates corrected p values and thresholds using t RF results, and, if necessary, converts t values back to Z scores for display.The current version of SPM (SPM99) takes a similar approach, by calculating thresholds based in the underlying t statistics rather than Z scores.  The calculations of corrected p values for SPM{Z} values used here are based on t fields rather than Z fields. This is because SPM generates simulated Z statistics from the calculated t field (see SPM course notes, and my [[PrinciplesStatisticsSPM statistics page]] ). As W96 notes, using Gaussian RF results for simulated Z scores gives lower thresholds (and higher false positive rate) than using the t RF results on the underlying t statistics. This code therefore converts Z scores back to t statistics, calculates corrected p values and thresholds using t RF results, and, if necessary, converts t values back to Z scores for display.The current version of SPM (SPM99) takes a similar approach, by calculating thresholds based in the underlying t statistics rather than Z scores. 
Line 97:  Line 99: 
This software (unlike SPM5 for example) requires the VVOI images to be in in [wiki:FormatAnalyze Analyze 7 format (SPM format)].  This software (unlike SPM5 for example) requires the VVOI images to be in in [[FormatAnalyzeAnalyze 7 format (SPM format)]]. 
vol_corr  a program to calculate small volume corrections in SPM
This page describes some rather old software I wrote to calculate SmallVolumeCorrection for older versions of SPM. It is largely redundant with recent versions of SPM, as the corrections are applied as part of the results interface (SVC button). However, it does calculate height thresholds needed for particular small volume correction at corrected thresholds of e.g. 0.05.
Contents

vol_corr  a program to calculate small volume corrections in SPM
 Differences between vol_corr and spm 99
 Installing the vol_corr code
 Using the corr_p code
 Unpacking the archive
 Running the program
 Defining the statistic
 Specifying smoothness and degrees of freedom
 Defining the shape and size of the volume of interest
 Corrected p values or statistic thresholds
 A worked example
 Notes on the implementation
 Acknowledgments and warnings
Differences between vol_corr and spm 99
As I mentioned above, SPM implements many of the small volume correction formulae, as does the vol_corr software, described here. The only significant difference between the corrections within SPM and the corrections in vol_corr is that vol_corr can give thresholds for Z/F/t statistics at set levels, such as alpha = 0.1, 0.05 etc. Both SPM and vol_corr will give corrected p values for given Z/F/t statistics
Installing the vol_corr code
The following section gives detailed and basic instructions on installing and using the code. The last section (Notes on the implementation) gives some details of the algorithms and rules for creating an image to define your region of interest.
Using the corr_p code
I have tested this code on Sun Solaris, and Windows NT for PC. It should run with matlab 5.x, and maybe later versions. The mex files were compiled using gcc on Solaris, and gcc on the PC (with command mex DWIN32 [filename] ). See the Cygwin / Windows gcc mex files page for instructions for setting up gcc compiles on the PC.The code will, in matlab 5, be able to read SPM99 results files (see below).
Unpacking the archive
Obtain the archive file, corr_p.tar.gz, and unpack the archive into a directory on your matlab path. To do this, follow the instructions on the archive extraction page.If you are running the program on a machine other than a PC, Sun or SGI64, you will need to recompile two matlab mex routines. These are:
 mat_vstats.c
 read_image.c
In matlab 5 the command is 'mex':
mex mat_vstats.c mex read_image.c
Many thanks to Geraint Rees for providing the SGI64 mex binaries.
Running the program
Run matlab. You should have the SPM96 or later distribution on the matlab path. At the matlab prompt, type:
>> vol_corr
The program will then prompt you for a variety of inputs. These inputs define the statistic for which you want corrected values, the smoothness parameters of the SPM containing the statistics, and the volume within which you are containing your search.
Defining the statistic
First specify whether you want a corrected p value for an F field (SPM{F}), a t field (SPM{t}), a true Z score, or a SPM Z field (SPM{Z}(t)). The SPM Z field is an old option from the days of SPM96. SPM96 created Z field which were actually a simulated Z field by conversion from a t field  hence SPM{Z}(t). This has implications for the calculations (see below). Note that SPM does not produce true Z scores, although the p values for Z(t) and true Z converge as degrees of freedom increase  see SmallVolumeCorrection#W96.
Specifying smoothness and degrees of freedom
The calculations require the smoothness of the statistic volume  in terms of FWHM, in mm. These are the FWHM figures, in mm, at the bottom of SPM result printouts. You can either type these FWHM figures in, for X Y and Z (choose "Input" from the buttons offered), or retrieve them from the SPM analysis files  "Analysis".If you choose "Analysis", you will be prompted to select the SPM.mat file for the analysis of interest. The calculation also requires the degrees of freedom of the analysis. If you chose "Analysis", the df are obtained from the SPM.mat file. If the SPM.mat file was from an SPM99 analysis, and you want a corrected p for an F value, you will need to choose the F contrast of interest, to define the F degrees of freedom.
If you chose "Input" then you will need to specify the degrees of freedom. For the Z scores, this is the 'degrees of freedom due to error' at the bottom of the SPM results printout. For the F statistic, there are two df values: the df for the effects of interest, followed by the df due to error. These are both printed on the design matrix printout page of a standard SPM96 analysis, or on the SPM glass brain displays in an SPM99 analysis. You will need to specify both figures in the input box, if you have asked for corrected values for an F field.
Defining the shape and size of the volume of interest
You can define the search region in one of two basic ways. The first is to specify a box, or sphere, that contains the region that you are interested in. For this you choose the Box or Sphere buttons from the menu. For example, if your search region is box shaped, of about 40mm x 40mm x 20mm, then you would specify a box by choosing the Box option, and typing "40 40 20" in the "Box size (mm in XYZ)" input box. If your search region is roughly spherical, with radius 20mm, you would choose "Sphere" and enter the radius into the input box.Alternatively you could create an image of the region that you are interested in, containing nonzero values in the region, and zeros elsewhere  defining a Voxel Volume of Interest (VVOI). For example, let's say you are interested in the dorsolateral prefrontal cortex, and that your statistical map, say of Z scores, has 2x2x2mm voxel sizes. You might then get an MRI template in the same space as your statistic image, and edit out the whole brain apart from (say) the left dorsolateral prefrontal cortex. See the Creating VVOI images section for details on creating such an image.
At this stage in the program input, you could then choose the 'Image' button, select your image defining your VVOI, and the program would use the image to determine the shape and size of the nonzero region(s) of this image. This in turn will determine the appropriate corrections to the Z/F/t p values.
The last button on this menu is 'vstats'. This enables you to use saved parameters already calculated from VVOIs, to avoid recalculation of the VOI parameters. Every time you choose the 'Image' button, the parameters of the VVOI are calculated, but also saved as imagename_vstats.mat in the same directory as the VVOI image. Thus, if the VVOI calculation takes a long time, and you wish to use the parameters from the same VVOI twice, the second time you wanted to use the VVOI, you might choose 'vstats' at this menu, and choose the imagename_vstats.mat file for your image.
Corrected p values or statistic thresholds
There are two uses for the corrected p values routines. The first is to input the relevant Z/F/t values, and get the corrected p values for those statistics. To do this, chose 'Corrected p', then type one or more Z/F/t values, and press return, to get the corrected values, printed in the matlab window.The second use is to derive the thresholds for your Z/F/t values that give corrected p values of less than or equal to some probability level  e.g 0.05. Here you choose the 'Thresholds' button, and then input one or more levels of probability, e.g. 0.1 0.05 0.01. The statistics giving each p value are displayed in the matlab window.
A worked example
So, let us imagine that you want corrected t thresholds for an SPM99 analysis you have already done on the whole brain. You want corrected statistics assuming you are only looking at the dorsolateral prefrontal cortex. You have already created an image defining the dorsolateral prefrontal cortex, called "DLPFC.img". This is the procedure: 1. Run vol_corr
 choose "t field" for "Type of statistic"
 choose "Analysis" for "Smoothness params from"
 select the 'SPM.mat' file for your analysis of the whole brain
 Choose "Image" for "VOI defined using"
 Select your image defining the dorsolateral prefrontal cortex  "DLPFC.img"
 Choose "Thresholds" for "Select output required"
 Type "0.1 0.05 0.01" in the "Input alpha level(s) required" input box
 You should now get output in the matlab window which looks a little like:
Volume correction Smoothness 14.65 17.00 18.90 mm df 59.00 Volume is DLPFC.img Alpha t value threshold 0.1000 3.8476 0.0500 4.1093 0.0100 4.6735
Notes on the implementation
t and Z fields in SPM
The calculations of corrected p values for SPM{Z} values used here are based on t fields rather than Z fields. This is because SPM generates simulated Z statistics from the calculated t field (see SPM course notes, and my SPM statistics page ). As W96 notes, using Gaussian RF results for simulated Z scores gives lower thresholds (and higher false positive rate) than using the t RF results on the underlying t statistics. This code therefore converts Z scores back to t statistics, calculates corrected p values and thresholds using t RF results, and, if necessary, converts t values back to Z scores for display.The current version of SPM (SPM99) takes a similar approach, by calculating thresholds based in the underlying t statistics rather than Z scores.
Note also that vol_corr applies the same corrections as SPM, noted in SmallVolumeCorrection#appropriate_volumes
This software (unlike SPM5 for example) requires the VVOI images to be in in Analyze 7 format (SPM format).
Acknowledgments and warnings
The code here is my own. I have had some help from Keith Worsley and Karl Friston, but any errors are entirely mine. Please let me know of any problems. The code is free under the usual GNU license, the usual disclaimers apply. Thanks to Chris Rorden for his helpful comments.