cut_quantile: Cut a continuous variable into quantiles

In erplots: Model-Agnostic Exposure-Response Plots

Cut a continuous variable into quantiles

Description

cut_quantile() bins a numeric vector into n_bins quantile groups. cut_exposure_quantile() does the same for an exposure variable, additionally keeping placebo (0) observations in their own bin.

Usage

cut_exposure_quantile(
  x,
  n_bins = 4,
  is_placebo = NULL,
  ties = c("upward", "downward", "split-even"),
  seed = NULL,
  quantile_type = 7,
  labeller = NULL
)

cut_quantile(
  x,
  n_bins = 4,
  ties = c("upward", "downward", "split-even"),
  seed = NULL,
  quantile_type = 7,
  labeller = NULL
)

Arguments

x	Numeric vector
n_bins	Number of bins
is_placebo	Logical vector indicating placebo samples
ties	Rule for assigning a value that sits exactly on an interior break point, where the bin membership would otherwise be ambiguous. "upward" (the default, matching prior behaviour) is equivalent to cut() with right = TRUE; "downward" is equivalent to right = FALSE; "split-even" randomly divides each tied group between its two candidate bins so that final bin sizes are as equal as possible, rather than sending every tied value the same direction.
seed	Optional single number used to seed the random tie-break used by ties = "split-even" (ignored for "upward"/"downward", which involve no randomness). NULL (the default) draws from the ambient RNG stream and so is not reproducible across calls; pass a seed for reproducible bin assignment.
quantile_type	Integer between 1 and 9, passed straight through as stats::quantile()'s own type argument to compute the quantile break points. Defaults to 7, matching stats::quantile()'s own default.
labeller	Controls the labels used for the n_bins quantile bins (cut_exposure_quantile()'s separate "Placebo" level is always used as-is, regardless of labeller). NULL (the default) labels bins "Q1", "Q2", etc. A function is called as labeller(n_bins, breaks) (the actual bin count and the n_bins + 1 quantile cutpoints, after any resolution-driven fallback – see ⁠@details⁠ below) and must return a character vector of length n_bins; this is the hook for, e.g., range-style labels built from breaks. A character vector is used directly as the n_bins labels.

Details

Both functions error if x has fewer than 2 distinct non-missing values, since quantile bins aren't well-defined in that case. If x doesn't have enough resolution to distinguish all n_bins requested bins (e.g. many repeated values clustered at one end), both functions warn and fall back to using as many bins as the data supports, rather than erroring or silently showing fewer bins with no explanation. cut_exposure_quantile()'s "breaks" attribute is read back out by quantile-layer builders that draw bin-boundary separators (e.g. er_style_quantile_errorbar_vlines()) via attr(exposure_bins, "breaks"). Because that fallback can lower n_bins below what was originally requested, a character-vector labeller is length-checked against the actual bin count, not the requested one, and errors informatively on a mismatch.

Value

A factor with "ties" and "quantile_type" attributes recording those two arguments. cut_exposure_quantile()'s result additionally carries a "breaks" attribute holding the n_bins + 1 quantile cutpoints used to form the bins.

Examples

x <- rnorm(100)
cut_quantile(x)
cut_exposure_quantile(abs(x))
cut_quantile(x, ties = "split-even", seed = 8213)
cut_quantile(x, quantile_type = 1)
cut_quantile(x, labeller = function(n_bins, breaks) paste0("Group ", 1:n_bins))
cut_quantile(x, labeller = c("Low", "Mid-low", "Mid-high", "High"))

erplots documentation built on Oct. 4, 2026, 5:06 p.m.