Generate Box-Whisker Plots

Produces box-and-whisker plots for visualizing the distribution of data. For more details and examples, see the vignettes:

• vignette("Box-Whisker Plots", package = "ospsuite.plots")

• vignette("ospsuite.plots", package = "ospsuite.plots")

Usage

plotBoxWhisker(
  data,
  mapping,
  metaData = NULL,
  plotObject = NULL,
  percentiles = getOspsuite.plots.option(optionKey = OptionKeys$Percentiles),
  yscale = AxisScales$linear,
  yscale.args = list(),
  xscale = "auto",
  xscale.args = list(),
  statFun = NULL,
  outliers = FALSE,
  statFunOutlier = NULL,
  geomBoxplotAttributes = getDefaultGeomAttributes("Boxplot"),
  geomPointAttributes = getDefaultGeomAttributes("Boxplot"),
  residualScale = ResidualScales$log
)

Arguments

data

A data.frame containing the data to aggregate.

mapping

A list of aesthetic mappings to use for the plot.

metaData

A named list of information about data such as the dimension and unit of its variables.

plotObject

An optional ggplot object on which to add the plot layers

percentiles

A numeric vector with percentiles used for the box whiskers and boxes, e.g., c(0.05, 0.25, 0.5, 0.75, 0.95). Default defined by ospsuite.plots option.

yscale

either 'linear' then ggplot2::scale_y_continuous() or 'log' then ggplot2::scale_y_log10() is used

yscale.args

list of arguments passed to ggplot2::scale_y_continuous() or ggplot2::scale_y_log10()

xscale

Either 'linear', 'log', 'discrete', or 'auto' (default). Auto selects linear for continuous data and discrete for categorical data.

xscale.args

A list of arguments passed to ggplot2::scale_x_continuous(), ggplot2::scale_x_log10(), or ggplot2::scale_x_discrete().

statFun

(default NULL) A function to calculate whiskers and box ranges, which overwrites the percentiles variable if provided.

outliers

Logical indicating whether outliers should be included in the boxplot. Outliers are flagged when outside the range from the "25th" percentile - 1.5 x IQR to the "75th" percentile + 1.5 x IQR, as suggested by McGill et al.

statFunOutlier

(default NULL) A function to calculate outliers, which overwrites the default calculation if provided.

geomBoxplotAttributes

A list of arguments passed to the geom_boxplot call.

geomPointAttributes

A list of arguments passed to the ggplot2::geom_point call.

residualScale

Either "linear", "log", or "ratio" scale for residuals.

Value

A ggplot object representing the box-whisker plot.

References

McGill, R., Tukey, J. W., & Larsen, W. A. (1978). Variations of box plots. The American Statistician, 32(1), 12-16.

See also

Other plot functions: plotForest(), plotHistogram(), plotPredVsObs(), plotQQ(), plotRangeDistribution(), plotRatioVsCov(), plotResVsCov(), plotTimeProfile(), plotYVsX()

Examples

if (FALSE) { # \dontrun{
# Basic box-whisker plot
plotBoxWhisker(
  data = myData,
  mapping = aes(x = group, y = value)
)

# Box-whisker plot with custom percentiles
plotBoxWhisker(
  data = myData,
  mapping = aes(x = treatment, y = response),
  percentiles = c(0.1, 0.25, 0.5, 0.75, 0.9)
)

# Box-whisker plot with custom stat function
customStatFun <- function(x) {
  return(quantile(x, probs = c(0.05, 0.25, 0.5, 0.75, 0.95), na.rm = TRUE))
}
plotBoxWhisker(
  data = myData,
  mapping = aes(x = dose_group, y = concentration),
  statFun = customStatFun,
  outliers = TRUE
)
} # }