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.
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 allx 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 <chris.jackson@mrc-bsu.cam.ac.uk>
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)