xpose.xtras (version 0.2.2)

cov_forest: Covariate effect forest plot

Description

Visualizes the effect of covariates on structural parameters, as declared with add_cov_association(), as a forest plot: one row per (parameter, covariate, evaluation point), the point estimate and interval as a ratio to the parameter's typical value, with a reference line at 1.

This is the covariate-specific wrapper: it calls prm_cov() to compute the effect-size table and xplot_forest() (a generic, forest-plot-agnostic renderer, see its own documentation) to draw it.

Usage

cov_forest(
  xpdb,
  ...,
  type = "pilr",
  region = NULL,
  show_ref = TRUE,
  log = TRUE,
  forest_opts = list(),
  title = "Covariate effects on model parameters | @run",
  subtitle = "Ratio to typical parameter value; reference line at 1",
  caption = "@dir",
  tag = NULL,
  .problem = NULL,
  .subprob = NULL,
  .method = NULL,
  quiet
)

Value

The desired plot

Arguments

xpdb

<xp_xtras> object with covariate associations declared via add_cov_association()

...

<dynamic-dots> Forwarded to prm_cov() -- eg param ~ covariate selectors, ci_method, probs, level, nsim.

type

Passed to xplot_forest(); defaults to 'pilr' (point + interval + reference line + shaded reference region -- xplot_forest()'s own defaults omit the line and region, since those are cov_forest()- specific opinions, not generic ones). Including "v" adds a violin/density layer of the raw simulation draws behind each interval; this forces prm_cov(keep_draws = TRUE), which in turn requires ci_method = "simulation" (the default) -- pass ci_method = "delta" in ... together with type containing "v" and it will error, since no draws exist for the delta method.

region

<numeric(2)> c(low, high) bounds for the shaded reference region (type includes "r", the default); NULL (default) falls back to c(0.8, 1.25), a common bioequivalence-style "no relevant effect" band.

show_ref

<logical> Include the reference row(s) (effect/ ci_low/ci_high always 1, by construction, for every reference covariate value/level)? Defaults to TRUE; set FALSE to drop them from the plot -- they carry no information beyond what the reference line already shows, and cutting them can reduce clutter when there are many covariates.

log

<logical> Log-scale the effect-ratio (x) axis? Defaults to TRUE. Unlike most of the package's log arguments (eg eta_vs_contcov()'s), this is a plain boolean rather than an "x"/"y"/NULL axis-selector string -- cov_forest()'s orientation isn't user-configurable, so the axis being logged is never ambiguous.

forest_opts

<list> Extra named arguments forwarded to xplot_forest() (eg theme overrides), the same way pairs_opts works for cov_grid()/eta_grid(). Rarely needed since the most common override, type, is already its own argument.

title

Plot title

subtitle

Plot subtitle

caption

Plot caption

tag

Plot tag

.problem

<numeric> Problem number

.subprob

<numeric> Subprob number

.method

<numeric> Method

quiet

Silence extra output

See Also

add_cov_association(), prm_cov(), xplot_forest()

Examples

# \donttest{

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