## Note: This page was created with the CommandTemplate
##
## If you're modifying this page please take a look at the
## latest version of CommandTemplate to ensure that you're
## using the latest version of the CommandTemplate
##
## See HelpOnCommandTemplate for description of formatting

'''Index'''
<<TableOfContents>>

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 binary-curvature 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 single-character 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.<<BR>>If specified in conjunction with '-o outputFileStem>' will also create a curvature file with these values.||
||<^>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>).<<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||<^>-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.<<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||<^>-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>.<<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.||

= 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><<BR>>
HSC  = <hemi>.<surface>.<curvFile> <<BR>>
etc

All possible files that can be saved are:

||<^>'''File Name Pattern'''||<^>'''Description'''||
||<^><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.||
||<^><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 surface-finding process?<<BR>>
-- 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 <<BR>>
rh.smoothwm.curv.H.crv <<BR>>    
rh.smoothwm.sulc.K.crv <<BR>>
rh.smoothwm.sulc.H.crv <<BR>>    

and are saved to the $SUBJECTS_DIR/<subjid>/surf directory. 
These can be re-read 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 =
[[mris_anatomical_stats]]

= Links =
FreeSurfer

= Methods Description =
{{{
description
description
}}}

= References =
[[References/Lastname###]]

= Reporting Bugs =
Report bugs to <analysis-bugs@nmr.mgh.harvard.edu>

= Author/s =
GrahamWideman<<BR>>
(Program author: RudolphPienaar)