Differences between revisions 10 and 11
Deletions are marked like this. Additions are marked like this.
Line 35: Line 35:
Line 46: Line 47:
||Category||Flag|| Arguments ||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.||
||Basic options||-g|| ||Calculate Gaussian and Mean||
||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' 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 what files to output and how to name them. 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[[BR]]-?|| ||Print usage information.||
||Utility||-V[[BR]]-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 calcuations) skew mean and sigma values.||
MMTable
||<^>
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.||
||<^>Basic options||<^>-g||<^> ||<^>Calculate Gaussian and Mean||
||<^>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' 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 what files to output and how to name them. 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
-?||<^> ||<^>Print usage information.||"
"||<^>Utility||<^>-V
-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 calcuations) skew mean and sigma values.||

Index TableOfContents

Overview

mris_curvature_stats - will primarily compute the mean and variances for a curvature file (or a set of curvature files). 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.

MMTable

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.

Basic options

-g

Calculate Gaussian and Mean

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' it will override the effects of the scaling.BRIf 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 what files to output and how to name them. 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>).BRBRIf specified in conjunction with '-o <outputFileStem>' will also create a curvature file with these values.

Scaling

-d

<minCurvature>

-d minCurvature -e maxCurvatureBRMust be used together. (Note to RP: If both args are required, why not make this a single flag with two args? --GW)BRBRScale 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.BRBRThis scale computation takes precedence over '-c' scaling. BRBRNote 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.BRBRIf 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.BRBRIf 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 -?||<^> ||<^>Print usage information.||" "||<^>Utility||<^>-V -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>.BRBRThis adds extra function calls to AlmostEqual2sComplement(..) for float comparisons and improves the general accuracy, at a very slight performance penalty.BRBRYou 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.BRBRThis is useful in cases when outliers in the data (particularly evident in Gaussian calcuations) skew mean and sigma values.

Outputs

volume1

description

volume2

description

Description

description

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

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

["othercommand1"], ["othercommand2"]

Links

FreeSurfer

Methods Description

description
description

References

["References/Lastname###"]

Reporting Bugs

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

Author/s

GrahamWidemanBR (Program author: RudolphPienaar)

mris_curvature_stats (last edited 2008-04-29 11:45:53 by localhost)