# 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

1 2 3 4 5 |

### Arguments

`x` |
Suppose the continuously-varying quantity varies over a
space S. |

`y` |
Vector of ordinates at which the density of the distribution
will be evaluated for every point in |

`z` |
Matrix of densities on the grid defined by |

`pointwise` |
If If |

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

`colmin` |
Colour to shade the minimum density, likewise.
Defaults to "white". If this is set to |

`scale` |
Proportion of |

`gamma` |
Gamma correction to apply to the colour palette, see |

`contour` |
If |

`...` |
Further arguments passed to or from other methods, such
as the |

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

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

`densregion.survfit`

, `densregion.normal`

, `denstrip`

### Examples

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | ```
## 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)
``` |