prm_cov: Continuous/categorical covariate effect tables

In xpose.xtras: Extra Functionality for the 'xpose' Package

Continuous/categorical covariate effect tables

Description

Computes, for each covariate association declared with add_cov_association(), the covariate's effect on the associated parameter (as a ratio to the parameter's typical value, 1 at the reference covariate value/level) at a handful of representative evaluation points, with an uncertainty interval propagated from the effect-size theta's standard error. This is what xplot_forest() plots; calling these directly is mostly useful for inspecting the numbers before/without plotting.

prm_contcov() handles continuous covariates (linear, power, exponential, hockey, or custom associations), evaluated at the low/reference/high points. prm_catcov() handles categorical covariates (catshift or custom associations), evaluated at every observed level. prm_cov() combines both.

Usage

prm_contcov(
  xpdb,
  ...,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  ci_method = c("simulation", "delta"),
  probs = c(0.05, 0.95),
  level = 0.95,
  nsim = 1000,
  keep_draws = FALSE,
  quiet
)

prm_catcov(
  xpdb,
  ...,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  ci_method = c("simulation", "delta"),
  level = 0.95,
  nsim = 1000,
  keep_draws = FALSE,
  quiet
)

prm_cov(
  xpdb,
  ...,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  ci_method = c("simulation", "delta"),
  probs = c(0.05, 0.95),
  level = 0.95,
  nsim = 1000,
  keep_draws = FALSE,
  quiet
)

Arguments

xpdb	<xp_xtras> object with associations declared via add_cov_association()
...	<dynamic-dots> Optional param ~ covariate selectors (bare, unquoted, same style as drop_cov_association()) to restrict which declared associations are computed. Defaults to all of them.
.problem	<numeric> Problem number.
.subprob	<numeric> Subprob number.
.method	<numeric> Method.
ci_method	<character> "simulation" (default) draws nsim samples of each theta from N(theta_hat, se) (mirrors mutate_prm()'s .autose approach) and propagates them through the (possibly nonlinear) effect_ratio function, taking the resulting sample quantiles as the interval; most accurate for strongly nonlinear forms (power, exponential, hockey). "delta" is a first-order analytic (numerical-gradient) log-scale approximation – cheap and deterministic, but less accurate the more nonlinear the association is. Both treat multiple thetas (eg hockey, multi-level catshift) as independent, ignoring any covariance between them.
probs	<numeric(2)> For prm_contcov(): quantiles of the covariate's observed data used as the "low"/"high" evaluation points.
level	<numeric> Confidence level for the effect interval.
nsim	<numeric> Number of simulation draws, when ci_method = "simulation".
keep_draws	<logical> If TRUE (requires ci_method = "simulation"), attach a draws list-column: the raw nsim simulated effect-ratio draws behind each row's CI. Mainly intended for a forest-plot violin/density layer; most users won't need this.
quiet	Silence extra output.

Value

A prm_cov_tbl tibble with one row per (parameter, covariate, evaluation point): param, covariate, covtype, level ("low"/"ref"/"high" for continuous, the raw category value for categorical), value (the covariate value/level backing that row), is_ref (TRUE for the reference row/level – always effect/ci_low/ci_high ⁠== 1⁠, by construction), effect, ci_low, ci_high, ci_method.

See Also

add_cov_association(), xplot_forest()

Examples

xpdb_x %>%
  add_cov_association(TVCL ~ power(CLCR, THETA7, ref = 64)) %>%
  prm_contcov()

xpdb_x %>%
  add_cov_association(TVCL ~ catshift(SEX, THETA4, ref = 1)) %>%
  prm_catcov()

xpdb_x %>%
  add_cov_association(
    TVCL ~ power(CLCR, THETA7, ref = 64),
    TVCL ~ catshift(SEX, THETA4, ref = 1)
  ) %>%
  prm_cov()

# Restrict to one association, and use the analytic delta-method CI
xpdb_x %>%
  add_cov_association(
    TVCL ~ power(CLCR, THETA7, ref = 64),
    TVCL ~ catshift(SEX, THETA4, ref = 1)
  ) %>%
  prm_cov(TVCL ~ CLCR, ci_method = "delta")

xpose.xtras documentation built on Sept. 1, 2026, 5:08 p.m.