Skip to main content

6  Boxplots and violins

library(rtemis.draw)

draw_boxplot() and draw_violin() summarize the distribution of one or more numeric variables, optionally by group, with observation points, paired lines, and comparison labels.

6.1 Single or Multiple Numeric Vectors

Input: Single numeric vector

draw_boxplot(
  penguins$body_mass
)
2026-11-18 17:29:13 Removed 2 NA values from data [boxplot_option]

Note:

  • The function automatically detects the presence of NAs, prints a message, and excludes them from the plot
  • An unnamed vector is labeled Variable 1; use a named list or labels for a descriptive category

A custom label is set either by passing a named list/data.frame or by using the labels argument:

draw_boxplot(
  list(`Body Mass` = penguins$body_mass)
)
2026-11-18 17:29:13 Removed 2 NA values from data [boxplot_option]
draw_boxplot(
  penguins$body_mass,
  labels = "Body Mass"
)
2026-11-18 17:29:13 Removed 2 NA values from data [boxplot_option]

Input can be a list of any number of numeric vectors:

draw_boxplot(
  list(
    `Bill Length` = penguins$bill_len,
    `Flipper Length` = penguins$flipper_len
  )
)
2026-11-18 17:29:13 Removed 4 NA values from data [boxplot_option]

or a data.frame:

draw_boxplot(
  penguins[, c("bill_len", "flipper_len")],
  labels = c("Bill Length", "Flipper Length")
)
2026-11-18 17:29:13 Removed 4 NA values from data [boxplot_option]
draw_boxplot(
  penguins[, c("bill_len", "flipper_len")],
  labels = c("Bill Length", "Flipper Length"),
  palette = rtemis_colors[2]
)
2026-11-18 17:29:13 Removed 4 NA values from data [boxplot_option]

6.2 Grouped Single or Multiple Numeric Vectors

draw_boxplot(
  penguins$body_mass,
  group = penguins$species
)
2026-11-18 17:29:13 Removed 2 NA values from data [boxplot_option]
draw_boxplot(
  penguins[c("bill_len", "bill_dep")],
  labels = c("Bill length (mm)", "Bill depth (mm)"),
  group = penguins["species"]
)
2026-11-18 17:29:13 Removed 4 NA values from data [boxplot_option]

Categorical legends sit in a compact, centered row above the plotting area. Use legend_position = "top-right" to right-align that row, or choose "top-left", "bottom", "bottom-left", "bottom-right", "left", or "right". Outside placement reserves space for the complete legend; legend_placement = "inside" places it over the data instead. These controls also work with the other ECharts drawing functions and their configuration objects. A single grouped variable keeps its group labels on the axis and does not need an additional legend.

legend_title names what the legend entries stand for. It sits before the first row of a top or bottom legend, and above a left or right legend or a color scale; the default NULL draws no title:

draw_boxplot(
  penguins[c("bill_len", "bill_dep")],
  labels = c("Bill length (mm)", "Bill depth (mm)"),
  group = penguins["species"],
  legend_title = "Species",
  legend_position = "right"
)
2026-11-18 17:29:13 Removed 4 NA values from data [boxplot_option]

6.3 Violin distributions

Violin widths show the distribution within each sample. Each violin has the same maximum width; width does not compare sample size across species. show_box = TRUE adds a narrow box showing the median and quartiles.

draw_violin(
  penguins["bill_len"],
  group = penguins["species"],
  show_box = TRUE,
  boxpoints = "all",
  ylab = "Bill length (mm)"
)
2026-11-18 17:29:13 Removed 2 NA values from data [boxplot_option]

The Gaussian density uses bw.nrd0() bandwidth selection. Increase adjust for a smoother shape, or supply a numeric bandwidth in measurement units. Densities stop at the observed range. Constant samples appear as crossbars.

6.4 Paired measurements and comparisons

The sleep dataset records extra hours of sleep for ten people receiving each of two drugs. Explicit subject IDs connect the same people across conditions, even if the rows are reordered. Missing measurements leave gaps.

Compute the paired test separately, then pass its result as an annotation. This keeps the statistical test and its assumptions visible in the analysis. The plotting function displays the supplied label without running a test.

sleep_data <- datasets::sleep
sleep_data$drug <- paste("Drug", sleep_data$group)
sleep_wide <- reshape(sleep_data[c("ID", "group", "extra")],
  idvar = "ID", timevar = "group", direction = "wide")
paired_test <- t.test(sleep_wide$extra.1, sleep_wide$extra.2, paired = TRUE)
comparison <- data.frame(
  from = "Drug 1", to = "Drug 2",
  label = sprintf("Paired t-test: p = %.3f", paired_test$p.value)
)
draw_violin(
  sleep_data$extra,
  group = sleep_data$drug,
  observation = sleep_data$ID,
  paired = TRUE,
  show_box = TRUE,
  boxpoints = "all",
  comparisons = comparison,
  ylab = "Extra sleep (hours)"
)

draw_boxplot() accepts the same pairing and comparison arguments. Comparisons use category names; for multiple grouped variables, also specify from_group and to_group. An optional position column sets bracket heights explicitly. For a saved BoxplotConfig, comparisons names a data-frame entry in the bound data list, as observation names the ID column.

6.5 Configuration

setup_BoxplotConfig() describes a boxplot by column names:

config <- setup_BoxplotConfig(x = "body_mass", group = "species",
                              boxpoints = "all")
draw(config, data = penguins)
2026-11-18 17:29:13 Removed 2 NA values from data [boxplot_option]
© 2026 E.D. Gennatas