

hist {base}                                  R Documentation

_H_i_s_t_o_g_r_a_m_s

_D_e_s_c_r_i_p_t_i_o_n_:

     The generic function `hist' computes and plots (if
     `plot=T') a histogram of the given data values.

_U_s_a_g_e_:

     hist(x, ...)
     hist.default(x, breaks, freq = NULL, probability = !freq,
          include.lowest = TRUE, right = TRUE,
          col = NULL, border = par("fg"),
          main = paste("Histogram of" , deparse(substitute(x))),
          xlim = range(breaks),  ylim = range(counts, 0),
          xlab = deparse(substitute(x)),  ylab,
          axes = TRUE, plot = TRUE, labels = FALSE,
          nclass = NULL, ...)

_A_r_g_u_m_e_n_t_s_:

       x: a vector of values for which the histogram is
          desired.

  breaks: either a single number giving the approximate num-
          ber of cells for the histogram or a vector giving
          the breakpoints between histogram cells.

    freq: logical; if `TRUE', the histogram graphic is to
          present a representation of frequencies, i.e, the
          `counts' component of the result; if `FALSE', rel-
          ative frequencies (``probabilities''), the
          `rel.freqs', are plotted.   Defaults to `TRUE' iff
          `breaks' are equidistant.

probability: an alias for `!freq', for S compatibility.

include.lowest: logical; if `TRUE', an `x[i]' equal to the
          `breaks' value will be included in the first (or
          last, for `right = FALSE') bar.

   right: logical; if `TRUE', the histograms cells are
          right-closed (left open) intervals.

     col: a colour to be used to fill the bars.  The default
          of `NULL' yields unfilled bars.

  border: the color of the border around the bars.

main,xlab,ylab: these arguments to `title' have useful
          defaults here.

xlim,ylim: the range of x and y values with sensible
          defaults.

    plot: logical.  If `TRUE' (default), a histogram is
          plotted, otherwise a list of breaks and counts is
          returned.

  labels: logical.  Additionally draw labels on top of bars,
          if `TRUE'.

  nclass: numeric (integer).  For S compatibility only,
          `nclass=n' is equivalent to `breaks=n' (n scalar).

     ...: further graphical parameters to `title' and
          `axis'.

_D_e_t_a_i_l_s_:

     If `right = TRUE' (default), the histogram cells are
     intervals of the form `(a,b]', i.e. they include their
     right-hand endpoint, but not their left one, with the
     exception of the first cell when `include.lowest' is
     `TRUE'.

     For `right = FALSE', the intervals are of the form
     `[a,b)', and `include.lowest' really has the meaning of
     ``include highest''.

_V_a_l_u_e_:

     a list with components

  breaks: the n+1 cell boundaries (= `breaks' if that was a
          vector).

  counts: n integers; for each cell, the number of `x[]'
          inside.

intensities: values f^(x[i]), as estimated density values.
          If `all(diff(breaks) == 1)', they are the relative
          frequencies `counts/n' and in general satisfy
          sum[i; f^(x[i]) (b[i+1]-b[i])] = 1, where
          b[i]=`breaks[i]'.

    mids: the n cell midpoints; useful for plotting.

_N_o_t_e_:

     The resulting value does not depend on the values of
     the arguments `freq' (or `probability') or `plot'.
     This is intentionally different from S.

_S_e_e _A_l_s_o_:

     `stem', `density'.

_E_x_a_m_p_l_e_s_:

     data(islands)
     op <- par(mfrow=c(2,2))
     hist(islands)
     str(hist(islands, col="gray", labels = TRUE))

     hist(sqrt(islands), br = 12, col="lightblue", border="pink")
     ##-- For non-equidistant breaks, counts should NOT be graphed unscaled:
     r <- hist(sqrt(islands), br = c(4* 0:5,10* 3:5,70,100,140), col='blue1')
     text(r$mids, r$intensities, r$counts, adj=c(.5,-.5), col='blue3')
     sapply(r[2:3],sum)
     sum(r$intensities * diff(r$breaks)) # == 1
     par(op)

     str(hist(islands, plot= F))
     str(hist(islands, br=12, plot= F))
     str(hist(islands, br=c(12,20,36,80,200,1000,17000), plot = F))
     str(hist(islands, br=c(12,20,36,80,200,1000,17000), freq = TRUE))#warning

