denstrip (version 1.5.5)

bpstrip: Box-percentile strips

Description

Box-percentile strips give a compact illustration of a distribution. The width of the strip is proportional to the probability of a more extreme point. This function adds a box-percentile strip to an existing plot.

Usage

bpstrip(x, prob, 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.bpstrip(...)

Arguments

x

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

prob

Probability, or cumulative density, of the distribution at x. If prob is not supplied, this is estimated from the sample x using ecdf(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 its thickest point, which will be at the median. 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 bpstrip a lattice panel function instead of a base graphics function.
panel.bpstrip(x,...) is equivalent to bpstrip(x, lattice=TRUE, ...).

...

Other arguments passed to panel.bpstrip.

Author

Christopher Jackson <[e-mail]>

Details

The box-percentile strip looks the same as the box-percentile plot (Esty and Banfield, 2003) which is a generalisation of the boxplot for summarising data. However, bpstrip is intended for illustrating distributions 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.

The function bpplot in the Hmisc package can be used to draw vertical box-percentile plots of observed data.

References

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

Esty, W. W. and Banfield, J. D. (2003) The box-percentile plot. Journal of Statistical Software 8(17).

See Also

vwstrip, cistrip, denstrip

Examples

x <- seq(-4, 4, length=1000)
prob <- pnorm(x)
plot(x, xlim=c(-5, 5), ylim=c(-5, 5), xlab="x", ylab="x", type="n")
bpstrip(x, prob, at=1, ticks=qnorm(c(0.25, 0.5, 0.75)))

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

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

## Estimate the density from a large sample 
x <- rnorm(10000)
bpstrip(x, at=4)
# \dontshow{
x <- seq(-4, 4, length=1000)
bpstrip(x, prob, at=-1, col="purple", lwd=2, lty=2)
bpstrip(x, prob, at=-2, border=NA, ticks=qnorm(c(0.25,0.5,0.75)),
        twd=3,tty=2)
bpstrip(x, prob, at=-4, border=NA, horiz=FALSE)
bpstrip(x, prob, at=-3, border=NA, horiz=FALSE, width=0.2)
bpstrip(x, prob, at=2, border=NA, horiz=FALSE, scale=0.5)
# }