Next: hpolar() Up: MacAnova Help File Previous: himag()   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
hist(x .... , keys:structure(keyword phrases))
Keyword phrases are relfreq:T, freq:T, leftendin:T, outsideok:T, draw:T,
  save:T plus most graphics keywords



Keywords: plotting, descriptive statistics
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".

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.

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 any 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 anchor +
min(j)*width < min(x) and anchor + min(j) > max(x), with the lowest and
highest bar edges chosen to include all the data.

hist(x, Edges [,keyword phrases]) draws a histogram with bar boundaries
from 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.

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.  Without outsideok:T
this is an error.  A value y is outside the bars when y < Edges[1] or y
> Edges[nbars+1].  Without 'leftendin:T', Edges[1] is outside; with
'leftendin:T', Edges[nbars+1] is outside.

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 ... , save:T [, draw:T] [,graphics keywords]) returns
structure(x:xvals, y:yvals [,graphics keywords], lines:T, yaxis:F) as
value.  REAL vectors xvals and yvals are such that lineplot(xvals,yvals,
yaxis:F [,graphics keywords]) or lineplot(keys:results) draws the
histogram.  Nothing is drawn unless 'draw:T' is also 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> keyValues <- structure(xlab:"Bone length",relfreq:T,\
        title:"Bone histogram", ylab:"Relative frequency",save:T)

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

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().


Gary Oehlert 2003-01-15