Box plot of tAge predictions with pairwise significance annotation

Draws a box plot with jittered points for one prediction column, split by a grouping variable and optionally faceted by a subgroup. Pairwise comparisons are annotated with brackets; comparisons involving groups with too few observations, and – when p_threshold is set – non-significant ones, are dropped before plotting so the panel stays readable.

Usage

tage_boxplot(
  data,
  x_var,
  y_var,
  subgroup_var = NULL,
  colors = NULL,
  point_size = 2,
  point_alpha = 0.7,
  box_width = 0.5,
  stat_method = "emmeans",
  reference_group = NULL,
  covariates = NULL,
  se_column = NULL,
  variance_strata = c("subset", "all_data"),
  p_adjust = "BH",
  p_adjust_scope = "within_column",
  comparisons = NULL,
  p_label = "p.signif",
  p_threshold = NULL,
  min_group_n = 2,
  font_size = 10,
  theme_type = NULL,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  xlab = NULL,
  ylab = NULL,
  legend_position = "right",
  y_center = NULL,
  y_min = NULL,
  y_max = NULL,
  facet_scales = "free_y",
  x_order = NULL,
  width = 10,
  height = 6
)

Arguments

data

Data frame of per-sample values, typically the prediction table returned by predict_tAge.

x_var

Column name defining the groups on the x axis.

y_var

Column name holding the values to plot, e.g. a *_tAge column.

subgroup_var

Optional column name used to facet the plot. Default NULL.

colors

Optional colours keyed by the levels of x_var, overriding the default in which the reference group is grey and the other groups take the categorical slots of tage_series_colors in order.

point_size, point_alpha

Size and opacity of the jittered points.

box_width

Width of the boxes.

stat_method

Test used for the comparisons. "emmeans" (default) uses tage_compare_groups: estimated marginal-mean contrasts, which support covariates, stratum-wise models and Bayesian ridge weighting. Any other value is passed to ggpubr::stat_compare_means, e.g. "t.test" or "wilcox.test".

reference_group

Reference level for stat_method = "emmeans". Default NULL uses the first level of x_var.

covariates

Covariate columns adjusted for when stat_method = "emmeans". Supplying them also switches the plotted values to covariate-adjusted ones (tage_adjust_covariates).

se_column

Column of per-sample prediction standard deviations for a Bayesian ridge clock, enabling the meta-regression test. Default NULL.

variance_strata

Passed to tage_compare_groups.

p_adjust, p_adjust_scope

Multiplicity correction passed to tage_compare_groups.

comparisons

List of length-2 character vectors giving the pairs to test. Default NULL compares every level against reference_group for stat_method = "emmeans", and tests all pairs of x_var levels otherwise.

p_label

Label style for the annotations, e.g. "p.signif" for stars or "p.format" for numeric p-values.

p_threshold

If supplied, comparisons whose p-value is not below this threshold are removed from the plot. When faceting, a comparison is kept if it is significant in at least one facet.

min_group_n

Minimum number of non-missing observations required in both groups for a comparison to be shown. When faceting, every facet must meet it.

font_size

Base font size; also scales the annotation text.

theme_type

Deprecated; figures follow theme_tage.

title, xlab, ylab

Plot title and axis labels.

subtitle, caption

Subtitle (secondary ink) and a provenance caption (muted ink) under the plot.

legend_position

Legend placement passed to ggplot2::theme.

y_center

If given, the y axis is made symmetric around this value – useful for relative predictions centred on zero.

y_min, y_max

Explicit y-axis limits, overriding the automatic range.

facet_scales

Scale behaviour across facets, passed to ggplot2::facet_wrap. Default "free_y".

x_order

Character vector giving the order of the x_var levels.

width, height

Plot size in inches, used to set the inline display size.

Value

A ggplot object.

See also

predict_tAge for producing the input table.

Examples

if (FALSE) { # \dontrun{
results <- predict_tAge(tAge_eset, model_paths, species = "mouse", mode = "EN")
tage_boxplot(
  results,
  x_var = "Genotype",
  y_var = "yugene_diff_EN_tAge",
  subgroup_var = "Tissue",
  x_order = c("WT", "Klotho KO"),
  ylab = "Relative tAge, months"
)
} # }