## 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''' <> 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] [... '''Category'''||<^>'''Flag'''||<^> <'''Args'''> ||<^>'''Description'''|| ||<^>Basic options||<^>-a||<^> ||<^>Average the curvature times.|| ||<^>Basic options||<^>-f||<^> ||<^>Set surface (used to calculate curvature) to . 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||<^> ||<^>(-L) Constrain statistics to the region defined in .|| ||<^>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||<^> ||<^>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||<^> ||<^>Write out stats as . (Not sure what this does -- GW)|| ||<^>Output||<^>--writeCurvatureFiles||<^> ||<^>Toggle (set? --GW) save flag on curvature files|| ||<^>Scaling||<^>-c||<^> ||<^>Scale curvature values with . The mean of the original curvature is conserved (and the sigma increases with ).<
><
>If specified in conjunction with '-o ' will also create a curvature file with these values.|| ||<^>Scaling||<^>-d||<^> ||<^>-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 and . 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 ... since values are scaled across this range so as to preserve the original mean profile.<
><
>If specified in conjunction with '-o ' will also create a curvature file with these values.|| ||<^>Scaling||<^>-e||<^> ||<^>see -d|| ||<^>Scaling||<^>--postScale||<^> ||<^>Set post scale factor to || ||<^>Histogram||<^>-b||<^> ||<^>Option modifies -h/-p behavior. See ''Histogram details''.|| ||<^>Histogram||<^>-i||<^> ||<^>Option modifies -h/-p behavior. See ''Histogram details''.|| ||<^>Histogram||<^>-j||<^> ||<^>Option modifies -h/-p behavior. See ''Histogram details''.|| ||<^>Histogram||<^>-p||<^> ||<^>Same as -h, but use percentage.|| ||<^>Filters||<^>--highPassFilter||<^> ||<^>Set rectified high pass filter to . See ''About filters''.|| ||<^>Filters||<^>--highPassFilterGaussian||<^> ||<^>Set rectified high pass Gaussian filter to . See ''About filters''.|| ||<^>Filters||<^>--lowPassFilter||<^> ||<^>Set rectified low pass filter to . See ''About filters''.|| ||<^>Filters||<^>--lowPassFilterGaussian||<^> ||<^>Set rectified low pass Gaussian filter to . See ''About filters''.|| ||<^>Utility||<^>-h||<^> ||<^>If -h alone, print usage (''help'') info.<
><
>If specified with argument, prepare a histogram over the range of curvature values, using 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||<^> ||<^>The 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 .<
><
>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||<^> ||<^>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 = ...<
> HSC = .. <
> etc All possible files that can be saved are: ||<^>'''File Name Pattern'''||<^>'''Description'''|| ||<^>||<^>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.|| ||<^>.log||<^>Full output, i.e the output of each curvature file mean +-sigma, as well as min/max as it is processed.|| ||<^>.raw.hist||<^>Raw histogram file. 'Raw' = the curvature has not been further processed in any manner.|| ||<^>.norm.hist||<^>Normalised histogram file|| ||<^>.K.hist||<^>Gaussian curvature histogram file|| ||<^>.K.crv||<^>Gaussian curvature file|| ||<^>.H.hist||<^>Mean curvature histogram file|| ||<^>.H.crv||<^>Mean curvature file|| ||<^>.scaled.hist||<^>Scaled curvature histogram file|| ||<^>.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 ] [-p 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 ] [-i ' has also been specified. By default, is defined as (maxCurvature - minCurvature) / The '-b' option allows the user to specify an arbitrary . This is most useful when used in conjunction with the '-i ' option, which starts the histogram not at (minCurvature), but at . 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 < (minCurvature), then regardless of its current value, = (minCurvature). Also, if ( + * >) (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//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 = Author/s = GrahamWideman<
> (Program author: RudolphPienaar)