Index

Contents

Overview
Synopsis
Arguments
Output Files
Histogram details
About filters
Notes
Unresolved Documentation Issues
Examples
Advanced Examples
Bugs
See Also
Links
Methods Description
References
Reporting Bugs
Author/s

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. 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>). If specified in conjunction with '-o <outputFileStem>' will also create a curvature file with these values.
Scaling	-d	<minCurvature>	-d minCurvature -e maxCurvature Must be used together. (Note to RP: If both args are required, why not make this a single flag with two args? --GW) 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. This scale computation takes precedence over '-c' scaling. 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. 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. 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>. This adds extra function calls to AlmostEqual2sComplement(..) for float comparisons and improves the general accuracy, at a very slight performance penalty. 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. 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>
HSC = <hemi>.<surface>.<curvFile>
etc

All possible files that can be saved are:

File Name Pattern	Description
<outputFileStem>	Log only a single mean+-sigma. If several curvature files have been specified, log the mean+-sigma across all the curvatures. 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?

-- 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 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

Links

FreeSurfer

Methods Description

description
description

References

References/Lastname###

Reporting Bugs

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

Author/s

GrahamWideman
(Program author: RudolphPienaar)