Contents

hist()

Usage:

hist(x [, nbars] [,keyword phrases]), REAL vector x, integer nbars >= 2
hist(x, vector(anchor,width) [,keyword phrases]), anchor REAL scalar,
  width > 0 scalar
hist(x, edges [,keyword phrases]), edges REAL vector with increasing
  elements
Keyword phrases are relfreq:T, freq:T, leftendin:T, outsideok:T, draw:T,
  save:T plus most graphics keywords

Keywords: distribution graphs, bar graphs

hist(x, nbars) draws a histogram of the data in REAL vector x using with
nbars equal-width bars which include all data.  The bar edges are not
"neat".  For example, 1,1.5,2,2.5,3.0, ... are "neat", 2.71,3.82, 4.93,
6.04, ... are not "neat".

The default bar heights are in the so called "density scale" with height
= (M/N)/W, where M is the number of values in a bar with width W and N
is the number of non-MISSING values in x.  This choice makes the total
area of the bars = 1.  You can use keywords 'freq' and 'relfreq' (see
below) to get other bar heights.

A value x is included in bar i when L[i] < x <= R[i], where L and R are
vectors of the left and right edges of the bars.

hist(x, nbars, leftendin:T) does the same, except a value x is included
in bar i when L[i] <= x < R[i].  'leftendin:T' can be used with any
variant of hist() arguments and other keywords.

hist(x, nbars, freq:T) and hist(x, nbars, relfreq:T) do the same except
that bar heights are frequencies (M) or relative frequencies (M/N) with
no adjustment for bar width.  'freq:T' and 'relfreq:T' can be used with
any variant of hist() arguments.

hist(x [,keyword phrases]) does the same using floor(log2(N)) + 1 bars.

hist(x, vector(anchor, width) [,keyword phrases]) does the same, except
the edges of the bars are of the form anchor + j*width, with the lowest
and highest bar edges chosen to include all the data.

hist(x, Edges [,keyword phrases]) draws a histogram whose bar boundaries
are the elements of REAL vector Edges with length(Edges) > 2 and
satisfying Edges[i] < Edges[i+1].  The number of bars is nbars =
length(Edges) - 1.  A warning message is printed when bar widths are
not all equal and 'relfreq:T' or 'freq:T' is an argument.

It is normally an error when extreme data values are outside the bars
defined by Edges.  Without 'leftendin:T' this occurs when min(x) <=
Edges[1] or max(x) > Edges[nbars+1].  With 'leftendin:T', this occurs
when min(x) < Edges[1] or max(x) >= Edges[nbars+1].

hist(x, Edges, outsideok:T) does the same, except it is not an error
when some extreme values are outside the bars defined by Edges.  When
values are outside, a warning message is printed.

All of the usual plotting related keywords, including 'dumb', 'xlab',
'ylab', and 'title', may be used with hist().  See also topics 'graphs',
'graph_keys', 'graph_borders' and 'graph_files'.

result <- hist(x [, bar info] [,hist keywords] [,graphics keywords],
save:T) returns structure(x:xvals, y:yvals, line:T [,graphics keywords])
instead of drawing the histogram.  REAL vectors xvals and yvals are
such that lineplot(xvals,yvals) draws the histogram.  You can force the
histogram to be drawn by also including 'draw:T' as an argument.

An alternate way to specify keyword values is to create a structure
keyValues of keyword values and use 'keys:keyValues' as the only keyword
phrase argument.  For example

  Cmd> keyvals <- structure(xlab:"Bone length",relfreq:T,\
        title:"Bone histogram", ylab:"Relative frequency",save:T)

  Cmd> stuff <- hist(bones,vector(0,.25),keys:keyvals)

does the same as
  Cmd> stuff <- hist(bones,vector(0,.25),xlab:"Bone length",relfreq:T,\
        title:"Bone histogram", ylab:"Relative frequency",save:T)

See also topic panelhist().