Deletions are marked like this.  Additions are marked like this. 
Line 10:  Line 10: 
[[TableOfContents]]  <<TableOfContents>> 
Line 56:  Line 56: 
<^>Basic options<^>n<^> <^>Normalise the curvature before computation. Normalisation takes precedence over scaling, so if 'n' is specified in conjunction with 'c' or 'smin'/'smax' [not sure what smin/smax are  GW] it will override the effects of the scaling.[[BR]]If specified in conjunction with 'o outputFileStem>' will also create a curvature file with these values.  <^>Basic options<^>n<^> <^>Normalise the curvature before computation. Normalisation takes precedence over scaling, so if 'n' is specified in conjunction with 'c' or 'smin'/'smax' [not sure what smin/smax are  GW] it will override the effects of the scaling.<<BR>>If specified in conjunction with 'o outputFileStem>' will also create a curvature file with these values. 
Line 61:  Line 61: 
<^>Scaling<^>c<^> <scaleFactor> <^>Scale curvature values with <factor>. The mean of the original curvature is conserved (and the sigma increases with <scaleFactor>).[[BR]][[BR]]If specified in conjunction with 'o <outputFileStem>' will also create a curvature file with these values. <^>Scaling<^>d<^> <minCurvature> <^>d minCurvature e maxCurvature[[BR]]Must be used together. (Note to RP: If both args are required, why not make this a single flag with two args? GW)[[BR]][[BR]]Scale curvature values between <minCurvature> and <maxCurvature>. If the minimum curvature is greater than the maximum curvature, or if either is unspecified, these flags are ignored.[[BR]][[BR]]This scale computation takes precedence over 'c' scaling. [[BR]][[BR]]Note also that the final scaling bounds might not correspond to <minCurvature>... <maxCurvature> since values are scaled across this range so as to preserve the original mean profile.[[BR]][[BR]]If specified in conjunction with 'o <outputFileStem>' will also create a curvature file with these values. 
<^>Scaling<^>c<^> <scaleFactor> <^>Scale curvature values with <factor>. The mean of the original curvature is conserved (and the sigma increases with <scaleFactor>).<<BR>><<BR>>If specified in conjunction with 'o <outputFileStem>' will also create a curvature file with these values. <^>Scaling<^>d<^> <minCurvature> <^>d minCurvature e maxCurvature<<BR>>Must be used together. (Note to RP: If both args are required, why not make this a single flag with two args? GW)<<BR>><<BR>>Scale curvature values between <minCurvature> and <maxCurvature>. If the minimum curvature is greater than the maximum curvature, or if either is unspecified, these flags are ignored.<<BR>><<BR>>This scale computation takes precedence over 'c' scaling. <<BR>><<BR>>Note also that the final scaling bounds might not correspond to <minCurvature>... <maxCurvature> since values are scaled across this range so as to preserve the original mean profile.<<BR>><<BR>>If specified in conjunction with 'o <outputFileStem>' will also create a curvature file with these values. 
Line 73:  Line 73: 
<^>Utility<^>h<^> <numberOfBins> <^>If h alone, print usage (''help'') info.[[BR]][[BR]]If specified with argument, prepare a histogram over the range of curvature values, using <numberOfBins> buckets. These are dumped to stdout. See details below under ''Histogram details''. See also p for percentage version.  <^>Utility<^>h<^> <numberOfBins> <^>If h alone, print usage (''help'') info.<<BR>><<BR>>If specified with argument, prepare a histogram over the range of curvature values, using <numberOfBins> buckets. These are dumped to stdout. See details below under ''Histogram details''. See also p for percentage version. 
Line 76:  Line 76: 
<^>Advanced<^>q<^> <maxUlps> <^>The <maxUlps> is used to toggle (enable?  GW) a more rigorous floating point comparison operation in the histogram function. Comparing float values for sorting into bins can at times fail due to number precision issues. If, over the range of comparison some curvature values are not sorted, add <maxUlps>.[[BR]][[BR]]This adds extra function calls to AlmostEqual2sComplement(..) for float comparisons and improves the general accuracy, at a very slight performance penalty.[[BR]][[BR]]You will most likely never have to use this argument, and is for advanced use only. <^>Advanced<^>z<^> <vertexIndex> <^>Sets the curvature values at that index to zero. The 'raw' curvature, as well as the Gaussian and Mean curvatures are set to zero, and min/max values are recomputed.[[BR]][[BR]]This is useful in cases when outliers in the data (particularly evident in Gaussian calculations) skew mean and sigma values. 
<^>Advanced<^>q<^> <maxUlps> <^>The <maxUlps> is used to toggle (enable?  GW) a more rigorous floating point comparison operation in the histogram function. Comparing float values for sorting into bins can at times fail due to number precision issues. If, over the range of comparison some curvature values are not sorted, add <maxUlps>.<<BR>><<BR>>This adds extra function calls to AlmostEqual2sComplement(..) for float comparisons and improves the general accuracy, at a very slight performance penalty.<<BR>><<BR>>You will most likely never have to use this argument, and is for advanced use only. <^>Advanced<^>z<^> <vertexIndex> <^>Sets the curvature values at that index to zero. The 'raw' curvature, as well as the Gaussian and Mean curvatures are set to zero, and min/max values are recomputed.<<BR>><<BR>>This is useful in cases when outliers in the data (particularly evident in Gaussian calculations) skew mean and sigma values. 
Line 94:  Line 94: 
OHSC = <outputFileStem>.<hemi>.<surface>.<curvFile>[[BR]] HSC = <hemi>.<surface>.<curvFile> [[BR]] 
OHSC = <outputFileStem>.<hemi>.<surface>.<curvFile><<BR>> HSC = <hemi>.<surface>.<curvFile> <<BR>> 
Line 101:  Line 101: 
<^><outputFileStem><^>Log only a single mean+sigma. [[BR]]If several curvature files have been specified, log the mean+sigma across all the curvatures.[[BR]]Note also that this file is ''appended'' for each new run.  <^><outputFileStem><^>Log only a single mean+sigma. <<BR>>If several curvature files have been specified, log the mean+sigma across all the curvatures.<<BR>>Note also that this file is ''appended'' for each new run. 
Line 174:  Line 174: 
* Why is "orig" the default for calculating curvatures? Why does Example 6 suggest "smoothwm" instead, rather than "wm" which is the actual result of FS's surfacefinding process?[[BR]]  * Why is "orig" the default for calculating curvatures? Why does Example 6 suggest "smoothwm" instead, rather than "wm" which is the actual result of FS's surfacefinding process?<<BR>> 
Line 246:  Line 246: 
rh.smoothwm.curv.K.crv [[BR]] rh.smoothwm.curv.H.crv [[BR]] rh.smoothwm.sulc.K.crv [[BR]] rh.smoothwm.sulc.H.crv [[BR]] 
rh.smoothwm.curv.K.crv <<BR>> rh.smoothwm.curv.H.crv <<BR>> rh.smoothwm.sulc.K.crv <<BR>> rh.smoothwm.sulc.H.crv <<BR>> 
Line 315:  Line 315: 
["mris_anatomical_stats"]  [[mris_anatomical_stats]] 
Line 327:  Line 327: 
["References/Lastname###"]  [[References/Lastname###]] 
Line 333:  Line 333: 
GrahamWideman[[BR]]  GrahamWideman<<BR>> 
Index
Contents
Software version described:
 $Date: 2007/11/27 21:30:14 $
 $Revision: 1.39 $
Overview
mris_curvature_stats  will primarily compute the mean and variances for a curvature file (or a set of curvature files) (or new curvatures calculated from a specified surface [right?  GW]). These files can be possibly constrained by a label.
Additionally, 'mris_curvature_stats' can report the max/min curvature values, and compute a simple histogram based on these vales.
Curvatures can also be normalised and constrained to a given range before computation.
Gaussian and mean calculations on a surface structure can be performed.
Finally, all output to the console, as well as any new curvatures that result from the above calculations can be saved to a series of text and binarycurvature files. Please see the descriptions of options for more details.
Synopsis
mris_curvature_stats [options] <subjectId> <hemi> <curvFile1> [... <curvFileN]
Arguments
Positional Arguments
subjectId 
Subject Id 
detailed description (eg, help file information) 
hemi 
hemisphere 
rh or lh 
curvFile1..curvFileN 
List of one or more existing curvature files to input 
Note that this program can also calculate (and save) other curvatures from surfaces selected by other options. 
Required Flagged Arguments
I don't think there are any required arguments.  GW
Optional Flagged Arguments
All singlecharacter flags can be upper or lower case.
Category 
Flag 
<Args> 
Description 
Basic options 
a 
<numberOfAverages> 
Average the curvature <numberOfAverages> times. 
Basic options 
f 
<surf_name> 
Set surface (used to calculate curvature) to <surf_name>. Eg: wm, pial etc. Default (if this argument is not supplied) is the orig surface. 
Basic options 
g 

Calculate Gaussian and Mean curvatures (ie: per vertex). Generate curvature output files for these values if used with o. 
Basic options 
l 
<labelFileName> 
(L) Constrain statistics to the region defined in <labelFileName>. 
Basic options 
n 

Normalise the curvature before computation. Normalisation takes precedence over scaling, so if 'n' is specified in conjunction with 'c' or 'smin'/'smax' [not sure what smin/smax are  GW] it will override the effects of the scaling. 
Output 
m 

Output min / max information for the processed curvature. 
Output 
o 
<outputFileStem> 
Specifies that files are to be output, and provides a base (stem) for their filenames. This includes condensed text output, histogram files (MatLAB friendly) and curvature files. See details below under Output Files heading. 
Output 
s 
<summaryCondition> 
Write out stats as <summaryCondition>. (Not sure what this does  GW) 
Output 
writeCurvatureFiles 

Toggle (set? GW) save flag on curvature files 
Scaling 
c 
<scaleFactor> 
Scale curvature values with <factor>. The mean of the original curvature is conserved (and the sigma increases with <scaleFactor>). 
Scaling 
d 
<minCurvature> 
d minCurvature e maxCurvature 
Scaling 
e 
<maxCurvature> 
see d 
Scaling 
postScale 
<postScale> 
Set post scale factor to <postScale> 
Histogram 
b 
<binSize> 
Option modifies h/p behavior. See Histogram details. 
Histogram 
i 
<binStartCurvature> 
Option modifies h/p behavior. See Histogram details. 
Histogram 
j 
<binEndCurvature> 
Option modifies h/p behavior. See Histogram details. 
Histogram 
p 
<numberOfBins> 
Same as h, but use percentage. 
Filters 
highPassFilter 
<highPassFilter> 
Set rectified high pass filter to <highPassFilter>. See About filters. 
Filters 
highPassFilterGaussian 
<highPassFilterGaussian> 
Set rectified high pass Gaussian filter to <highPassFilterGaussian>. See About filters. 
Filters 
lowPassFilter 
<lowPassFilter> 
Set rectified low pass filter to <lowPassFilter>. See About filters. 
Filters 
lowPassFilterGaussian 
<lowPassFilterGaussian> 
Set rectified low pass Gaussian filter to <lowPassFilterGaussian>. See About filters. 
Utility 
h 
<numberOfBins> 
If h alone, print usage (help) info. 
Utility 
u or ? 

Print usage information. 
Utility 
V or version 

Print out version number. 
Advanced 
q 
<maxUlps> 
The <maxUlps> is used to toggle (enable?  GW) a more rigorous floating point comparison operation in the histogram function. Comparing float values for sorting into bins can at times fail due to number precision issues. If, over the range of comparison some curvature values are not sorted, add <maxUlps>. 
Advanced 
z 
<vertexIndex> 
Sets the curvature values at that index to zero. The 'raw' curvature, as well as the Gaussian and Mean curvatures are set to zero, and min/max values are recomputed. 
Output Files
The following was transcribed from source code. Not sure if the variations in File Name Pattern (OHSC, OHS, HS), are accurate.  GW
The actual files that are saved depends on which additional calculation flags have been specified (i.e. normalisation, Gaussian / Mean, scaling).
In the case when a Gaussian/Mean calculation has been performed, 'mris_curvature_stats' will act in a manner similar to 'mris_curvature w'. Though the name of the curvature files that are created are different, the contents are identical to 'mris_curvature w' created files.
In the following OHSC = <outputFileStem>.<hemi>.<surface>.<curvFile>
HSC = <hemi>.<surface>.<curvFile>
etc
All possible files that can be saved are:
File Name Pattern 
Description 
<outputFileStem> 
Log only a single mean+sigma. 
<OHSC>.log 
Full output, i.e the output of each curvature file mean +sigma, as well as min/max as it is processed. 
<OHS>.raw.hist 
Raw histogram file. 'Raw' = the curvature has not been further processed in any manner. 
<OHS>.norm.hist 
Normalised histogram file 
<OHS>.K.hist 
Gaussian curvature histogram file 
<HS>.K.crv 
Gaussian curvature file 
<OHS>.H.hist 
Mean curvature histogram file 
<HS>.H.crv 
Mean curvature file 
<OHS>.scaled.hist 
Scaled curvature histogram file 
<HS>.scaled.crv 
Scaled curv file 
Notes:
 Curvature files are saved to $SUBJECTS_DIR/surf and *not* to the current working directory.
 File names can become quite long and somewhat unwieldy.
Histogram details
Histogram output is controlled by a number of options which work together.
[h <numberOfBins>] [p <numberOfBins]
If specified, prepare a histogram over the range of curvature values, using <numberOfBins> buckets. These are dumped to stdout.
If 'p' is used, then the histogram is expressed as a percentage.
Note that this histogram, working off float values and float boundaries, can suffer from rounding errors! There might be instances when a very few (on average) curvature values might not be sorted.
The histogram behaviour can be further tuned with the following:
[b <binSize>] [i <binStartCurvature] [j <binEndCurvature]
These arguments are only processed iff a 'h <numberOfBins>' has also been specified. By default, <binSize> is defined as
(maxCurvature  minCurvature) / <numberOfBins>
The 'b' option allows the user to specify an arbitrary <binSize>. This is most useful when used in conjunction with the 'i <binStartCurvature>' option, which starts the histogram not at (minCurvature), but at <binStartCurvature>. So, if a histogram reveals that most values seem confined to a very narrow range, the 'b' and 'i' allow the user to 'zoom in' to this range and expand.
If <binStartCurvature> < (minCurvature), then regardless of its current value, <binStartCurvature> = (minCurvature). Also, if (<binStartCurvature> + <binSize>*<numberOfBins> >) (maxCurvature), an error is raised and processing aborts.
The 'j' allows the user to specify an optional end value for the histogram. Using 'i' and 'j' together are the most convenient ways to zoom into a region of interest in a histogram.
About filters
I don't know anything about this.  GW
Notes
It is important to note that some combinations of the command line parameters are somewhat meaningless, such as normalising a 'sulc' curvature file (since it's normalised by definition).
Unresolved Documentation Issues
 What is the relationship between supplying specific curvature files, versus having mris_curvature_stats figure out curvature from a surface file, either supplied by f argument, or the "orig" default?
Why is "orig" the default for calculating curvatures? Why does Example 6 suggest "smoothwm" instead, rather than "wm" which is the actual result of FS's surfacefinding process?
 GW
Examples
Example 1
mris_curvature_stats 801_recon rh curv
For subject '801_recon', determine the mean and sigma for the curvature file on the right hemisphere.
Example 2
mris_curvature_stats m 801_recon rh curv
Same as above, but print the min/max curvature values across the surface.
Example 3
mris_curvature_stats h 20 m 801_recon rh curv
Same as above, and also print a histogram of curvature values over the min/max range, using 20 bins. By replacing the 'h' with 'p', print the histogram as a percentage.
Example 4
mris_curvature_stats h 20 b 0.01 i 0.1 m 801_recon rh curv
Same as above, but this time constrain the histogram to the 20 bins from 0.1 to 0.1, with a bin size of 0.01.
Note that the count / percentage values are taken across the total curvature range and not the constrained window defined by the 'i' and 'b' arguments.
Example 5
mris_curvature_stats G m 801_recon rh curv
Print the min/max curvatures for 'curv', and also calculate the Gaussian and Mean curvatures (also printing the min/max for these).
Example 6
mris_curvature_stats G F smoothwm m 801_recon rh curv
By default, 'mris_curvature_stats' reads the 'orig' surface for the passed subject. This is not generally the best surface for Gaussian determination. The 'F' uses the 'smoothwm' surface, which is a better choice.
Example 7
mris_curvature_stats h 10 G F smoothwm m 801_recon rh curv
Same as above, with the addition of a histogram for the Gaussian and Mean curvatures as well.
Example 8
mris_curvature_stats h 10 G F smoothwm m o foo 801_recon rh curv sulc
Generate several output text files that capture the min/max and histograms for each curvature processed. Also create new Gaussian and Mean curvature files.
In this case, the curvature files created are called:
rh.smoothwm.curv.K.crv
rh.smoothwm.curv.H.crv
rh.smoothwm.sulc.K.crv
rh.smoothwm.sulc.H.crv
and are saved to the $SUBJECTS_DIR/<subjid>/surf directory. These can be reread by 'mris_curvature_stats' using
Example 9
mris_curvature_stats m 801_recon rh smoothwm.curv.K.crv smoothwm.sulc.K.crv
Advanced Examples
'mris_curvature_stats' can also provide some useful side effects. Reading in a curvature, and applying any calculation to it (scaling, gaussian, etc.) can result in data that can be visualised quite well in a tool such as 'tksurfer'.
Consider the normal curvature display in 'tksurfer', which is usually quite dark due to the dynamic range of the display. We can considerably improve the brightness by scaling a curvature file and rendering the resultant in 'tksurfer'.
First, take an arbitrary curvature, apply a scale factor, and an output filestem:
mris_curvature_stats o foo c 10 801_recon rh curv
This scales each curvature value by 10. A new curvature file is saved in
$SUBJECTS_DIR/801_recon/surf/rh.orig.curv.scaled.crv
Comparing the two curvatures in 'tksurfer' will clearly show the scaled file as much brighter.
Similarly, the Gaussian curvature can be processed, scaled, and displayed, yielding very useful visual information. First create and save a Gaussian curvature file (remember that the smoothwm surface is a better choice than the default orig surface):
mris_curvature_stats o foo G F smoothwm 801_recon rh curv
The 'foo' filestem is ignored when saving curvature files, but needs to be specified in order to trigger output saving. This command will create Gaussian and Mean curvature files in the $SUBJECTS_DIR/surf directory:
rh.smoothwm.curv.K.crv rh.smoothwm.curv.H.crv
Now, process the created Gaussian with the scaled curvature:
mris_curvature_stats o foo c 10 801_recon rh smoothwm.curv.K.crv
Again, the 'foo' filestem is ignored, but needs to be specified to trigger the save. The final scaled Gaussian curvature is saved to (again in the $SUBJECTS_DIR/801_recon/surf directory):
rh.orig.smoothwm.curv.K.crv.scaled.crv
which is a much better candidate to view in 'tksurfer' than the original Gaussian curvature file.
Bugs
None
See Also
Links
Methods Description
description description
References
Reporting Bugs
Report bugs to <analysisbugs@nmr.mgh.harvard.edu>
Author/s
GrahamWideman
(Program author: RudolphPienaar)