densregion {denstrip}

Density regions

Description

A density region uses shading to represent the uncertainty surrounding a continuously-varying quantity, such as a survival curve or a forecast from a time series. The darkness of the shading is proportional to the (posterior, predictive or fiducial) density. This function adds a density region to an existing plot.

Usage

densregion(x, ...)
## Default S3 method:
densregion(x, y, z, pointwise=FALSE, nlevels=100, 
                   colmax=par("fg"), colmin="white", scale=1, gamma=1,
                   contour=FALSE, ...)

Arguments

x

Suppose the continuously-varying quantity varies over a space S. x is a vector of the points in S at which the full posterior / predictive / fiducial distribution will be evaluated.

y

Vector of ordinates at which the density of the distribution will be evaluated for every point in x.

z

Matrix of densities on the grid defined by x and y, with rows corresponding to elements of x and columns corresponding to elements of y.

pointwise

If TRUE then the maximum density at each x is shaded with colmax (default black), and the shading intensity is proportional to the density within each x.

If FALSE then the maximum density over all x is shaded with colmax, and the shading is proportional to the density over all x.

nlevels

Number of distinct shades to use to illustrate the varying densities. The default of 100 should result in a plot with smoothly-varying shading.

colmax

Colour to shade the maximum density, either as a built-in R colour name (one of colors()) or an RGB hex value. Defaults to par("fg") which is normally "black", or "#000000".

colmin

Colour to shade the minimum density, likewise. Defaults to "white". If this is set to "transparent", and the current graphics device supports transparency (see rgb), then multiple regions drawn on the same plot will merge smoothly.

scale

Proportion of colmax to shade the maximum density, for example scale=0.5 with colmax="black" for a mid-grey colour.

gamma

Gamma correction to apply to the colour palette, see denstrip.

contour

If TRUE then contours are added to illustrate lines of constant density.

...

Further arguments passed to or from other methods, such as the contour function for drawing contours.

Details

The plot is shaded by interpolating the value of the density between grid points, using the algorithm described by Cleveland (1993) as implemented in the filled.contour function.

With lattice graphics, similar plots can be implemented using the contourplot or levelplot functions.

Author(s)

Christopher Jackson <[e-mail]>

References

Jackson, C. H. (2008) Displaying uncertainty with shading. The American Statistician, 62(4):340-347.

Cleveland, W. S. (1993) Visualizing Data. Hobart Press, Summit, New Jersey.

See Also

densregion.survfit, densregion.normal, denstrip

Examples

## Predictive uncertainty around a hypothetical regression line

x <- 1:10
nx <- length(x)
est <- seq(0, 1, length=nx)
lcl <- seq(-1, 0, length=nx)
ucl <- seq(1, 2, length=nx)
se <- (est - lcl)/qnorm(0.975)

y <- seq(-3, 3, length=100)
z <- matrix(nrow=nx, ncol=length(y))
for(i in 1:nx)
  z[i,] <- dnorm(y, est[i], se[i])
plot(x, type="n", ylim=c(-5.5, 2.5))
densregion(x, y, z, colmax="darkgreen")
lines(x, est)
lines(x, lcl, lty=2)
lines(x, ucl, lty=2)
box()

## On graphics devices that support transparency, specify
## colmin="transparent" to allow adjacent regions to overlap smoothly
densregion(x, y-1, z, colmax="magenta", colmin="transparent")


## or automatically choose the y points to evaluate the density 

plot(x, type="n", ylim=c(-1.5, 2.5))
densregion.normal(x, est, se, ny=50, colmax="darkgreen")
lines(x, est)
lines(x, lcl, lty=2)
lines(x, ucl, lty=2)