.\"                                      Hey, EMACS: -*- nroff -*-
.\" Copyright 2001 Peter Neelin, McConnell Brain Imaging Centre,
.\" Montreal Neurological Institute, McGill University.
.\" Permission to use, copy, modify, and distribute this
.\" software and its documentation for any purpose and without
.\" fee is hereby granted, provided that the above copyright
.\" notice appear in all copies.  The author and McGill University
.\" make no representations about the suitability of this
.\" software for any purpose.  It is provided "as is" without
.\" express or implied warranty.
.\"
.\" $Header: /private-cvsroot/minc/progs/mincstats/mincstats.man1,v 1.5 2004-05-20 21:52:09 bert Exp $
.\"
.TH MINCSTATS 1 "$Date: 2004-05-20 21:52:09 $" "" "MINC User's Guide"

.SH NAME
mincstats - calculate simple statistics across voxels of a minc file

.SH SYNOPSIS
.B mincstats
[<options>] <in1>.mnc

.SH DESCRIPTION
\fIMincstats\fR
will calculate simple statistical measures across all voxels of a minc
file. Note that these are global statistical measures and not
voxel-by-voxel measures (see \fImincaverage\fR for that). By default all
statistics are calculated. If any statistics are requested via a
command-line option, then only the requested statistics are printed.

A very useful feature of this program is the ability to restrict the
set of voxels included in the statistic calculation, either by restricting
the range of included values, or by using a mask file with a restricted
range. Multiple ranges for the input file or mask file can be
specified. For each range of included volume values, and for each range of
mask values, the relevant statistics are printed out (n*m values,
where n is the number of volume ranges and m the number of mask
ranges). These calculations are done in a single pass through the
data, so specifying multiple ranges is much faster than running the
program repeatedly. This is quite helpful when calculating many
regional averages with a VOI mask volume.

Special mention should be given to histograms and related statistical
measures. The default range of the histogram is from the smallest
value in the file to the largest. In the not uncommon, but special,
case when the number of histogram bins exactly matches the number of
possible values in the file (e.g. 256 bins for full-range byte data),
the histogram can end up with some odd features when using the default
histogram range. This arises from the discretization of the data that
are then rebinned into a slightly mismatched histgram. For the example
of byte data, the values that should be used are 256 bins and a
histogram range that extends half a bin below the smallest value and
half a bin above the largest. Use option \fB-discrete_histogram\fR to work
this out automatically, or use \fB-integer_histogram\fR to have bins of unit
width if the input data are inherently integer (e.g. label data). In
general, one should be careful about the rebinning of discretized data
to a histogram with a bin size that is close to the level of
discretization.

.SH OPTIONS
Note that options can be specified in abbreviated form (as long as
they are unique) and can be given anywhere on the command line.

.SH General options
.TP
\fB\-clobber\fR
Overwrite an existing file.
.TP
\fB\-noclobber\fR
Don't overwrite an existing file (default).
.TP
\fB\-verbose\fR
Print out extra information (more than the default).
.TP
\fB\-quiet\fR
Print out only the requested numbers
.TP
\fB\-max_buffer_size_in_kb\fR\ \fIsize\fR
Specify the maximum size of the internal buffers (in kbytes). Default
is 4 MB.

.SH Invalid value options
.TP
\fB\-ignore_nan\fR
Exclude invalid values (outside valid range) from statistic
calculations. This is the default.
.TP
\fB\-include_nan\fR
Treat invalid values as zeros and include them in statistic calculations.
.TP
\fB\-replace_nan\fR\ \fIvalue\fR
Replace invalid values with the specified value and include the new
value in statistic calculations.

.SH Volume range options
.TP
\fB\-floor\fR\ \fImin1\fR,\fImin2\fR,...
Comma-separated list of lower bounds for ranges of data to include in
statistic calculation.
.TP
\fB\-ceil\fR\ \fImax1\fR,\fImax2\fR,...
Comma-separated list of upper bounds for ranges of data to include in
statistic calculation.
.TP
\fB\-range\fR\ \fImin1\fR,\fImax1\fR,\fImin2\fR,\fImax2\fR,...
Comma-separated list of lower and upper bounds for ranges of data to
include in statistic calculation.
.TP
\fB\-binvalue\fR \fIval1\fR,\fIval2\fR,...
Comma-separated list of integer values to include in statistic
calculation. A range of +/- 0.5 is defined around each specified value.
.TP
\fB\-mask\fR\ \fIfilename.mnc\fR
Name of file to be used for masking data included in statistic
calculation. For this to have any effect, you must specify a mask
range with one of the following options.
.TP
\fB\-mask_floor\fR\ \fImin1\fR,\fImin2\fR,...:
Like \fB\-floor\fR, but applied to the mask file.
.TP
\fB\-mask_ceil\fR\ \fImax1\fR,\fImax2\fR,...
Like \fB\-ceil\fR, but applied to the mask file.
.TP
\fB\-mask_range\fR\ \fImin1\fR,\fImax1\fR,\fImin2\fR,\fImax2\fR,...
Like \fB\-range\fR, but applied to the mask file.
.TP
\fB\-mask_binvalue\fR\ \fIval1\fR,\fIval2\fR,...
Like \fB\-binvalue\fR, but applied to the mask file.

