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 |

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