R/distShade.R

In helophilus/ColsTools: A variety of convenience tools and short-cuts

#' Shade the area under an existing distribution curve from two values.
#'
#' \code{distShade(xlo, xhi, xvec, yvec, ...)}
#'
#' @param xlo the lower x-axis value where the shading begins
#' @param xhi the higher x-axis value where the shading ends
#' @param xvec the name of the vector of x-axis values
#' @param yvec the name of the vector of y-axis values
#' @param ... further arguments to be passed to the polygon function
#'
#' @details This function is essentially a wrapper for the polygon function
#' allowing the polygon to be drawn below a curve from fewer values.
#' @examples
#' # beta distribution, 90% interval
#' X = 0:100/100
#' Y = dbeta(X, 6, 3)
#' plot(X, Y, type="l")
#' Draws = sample(X, prob=Y, size=10000, replace=TRUE)
#' Qz = quantile(Draws, c(0.05,0.95))
#' distShade(Qz[1], Qz[2], X, Y, col="pink")

distShade = function(xlo,xhi,xvec,yvec,...){
  Xs = c(xlo,xvec[xvec>=xlo & xvec<=xhi],xhi,xlo)
  Ys = c(0,yvec[xvec>=xlo & xvec<=xhi],0,0)
  polygon(Xs,Ys,...)
}