.SH Histogram options
.TP
\fB\-histogram\fR\ \fIfilename\fR
Specify the name of a file into which the histogram is written. If
multiple ranges or mask ranges are specified, then all histograms are
written in this file, separated by blank lines. Information
describing each histogram is written before it in lines starting with
the hash (pound) character. These files can be loaded into gnuplot.
.TP
\fB\-hist_bins\fR \fInumber-of-bins\fR
Specify number of bins in histogram.
.TP
\fB-bins\fR \fInumber-of-bins\fR
Synonym for \fB\-hist_bins\fR.
.TP
\fB\-hist_floor\fR\ \fImin\fR
Specify lower bound for histogram.
.TP
\fB\-hist_ceil\fR\ \fImax\fR
Specify upper bound for histogram.
.TP
\fB\-hist_range\fR\ \fImin\fR\ \fImax\fR
Specify a range for the histogram
.TP
\fB\-integer_histogram\fR
Create bins of unit width, centred around integer values. This is
useful for integer data such as labels. The histogram range is rounded
to the nearest integer, then the min is lowered and the max is raised
by 0.5. The number of bins is taken as the difference of these two
values.  Note that 0.01 is added to the minimum and subtracted from the
maximum prior to the rounding in order to ensure that a correctly
specified range (e.g. [0.5,255.5]) is preserved. If you want to have
integer bins that are wider than one, you will have to work out the
histogram range and number of bins yourself and not use this option.
.TP
\fB\-discrete_histogram\fR
Attempt to match the histogram to the discretization of the input
data. This is appropriate for continuous data that are stored in an
integer representation and when a bin width close to the discretization is
desired. This is similar to \fB\-integer_histogram\fR, except that the the
histogram range is first converted to voxel values which are rounded
and extended by half a bin on either side. This new voxel range is
then converted back to real values. The number of bins is taken as the
difference in the voxel value range. Note that this does not account
for variations in slice-to-slice scaling, so odd histogram effects may
still occur. This option is intended to give behaviour similar to that of
\fIvolume_stats\fR.
.TP
\fB\-int_max_bins\fR \fInumber-of-bins\fR
Specify the largest histogram that can be automatically sized with the
above options. The limit prevents accidental creation of huge
histograms.  This option replaced the old
\fB-max_bins\fR option in MINC 1.1.

.SH Basic statistics
.TP
\fB\-all\fR
Compute all statistical measures. This is the default.
.TP
\fB\-none\fR
Synonym for \fB\-count\fR (for similarity to volume_stats). Note that
although this was necessary for \fIvolume_stats\fR, it is not needed here,
since specifying any of these options automatically turns off \fB\-all\fR
.TP
\fB\-count\fR
Count the number of voxels that are within the range and mask.
.TP
\fB\-percent\fR
Print the percentage of voxels within the range and mask
.TP
\fB\-volume\fR
Print the volume of the voxels within the range and mask (in mm-cubed).
.TP
\fB\-min\fR
Print the minimum value.
.TP
\fB\-max\fR
Print the maximum value.
.TP
\fB\-sum\fR
Print the sum of all values.
.TP
\fB\-sum2\fR
Print the sum of the squares of all values.
.TP
\fB\-mean\fR
Print the mean.
.TP
\fB\-variance\fR
Print the variance.
.TP
\fB\-stddev\fR
Print the standard deviation.
.TP
\fB\-CoM\fR
Print the centre of mass. Both the voxel coordinate and the world
coordinates are printed. The voxel coordinates are printed in file
order, whilst the world coordinates are printed in x,y,z order.
.TP
\fB\-com\fR
Synonym for \fB\-CoM\fR.
.TP
\fB\-world_only\fR
Print the centre of mass in world coordinates only.

.SH Histogram statistics
.P
Note that histogram statistics are derived solely from the histogram
counts and bin centres, so results such as the median will not be
exactly the same as the true value for all included voxels. For
example, the error on the median can be as large as a half bin
width. Furthermore, if the histogram range is less than that of
included voxels, then the result applies only to voxels included in
the histogram.
.TP
\fB\-hist_count\fR
Print number of voxels in histogram. This may be different from the
number of included and masked voxels if the histogram range is less
than the range of the included data.
.TP
\fB\-hist_percent\fR
Print percentage of voxels included in histogram.
.TP
\fB\-median\fR
Print the histogram median.
.TP
\fB\-majority\fR
Print the bin centre (intensity value) for the bin with the most counts.
.TP
\fB\-biModalT\fR
Print the bi-modal threshold calculated using the method described in
Otsu N, "A Threshold Selection Method from Grey-level Histograms",
IEEE Trans on Systems, Man and Cybernetics. 1979, 9:1; 62-66.
.TP
\fB\-pctT\fR
Print the threshold needed for a particular critical percentage of the
histogram.
.TP
\fB\-entropy\fR
Print the Shannon entropy.

     H(x) = - Sum(P(i) * log2(P(i))

where P(i) is the bin probability

.SH Generic options for all commands:
.TP
\fB\-help\fR
Print summary of command-line options and exit.
.TP
\fB\-version\fR
Print the program's version number and exit.

.SH AUTHOR
Andrew Janke

.SH COPYRIGHTS
.P
Program: Copyright \(co 2000 by Andrew Janke
.P
Man page: Copyright \(co 2001 by Peter Neelin