.TH STOCHIST 1carl CARL
.SH NAME
stochist \- plot histogram of stochastic function on CRT terminal
.SH SYNOPSIS
.B stochist
[
.B -lN
] [
.B -uN
] [
.B -nN
] [
.B -f
]
< floatsams > text or floatsams
.SH DESCRIPTION
Input must be file or pipe of floatsams.
If output is a terminal, a text histogram is produced.
If output is file or pipe, histogram sums are written as floatsams.
flags: (default)
.TP
.B -lN
set lower bound of display to N (-3.0)
.TP
.B -uN
set upper bound of display to N (3.0)
.TP
.B -nN
set number of histogram windows to N (22)
.TP
.B -f
force writing text bar graph
.PP
.B stochist 
plots a histogram of an arbitrary function on a CRT terminal.  It is
a convenient way of observing, e.g., the output of 
.I cannon(1carl).
It's function is specifically for viewing stochastic functions, not for
observing the behavior of signals.  To generate histograms of signals,
see
.I hist(1carl)
.PP
Example usage:
.RS .5i
% cannon gauss | stochist
.RE
.PP
The operation of
.B stochist
is to construct a grid of numerical ranges, called windows, and to compare the
numbers read in from the standard input against those windows, maintaining
a count of how many numbers fall into each window.  When the standard input
is exhausted, a display of the number of hits in each window is produced
on the standard output in the form of a horizontal bar graph.
.PP
The number and extent of the grid ranges is determined as 
.EQ
{ u - l } over w
.EN
where 
.I u 
is the upper bound, 
.I l 
the lower bound, and
.I w
is the number of windows.  There will be one bar in the resulting graph
for each 
.I w.
.I (w
defaults to 22, so the display will just fill the screen on a 24-line
display).
.PP
When the output of 
.B stochist
is a file or pipe, the numerical value of the
window counts are output instead of the bar graph
representation.
.PP
Some statistics are kept on the histogram which are printed as a line
after the bar graph.  These values are: the actual minimum and maximum
values read in, 
the value and location of the mode (window with the greatest
number of hits), the mean, and the number of samples, respectively.
.SH AUTHOR
Gareth Loy
.SH SEE ALSO
cannon(1carl)
hist(1carl)
.SH DIAGNOSTICS
Input must be a file or pipe.  This and any error in input flags generate
a usage statement.
