Draw a Boxplot with Observation Overlays — draw

Draw one box per numeric vector, optionally split by groups. Statistics use linear-interpolation quartiles (stats::quantile(type = 7)) or Tukey hinges (stats::fivenum()). Whiskers extend to observations within the quartiles plus/minus whisker times their difference, including the quartiles themselves. whisker = 0 uses the full observed range. Values strictly outside the fences are outliers; they are never removed from the quartiles.

Usage

draw_boxplot(
  x,
  labels = NULL,
  group = NULL,
  horizontal = FALSE,
  palette = NULL,
  fill_alpha = 0.25,
  na_rm = TRUE,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  theme = NULL,
  margins = DEFAULT_MARGINS,
  width = NULL,
  height = NULL,
  verbosity = 1L,
  element_id = NULL,
  filename = NULL,
  observation = NULL,
  quartiles = "linear",
  whisker = 1.5,
  boxpoints = "none",
  point_size = 5,
  point_alpha = 0.6,
  point_spread = 0.5,
  legend_position = "top",
  legend_placement = "outside",
  geometry = "box",
  bandwidth = NULL,
  adjust = 1,
  density_points = 128L,
  paired = FALSE,
  pair_alpha = 0.35,
  pair_width = 1,
  comparisons = NULL,
  order = "input",
  transform = "none"
)

Arguments

x: Numeric or List: Numeric vectors, one per box; named lists supply category labels. With group, every vector must match its length.
labels: Optional Character: One category label per vector. A single grouped vector uses group labels instead.
group: Optional Atomic vector or single-column data frame: Group identities in first-appearance order. The column name does not add a legend or heading; both input forms produce the same plot.
horizontal: Logical: Draw horizontal boxes.
palette: Optional Character: Box colors, recycled across boxes or groups.
fill_alpha: Numeric [0, 1]: Box fill opacity.
na_rm: Logical: Remove missing values. FALSE rejects missing input.
xlab, ylab: Optional Character: Axis labels.
title: Optional Character: Chart title.
theme: Optional Theme: Theme override. The palette inside the theme can be overridden per-chart with the color argument.
margins: Optional Named numeric vector or named list: Plot margins in pixels (or percentage strings) for any of "top", "right", "bottom", "left" — e.g. c(left = 80, right = 20) or list(left = 80, right = "10%"). Unspecified sides keep echarts' default auto-sizing (outerBoundsMode = "same"), which shrinks the grid to fit axis labels and names with no dead space.
width: Optional Character or Numeric: Widget width.
height: Optional Character or Numeric: Widget height.
verbosity: Integer [0, Inf): Verbosity for missing-value messages.
element_id: Optional Character: Explicit DOM element ID for the widget container. NULL lets htmlwidgets generate one.
filename: Optional Character: If provided, save the widget to this file via save_drawing().
observation: Optional Atomic vector: Observation identifiers in tooltips, aligned to every input vector. Required for pairing; otherwise unset uses original row numbers.
quartiles: Character {"linear", "hinges"}: Quartile convention.
whisker: Numeric [0, Inf): Finite IQR fence multiplier; zero uses full-range whiskers.
boxpoints: Character {"none", "all", "outliers"}: Values to overlay.
point_size: Numeric (0, Inf): Finite point diameter in pixels.
point_alpha: Numeric [0, 1]: Point opacity.
point_spread: Numeric [0, 1]: Fraction of box width occupied by offsets.
legend_position: Character {"top", "bottom", "left", "right", "top-left", "top-right", "bottom-left", "bottom-right"}: Legend anchor. Top/bottom anchors use horizontal rows; left/right anchors use a vertical column. Corner anchors align within the top or bottom row.
legend_placement: Character {"outside", "inside"}: Relation to the plotting area. Outside placement reserves space for the complete legend; inside placement overlays the data. Neither setting adds a missing legend.
geometry: Character {"box", "violin", "both"}: Distribution geometry.
bandwidth: Optional Numeric (0, Inf): Finite Gaussian kernel bandwidth.
adjust: Numeric (0, Inf): Finite bandwidth multiplier.
density_points: Integer [16, 4096]: Density evaluation grid size.
paired: Logical: Connect explicit IDs across adjacent categories.
pair_alpha: Numeric [0, 1]: Paired line opacity.
pair_width: Numeric (0, Inf): Finite paired line width in pixels.
comparisons: Optional Data frame: Category endpoints and comparison labels.
order: Character {"input", "mean", "median"}: Keep input order or sort categories by decreasing mean/median after transformation; empty boxes last.
transform: Character {"none", "scale", "minmax"}: Transform each input column before grouping. Scale subtracts the mean and divides by the sample standard deviation; minmax maps the available range to zero through one. Constant columns become zero and missing values remain missing.

Value

htmlwidget: ECharts boxes with optional vector point overlays.

Details

All-NA and empty boxes retain their category without a mark; entirely unavailable input is an error. Missing values are reported in the console according to verbosity and never replaced with zero. Missing group assignments are excluded. Axis titles are centered. The category-axis baseline is shown only when the plotted value range includes zero. Every category label is shown so boxes remain identifiable in narrow plots. Use a horizontal layout or a larger figure for many or long category names. With point overlays, padded range endpoints are unlabeled; interior ticks retain the backend's numeric formatting and plotted values are unchanged. Points retain their exact value coordinate. Their perpendicular offsets use a deterministic base-two sequence in input row order within point_spread times the box width. Zero spread centers every point; coincident points can overlap. No random state is read or changed. Browser and SVG share the same named point renderer, including grouped-box offsets and legend filtering.

Violin densities use a Gaussian kernel with stats::bw.nrd0() unless a numeric bandwidth is supplied, multiplied by adjust. They are evaluated over the observed range and each is scaled to the same maximum width; widths do not encode sample size or comparable density across groups. Singleton and constant samples appear as crossbars, without an invented density. geometry = "both" overlays a narrow box on each violin.

Paired lines join matching explicit observation IDs in adjacent categories only, within groups for multiple grouped vectors. A missing measurement leaves a gap. IDs must be unique within each category/group. Lines meet visible observation points at their deterministic offsets.

Comparison records annotate supplied results; no statistical test or multiplicity adjustment is performed. from and to name categories; label supplies the displayed text. Multiple grouped vectors also require from_group and to_group. Optional finite position values place brackets on the value axis; otherwise brackets stack above the observed geometry. References must identify distinct, nonempty cells. Brackets disappear when either endpoint's group is hidden. Long labels may require a larger figure.

Examples

draw_boxplot(list(Training = c(.8, .9, .85), Test = c(.7, .8, .75)),
  boxpoints = "all", observation = c("Fold1", "Fold2", "Fold3"))

draw_boxplot(iris["Sepal.Length"], group = iris["Species"])