vwstrip {denstrip}

Varying-width strips

Description

Varying-width strips give a compact illustration of a distribution. The width of the strip is proportional to the density. This function adds a varying-width strip to an exising plot.

Usage

vwstrip(x, dens, at, width, horiz=TRUE, scale=1, limits=c(-Inf, Inf), 
        col="gray", border=NULL, lwd, lty, ticks=NULL, tlen=1, twd, tty,
        lattice=FALSE,...)
panel.vwstrip(...)

Arguments

x

Either the vector of points at which the density is evaluated (if dens supplied), or a sample from the distribution (if dens not supplied).

dens

Density at x. If dens is not supplied, the density of the sample x is estimated by kernel density estimation, using density(x,...).

at

Position of the centre of the strip on the y-axis (if horiz=TRUE) or the x-axis (if horiz=FALSE).

width

Thickness of the strip at the maximum density, that is, the length of its shorter dimension. Defaults to 1/20 of the axis range.

horiz

Draw the strip horizontally (TRUE) or vertically (FALSE).

scale

Alternative way of specifying the thickness of the strip, as a proportion of width.

limits

Vector of minimum and maximum values, respectively, at which to terminate the strip.

col

Colour to shade the strip, either as a built-in R colour name (one of colors()) or an RGB hex value, e.g. black is "#000000".

border

Colour of the border, see polygon. Use border=NA to show no border. The default, 'NULL', means to use 'par("fg")' or its lattice equivalent

lwd

Line width of the border (defaults to par("lwd") or its lattice equivalent).

lty

Line type of the border (defaults to par("lty") or its lattice equivalent).

ticks

Vector of x-positions on the strip to draw tick marks, or NULL for no ticks.

tlen

Length of the ticks, relative to the thickness of the strip.

twd

Line width of these marks (defaults to par("lwd") or its lattice equivalent).

tty

Line type of these marks (defaults to par("lty") or its lattice equivalent).

lattice

Set this to TRUE to make vwstrip a lattice panel function instead of a base graphics function.
panel.vwstrip(x,...) is equivalent to vwstrip(x, lattice=TRUE, ...).

...

Additional arguments supplied to density(x,...), if the density is being estimated.

Details

Varying-width strips look like violin plots. The difference is that violin plots are intended to summarise data, while vwstrip is intended to illustrate a distribution arising from parameter estimation or prediction. Either the distribution is known analytically, or an arbitrarily large sample from the distribution is assumed to be available via a method such as MCMC or bootstrapping.

Illustrating outliers is important for summarising data, therefore violin plots terminate at the sample minimum and maximum and superimpose a box plot (which appears like the bridge of a violin, hence the name). Varying-width strips, however, are used to illustrate known distributions which may have unbounded support. Therefore it is important to think about where the strips should terminate (the limits argument). For example, the end points may illustrate a particular pair of extreme quantiles of the distribution.

The function vioplot in the vioplot package and panel.violin in the lattice package can be used to draw violin plots of observed data.

Author(s)

Christopher Jackson <[e-mail]>

References

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

Hintze, J.L. and Nelson, R.D. (1998) Violin plots: a box plot - density trace synergism. The American Statistician 52(2),181–184.

See Also

denstrip, bpstrip, cistrip.

Examples

x <- seq(-4, 4, length=10000)
dens <- dnorm(x)
plot(x, xlim=c(-5, 5), ylim=c(-5, 5), xlab="x", ylab="x", type="n")
vwstrip(x, dens, at=1, ticks=qnorm(c(0.025, 0.25,0.5, 0.75, 0.975)))

## Terminate the strip at specific outer quantiles
vwstrip(x, dens, at=2, limits=qnorm(c(0.025, 0.975)))
vwstrip(x, dens, at=3, limits=qnorm(c(0.005, 0.995)))

## Compare with density strip
denstrip(x, dens, at=0)

## Estimate the density from a large sample 
x <- rnorm(10000)
vwstrip(x, at=4)