# densregion

##### Density regions

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, ...)
"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.

##### References

Jackson, C. H. (2008) Displaying uncertainty with
shading. *The American Statistician*, 62(4):340-347.
http://www.mrc-bsu.cam.ac.uk/personal/chris/papers/denstrip.pdf

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

##### See Also

##### 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)
```

*Documentation reproduced from package denstrip, version 1.5.3, License: GPL (>= 2)*