Skip to contents

Split violin with aligned half-boxplots, significance label, sample sizes, and label-aware title

Source: R/PlotSplitViolin.R
PlotSplitViolin.Rd

Draws a split (left/right) violin for up to two groups at a single x-position, overlays per-group boxplots aligned with each half, and optionally annotates the plot with a p-value significance label. Supports displaying sample sizes (n) and automatically using variable labels for axis and title when available.

Usage

PlotSplitViolin(
  data,
  Var,
  group_var,
  covariates = NULL,
  nonparametric = FALSE,
  annotation_text = NULL,
  show_ns = FALSE,
  plot_title = NULL,
  use_var_label_as_title = FALSE,
  show_n = TRUE,
  n_position = c("legend", "top"),
  n_size = 3.5,
  left_group = NULL,
  color_palette = NULL,
  box_offset = 0.11,
  box_width = 0.15,
  star_from = c("quantile", "data_max", "whisker"),
  star_quantile = 0.995,
  star_pad = 0.05,
  star_size = 6,
  ...,
  Group = lifecycle::deprecated(),
  covars = lifecycle::deprecated()
)

Arguments

data

A data frame containing Var, Group, and optional covariates.

Var

Numeric outcome variable (tidy-eval).

group_var

Grouping variable (<= 2 unique values).

covariates

Character vector of covariates (default NULL).

nonparametric

Logical. If FALSE, uses linear model + emmeans contrast. If TRUE, uses Wilcoxon (with residualization if covariates are present).

annotation_text

Optional manual annotation (e.g., "*", "ns").

show_ns

Logical; if TRUE, display "ns" for non-significant results.

plot_title

Optional custom plot title.

use_var_label_as_title

Logical; if TRUE, uses variable label as title.

show_n

Logical; if TRUE, display sample size per group.

n_position

Where to display n: "legend" or "top".

n_size

Text size for n labels when shown on top.

left_group

Optional group to force on left side.

color_palette

Optional named vector of colors.

box_offset

Horizontal offset for boxplots.

box_width

Width of boxplots.

star_from

Position method ("quantile","data_max","whisker").

star_quantile

Quantile used for placement.

star_pad

Padding above anchor.

star_size

Text size for annotation.

...

Additional arguments reserved for future extensions.

Group

Deprecated (since 19.15.0). Use group_var instead.

covars

Deprecated (since 19.15.0). Use covariates instead.

Value

A ggplot2 object.

Examples

data(SampleData)
data(SampleVariableTypes)

Labelled <- RevalueData(SampleData, SampleVariableTypes)$RevaluedData

# Ab_42 has a clear Diagnosis-group difference in the bundled teaching data.
PlotSplitViolin(Labelled, Var = "Ab_42", group_var = "Diagnosis")