siberDensityPlot {SIBER}

Plot credible intervals as shaded boxplots using hdr.boxplot

Description

This function is essentially hdrcde::hdr.boxplot() but it more easily works with matrices of data, where each column is a different variable of interest. It has some limitations though....

Usage

siberDensityPlot(
  dat,
  probs = c(95, 75, 50),
  xlab = "Group",
  ylab = "Value",
  xticklabels = NULL,
  yticklabels = NULL,
  clr = matrix(rep(grDevices::gray((9:1)/10), ncol(dat)), nrow = 9, ncol = ncol(dat)),
  scl = 1,
  xspc = 0.5,
  prn = F,
  ct = "mode",
  ylims = NULL,
  lbound = -Inf,
  ubound = Inf,
  main = "",
  ylab.line = 2,
  ...
)

Arguments

dat

a matrix of data for which density region boxplots will be constructed and plotted for each column.

probs

a vector of credible intervals to represent as box edges. Defaults to ⁠c(95, 75, 50⁠.

xlab

a string for the x-axis label. Defaults to "Group".

ylab

a string of the y-axis label. Defaults to '"Value".

xticklabels

a vector of strings to override the x-axis tick labels.

yticklabels

a vector of strings to override the y-axis tick labels.

clr

a matrix of colours to use for shading each of the box regions. Defaults to greyscale grDevices::gray((9:1)/10) replicated for as many columns as there are in dat. When specified by the user, rows contain the colours of each of the confidence regions specified in probs and columns represent each of the columns of data in dat. In this way, one could have shades of blue, red and yellow for each of the groups.

scl

a scalar multiplier to scale the box widths. Defaults to 1.

xspc

a scalar determining the amount of spacing between each box. Defaults to 0.5.

prn

a logical value determining whether summary statistics of each column should be printed to screen prn = TRUE or suppressed as per default prn = FALSE.

ct

a string of either c("mode", "mean", "median") which determines which measure of central tendency will be plotted as a point in the middle of the boxes. Defaults to "mode".

ylims

a vector of length two, specifying the lower and upper limits for the y-axis. Defaults to NULL which inspects the data for appropriate limits.

lbound

a lower boundary to specify on the distribution to avoid the density kernel estimating values beyond that which can be expected a priori. Useful for example when plotting dietary proportions which must lie in the interval ⁠0 <= Y <= 1⁠. Defaults to -Inf

ubound

an upper boundary to specify on the distribution to avoid the density kernel estimating values beyond that which can be expected a priori. Useful for example when plotting dietary proportions which must lie in the interval ⁠0 <= Y <= 1⁠. Defaults to +Inf.

main

a title for the figure. Defaults to blank.

ylab.line

a postive scalar indicating the line spacing for rendering the y-axis label. This is included as using the permille symbol has a tendency to push the axis label off the plotting window margins. See the line option in graphics::axis() for more details as ylab.line passes to this.

...

further graphical parameters for passing to graphics::plot()

Value

A new figure window.

Warning

: This function will not currently recognise and plot multimodal distributions, unlike hdrcde::hdr.boxplot(). You should take care, and plot basic histograms of each variable (column in the object you are passing) and check that they are indeed unimodal as expected.

Examples

# A basic default greyscale density plot
Y <- matrix(stats::rnorm(1000), 250, 4)
siberDensityPlot(Y)

# A more colourful example
my_clrs <- matrix(c("lightblue", "blue", "darkblue",
"red1", "red3", "red4",
"yellow1", "yellow3", "yellow4",
"turquoise", "turquoise3", "turquoise4"), nrow = 3, ncol = 4)
siberDensityPlot(Y, clr = my_clrs)