Boxplots with possibly moderators — plot

This function allows to draw a boxplot, with possibly separating different moderators.

plot_box(
  fml,
  data,
  case,
  moderator,
  inCol,
  outCol = "black",
  density = -1,
  lty = 1,
  pch = 18,
  addLegend = TRUE,
  legend_options = list(),
  lwd = 2,
  outlier,
  dict = NULL,
  dict_case,
  dict_moderator,
  order_case,
  order_moderator,
  addMean,
  mean.col = "darkred",
  mean.pch = 18,
  mean.cex = 2,
  mod.title = TRUE,
  labels.tilted,
  trunc = 20,
  trunc.method = "auto",
  line.max,
  ...
)

Arguments

fml: A numeric vector or a formula of the type: vars ~ moderator_1 | moderator_2. Note that if a formula is provided then the argument ‘data’ must be provided. You can plot several variables, if you don't want a moderator, use 1 instead: e.g. plot_box(Petal.Width +Petal.Length ~ 1, iris). You can plot all numeric variables from a data set using ".": plot_box(. ~ 1, iris).
data: A data.frame/data.table containing the relevant information.
case: When argument fml is a vector, this argument can receive a vector of cases.
moderator: When argument fml is a vector, this argument can receive a vector of moderators.
inCol: A vector of colors that will be used for within the boxes.
outCol: The color of the outer box. Default is black.
density: The density of lines within the boxes. By default it is equal to -1, which means the boxes are filled with color.
lty: The type of lines for the border of the boxes. Default is 1 (solid line).
pch: The patch of the outliers. Default is 18.
addLegend: Default is TRUE. Should a legend be added at the top of the graph is there is more than one moderator?
legend_options: A list. Other options to be passed to legend which concerns the legend for the moderator.
lwd: The width of the lines making the boxes. Default is 2.
outlier: Default is TRUE. Should the outliers be displayed?
dict: A dictionnary to rename the variables names in the axes and legend. Should be a named vector. By default it s the value of getFplot_dict(), which you can set with the function setFplot_dict.
dict_case: A named character vector. If provided, it changes the values of the variable ‘case’ to the ones contained in the vector dict_case. Example: I want to change my variable named "a" to "Australia" and "b" to "Brazil", then I used dict=c(a="Australia",b="Brazil").
dict_moderator: A named character vector. If provided, it changes the values of the variable ‘moderator’ to the ones contained in the vector dict_moderator. Example: I want to change my variable named "a" to "Australia" and "b" to "Brazil", then I used dict=c(a="Australia",b="Brazil").
order_case: Character vector. This element is used if the user wants the ‘case’ values to be ordered in a certain way. This should be a regular expression (see regex help for more info). There can be more than one regular expression. The variables satisfying the first regular expression will be placed first, then the order follows the sequence of regular expressions.
order_moderator: Character vector. This element is used if the user wants the ‘moderator’ values to be ordered in a certain way. This should be a regular expression (see regex help for more info). There can be more than one regular expression. The variables satisfying the first regular expression will be placed first, then the order follows the sequence of regular expressions.
addMean: Whether to add the average for each boxplot. Default is true.
mean.col: The color of the mean. Default is darkred.
mean.pch: The patch of the mean, default is 18.
mean.cex: The cex of the mean, default is 2.
mod.title: Character scalar. The title of the legend in case there is a moderator. You can set it to TRUE (the default) to display the moderator name. To display no title, set it to NULL or FALSE.
labels.tilted: Whether there should be tilted labels. Default is FALSE except when the data is split by moderators (see mod.method).
trunc: If the main variable is a character, its values are truncaded to trunc characters. Default is 20. You can set the truncation method with the argument trunc.method.
trunc.method: If the elements of the x-axis need to be truncated, this is the truncation method. It can be "auto", "right" or "mid".
line.max: Option for the x-axis, how far should the labels go. Default is 1 for normal labels, 2 for tilted labels.
...: Other parameters to be passed to plot.

Value

Invisibly returns the coordinates of the x-axis.

Author

Laurent Berge

Examples


# Simple iris boxplot
plot(1:10)


# All numeric variables
plot_box(. ~ 1, iris)


# All numeric variable / splitting by species
plot_box(. ~ Species, iris)


# idem but with renaming
plot_box(. ~ Species, iris, dict = c(Species="Iris species",
         setosa="SETOSA", Petal.Width="Width (Petal)"))


# Now using two moderators
base = iris
base$period = sample(1:4, 150, TRUE)

plot_box(Petal.Length ~ period | Species, base)