R/plot.histogram.R

In HenrikBengtsson/R.basic: [R] Class Library - Stand-alone basic functions [DEPRECATED]

#########################################################################/**
# @class histogram
# @RdocMethod plot
#
# @title "Plots a histogram"
#
# @synopsis
#
# \description{
#   This function redefines the \code{plot.histogram} function
#   in the \R base package by adding the two arguments \code{width} and
#   \code{offset}. The function is modified in such a way that it is
#   backward compatible, i.e. if you do not use the arguments \code{width}
#   and \code{offset} the plot will look the same as the plot generated by
#   the original function. Note that \code{plot.histogram} is called by
#   \code{hist}.
# }
#
# \arguments{
#   \item{x}{a `histogram' object, or a @list with components
#       \code{intensities}, \code{mid}, etc, see @see "graphics::hist".}
#   \item{freq}{@logical; if @TRUE, the histogram graphic is to present
#       a representation of frequencies, i.e, \code{x$counts}; if
#       @FALSE, relative frequencies ("probabilities"), i.e.,
#       \code{x$intensities}, are plotted. The default is true for
#       equidistant \code{breaks} and false otherwise.}
#   \item{density}{the density of shading lines, in lines per inch.
#       If @NULL, no shading lines are drawn.
#       Non-positive values also inhibit the drawing of shading lines.}
#   \item{angle}{the slope of shading lines, given as an angle in degrees
#       (counter-clockwise).}
#   \item{col}{a colour to be used to fill the bars.  The default of
#       @NULL yields unfilled bars.}
#   \item{border}{the color of the border around the bars.}
#   \item{width}{The relative width of each bar compared to the full width.
#       \code{1.0} is full width. Default value is \code{1.0}.}
#   \item{offset}{The relative horisontal offset of each bar compared to the
#       full width. A value of \code{0.0} places each bar to the very left.
#       A value of \code{1.0-width} places each bar to the very right.
#       Default value is \code{(1.0-offset)/2}, i.e. the bars are centered.}
#   \item{lty}{the line type used for the bars, see also \code{lines}.}
#   \item{xlim, ylim}{the range of x and y values with sensible defaults.}
#   \item{main, sub, xlab, ylab}{these arguments to \code{title} have useful
#       defaults here.}
#   \item{axes}{logical, indicating if axes should be drawn.}
#   \item{labels}{logical or character.  Additionally draw labels on top of
#       bars, if not @FALSE; if @TRUE, draw the counts or
#       rounded intensities; if \code{labels} is a @character, draw
#       itself.}
#   \item{add}{logical. If @TRUE, only the bars are added to the
#       current plot. This is what \code{lines.histogram(*)} does.}
#   \item{...}{further graphical parameters to \code{title} and \code{axis}.}
# }
#
# \author{
#   Modified by @get "author", from the original \R plot.histogram.
# }
#
# \examples{
#   x1 <- rnorm(1000,  0.4, 0.8)
#   x2 <- rnorm(1000,  0.0, 1.0)
#   x3 <- rnorm(1000, -1.0, 1.0)
#   hist(x1, width=0.33, offset=0.00, col="blue", xlim=c(-4,4),
#    main="Histogram of x1, x2 & x3", xlab="x1 - blue, x2 - red, x3 - green")
#   hist(x2, width=0.33, offset=0.33, col="red", add=TRUE)
#   hist(x3, width=0.33, offset=0.66, col="green", add=TRUE)
# }
#
# \seealso{
#   See also original @see "graphics::plot.histogram".
# }
#
# @keyword "hplot"
#*/#########################################################################
setMethodS3("plot", "histogram", function (x, freq = equidist, density = NULL, angle = 45, col = NULL, border = par("fg"), lty = NULL, main = paste("Histogram of", x$xname), sub = NULL, xlab = x$xname, ylab, xlim = range(x$breaks), ylim = NULL, axes = TRUE, labels = FALSE, add = FALSE, width=1.0, offset=(1.0-width)/2, ...) {
    equidist <- if (is.logical(x$equidist))
        x$equidist
    else {
        h <- diff(x$breaks)
        diff(range(h)) < 1e-07 * mean(h)
    }
    if (freq && !equidist)
        warning("the AREAS in the plot are wrong -- rather use `freq=FALSE'!")
    y <- if (freq)
        x$counts
    else {
        y <- x$density
        if (is.null(y))
            x$intensities
        else y
    }
    nB <- length(x$breaks)
    if (is.null(y) || 0 == nB)
        stop("`x' is wrongly structured")
    if (!add) {
        if (is.null(ylim))
            ylim <- range(y, 0)
        if (missing(ylab))
            ylab <- if (!freq)
                "Density"
            else "Frequency"
        plot.new()
        plot.window(xlim, ylim, "")
        title(main = main, sub = sub, xlab = xlab, ylab = ylab,
            ...)
        if (axes) {
            axis(1, ...)
            axis(2, ...)
        }
    }

    # ---- BEGIN Required modifications ---- #
    if (width != 1.0 || offset != 0) {
      # Calculates the width of each bar in the histogram
      delta.breaks <- x$breaks[-1] - x$breaks[-nB];
      x.offset <- offset * delta.breaks;
      x.width <- width * delta.breaks;
      x <- x$breaks[-nB]+x.offset;
      rect(x, 0, x+x.width, y, col=col, border=border, angle = angle, density = density, lty=lty);
    } else {
      # As before
      rect(x$breaks[-nB], 0, x$breaks[-1], y, col = col, border = border,
          angle = angle, density = density, lty = lty)
    }
    # ----- END Required modifications ----- #

    if ((logl <- is.logical(labels) && labels) || is.character(labels))
        text(x$mids, y, labels = if (logl) {
            if (freq)
                x$counts
            else round(x$density, 3)
        }
        else labels, adj = c(0.5, -0.5))
    invisible()
}) # plot.histogram


if (isPackageInstalled("graphics")) {
  # For R v1.9.0 and after we need to copy hist.default() "out from" the
  # namespaced graphics package, otherwise hist() will call
  # base::plot.histogram().
  # Easiest is simply to assure that graphics is loaded.
  hist.default <- function(...) {
    graphics::hist.default(...);
  }
}


############################################################################
# HISTORY:
# 2013-05-30
# o CLEANUP: Now local hist.default() is a wrapper calling
#   graphics::hist.default() instead of being a copy of it.
# 2005-02-20
# o Now using setMethodS3().
# 2004-04-21
# o BUG FIX for Rv1.9.0: hist.default() does not exists because graphics
#   is not loaded from start.
# 2004-04-15
# o BUG FIX for Rv1.9.0: plot.histogram was not found because it is now
#   a private function in graphics (former in base).
# 2003-04-13
# o Updated the Rdoc comments.
# 2003-04-10
# o Now hist.default() is also overloaded.
# 2002-10-25
# o Updated the example to include one more color.
# 2002-01-18
# * Updated to be the same as the [R] v1.4.0 version.
# 2001-07-27
# * Moved into R.base.
# 2001-06-18
# * Created.
############################################################################