annotate man/man1/stats.1 @ 0:5242703e91d3 tip

Initial checkin for AIM92 aimR8.2 (last updated May 1997).

.TH STATS 1 "1 September 1993"

.SH NAME
stats \-     calculate some statistics.

.SH SYNTAX 
stats [options] [file]

.SH DESCRIPTION
Calculate statistics for given frames of each input file and write the
results on the stdout.
If no filenames are given, one input file is expected on the stdin.
Otherwise each given filename is processed in turn.

.SH OPTIONS

1. frame, width, samplerate

The `frame' option selects a sequence of contiguous frames for processing by:

.nf
	frame=a[-b]
.fi

where `a' and `b' are frame numbers: 1,2,3,...,max  The upper limit `b' is
optional, and when it is missing then the frame sequence is a single
frame, otherwise `a' and `b' are inclusive limits.  The strings "min"
and "max" are recognised as extreme limits.
Each frame has size `width' samples which
may be given with time units (s or ms), in which case the they
are converted to a number of samples using the given `samplerate' option.
The special option value "width=max" is interpreted as a single frame covering
the whole file.

2. type

Datatype for both input and output. Binary types are char, short, int, float, double.
Ascii input (one number per line) is recognised with "type=ascii".

3. stat

The statistics available to the `stat' option are:

.nf
    n           sample (ie. data set) size
    sum         area
    ss          sum of squares
    mean        sum/n
    rms         root mean square: square root of ss/n
    variance    computed with n-1 degrees of freedom
    stddev      standard deviation: square root of variance
    min         minimum value
    max         maximum value
    absmax      maximum absolute value, ie. max( |max|, |min| )
    range       max-min
.fi


The variance is the average squared deviation from the mean value, where the
average is computed by dividing by n-1 for a data set of n samples.
The stddev is the square root of this variance.
The stddev would be equal to the rms value for a data set with zero mean,
except that the average squared value is computed using ss/n, while the
average squared deviation from a zero mean value is computed using ss/(n-1).

Statistics may be given in a comma separated list, for example:

.nf
	stats stat=mean,variance,min,max
.fi

For each frame of each input file this will output the four statistics in the
data type selected by the `type' option.

4. line

When line=on (or -l) output is forced to be ascii irrespective of the `type' option,
and for each file argument in turn stats prints the statistics  requested,
in the order they were requested, on one line.
This makes a table (one line per file), and also helps subsequent operations
between statistics. For example, the standard error of the mean (the stddev
divided by the square root of the sample size) can be computed:

.nf
	stats -l stat=stddev,n  |  awk '{ print $1 / sqrt($2) }'
.fi

Tables can be formatted using field-width and precision arguments which are
included as silent options. For example, to format columns with a precision
of 4 decimal places with each number right-justified in a field-width of
12 characters:

.nf
	stats -l fieldwidth=12 precision=4
.fi

The columns may be left-justified by making the fieldwidth parameter negative.
Output is truncated to integers by setting the precision parameter 0.
For example, to print the sample size of each file as an integer without
setting in a field:

.nf
	stats -l fieldwidth=0 precision=0  stat=n  [files]
.fi

.SH "SEE ALSO"
.LP
options
.SH COPYRIGHT
.LP
Copyright (c) Applied Psychology Unit, Medical Research Council, 1995
.LP
Permission to use, copy, modify, and distribute this software without fee 
is hereby granted for research purposes, provided that this copyright 
notice appears in all copies and in all supporting documentation, and that 
the software is not redistributed for any fee (except for a nominal 
shipping charge). Anyone wanting to incorporate all or part of this 
software in a commercial product must obtain a license from the Medical 
Research Council.
.LP
The MRC makes no representations about the suitability of this 
software for any purpose.  It is provided "as is" without express or 
implied warranty.
.LP
THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL 
THE A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES 
OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, 
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS 
SOFTWARE.