.\"                                      Hey, EMACS: -*- nroff -*-
.\" Copyright 1995 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/mincaverage/mincaverage.man1,v 6.3 2004-05-20 21:52:07 bert Exp $
.\"
.TH MINCAVERAGE 1 "$Date: 2004-05-20 21:52:07 $" "" "MINC User's Guide"

.SH NAME
mincaverage - average minc files

.SH SYNOPSIS
.B mincaverage
[<options>] <in1>.mnc [<in2>.mnc...] <out>.mnc

.SH DESCRIPTION
\fIMincaverage\fR averages minc files together. A range of optional 
behaviour is permitted as well: pre-normalizing volumes, creating a 
standard deviation volume, averaging over a specified dimension of the
input files.

.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\-2\fR
Create a MINC 2.0 format output file.
.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 progress information for each chunk of data copied (default).
.TP
\fB\-quiet\fR
Do not print out progress information.
.TP
\fB\-debug\fR
Print extra information (e.g. normalization factors).
.TP
\fB\-filelist\fR \fIfilename\fR
Specify a file containing a list of input file names. If "-" is given, then
file names are read from stdin. If this option is given, then there should be
no input file names specified on the command line. Empty lines in the input
file are ignored.
.TP
\fB\-max_buffer_size_in_kb\fR \fIbuffer-size\fR
Specify the maximum size of the internal buffers (in kbytes). Default is
4096 kbytes.

.SH Output type options
These options control the storage precision and size of individual voxel
values in the output file.
.TP
\fB-filetype\fR
Don't do any type conversion (default).
.TP
\fB\-byte\fR
Write out 8-bit integer values.
.TP
\fB\-short\fR
Write out 16-bit integer values.
.TP
\fB-int\fR
Write out 32-bit integer values.
.TP
\fB\-long\fR
Superseded by -int.
.TP
\fB\-float\fR
Write out single-precision floating point values.
.TP
\fB\-double\fR
Write out double-precision floating point values.
.P
\fB\-signed\fR
Write out values as signed integers (default for short and long). Ignored for
floating point types.
.TP
\fB\-unsigned\fR
Write out values as unsigned integers (default for byte). Ignored for
floating point types.
.TP
\fB\-range\fR \fImin max\fR
specifies the valid range of output voxel values in their integer
representation. Default is the full range
for the type and sign. This option is ignored for floating point
values. For it to have any effect, you must specify a type.

.SH Averaging options
.TP
\fB\-normalize\fR
Normalize volumes to their global average before averaging them (based
on the mean of voxels with value greater than 2 percent of full range
above the minimum).
.TP
\fB\-nonormalize\fR
Do not normalize volumes (default).
.TP
\fB\-sdfile\fR \fIsdfile.mnc\fR
Specify the name of an output standard deviation file, to be
calculated in addition the mean that is normally calculated.
.TP
\fB\-weightfile\fR \fIweightfile.mnc\fR 
Specify an output cumulative voxel weight file (default=none).
.TP
\fB\-copy_header\fR
Copy all of the additional header information from the first input
file (default for one input file).
.TP
\fB\-nocopy_header\fR
Do not copy additional header information (default for many input files).
.TP
\fB\-avgdim\fR \fIdimname\fR
Specify the name of a dimension over which we should be averaging (or
calculating standard deviation). If normalization is done, it still
only applies to separate files only - no normalization is done within
a file.
.TP
\fB\-binarize\fR
Binarize the input volumes before calculating the average. The
binarization is done by specifying a range of values that contribute 1
to the average. Normalization of the input is not permitted when
performing binarization.
.TP
\fB\-binrange\fR \fImin max\fR
Specify the range of values for binarization.
.TP
\fB\-binvalue\fR \fIvalue\fR
Specify a single legal value (integer) for binarization. The range is
set to be +/- 0.5 around this value to achieve an effective rounding
of input values.
.TP
\fB\-ignore_below\fR \fIvalue\fR
Do not include voxels below this value in the average and sd
.TP
\fB\-ignore_above\fR \fIvalue\fR
Do not include voxels above this value in the average and sd
.TP
\fB\-floor\fR \fIvalue\fR
Synonym for \fB\-ignore_below\fR
.TP
\fB\-ignore_above\fR \fIvalue\fR
Synonym for \fB\-ignore_above\fR
.TP
\fB\-weights\fR \fI<w1,w2,...>\fR
Specify a series of weights for averaging. The number of weighting
values must match the number of input files and the values must be
provided as a single argument with commas or spaces as
separators. The sum of the weights must be non-zero. If weights are
used with an averaging dimension, then only one input file can be
specified.
.TP
\fB\-width_weighted\fR
This option can only be used when averaging across a dimension
(\fB-avgdim\fR option). It specifies that weighting should be done using the
width variable that corresponds to the averaging dimension. For
example, using \fB\-width_weighted\fR with \fB\-avgdim\fR time will use the
time-width variable to weight the values.
.TP
\fB\-min_weight\fR \fIvalue\fR
This specifies the minimum weight (number of volumes if no weights are specified) needed for calculating a valid average. If the cumulative weight for a voxel is below this threshold, the average and sd reported will be 0. This would typically be useful if values are excluded using any of the \fB\-ignore\fR options, or by NaN values in the input volume(s).
.TP
\fB\-min_weight_fraction\fR \fIvalue\fR
Same as \fB\-min_weight\fR, but specified as a fraction of the sum of the input weights (or the number of input volumes, if no weight is specified).
.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
Peter Neelin

.SH COPYRIGHTS
Copyright \(co 1995 by Peter Neelin
 

