Plot Empirical or Model-Based Transition Proportions

plot_transitions() creates heatmaps of population transition proportions from observed trajectory data or from transition probabilities implied by a fitted Markov model. Model-based plots are population averaged over the supplied or stored patient profiles. When comparison = "difference", counterfactual transition summaries are computed for the levels in variables, and the heatmap shows the difference in transition proportions relative to the first level.

Usage

plot_transitions(
  x,
  newdata = NULL,
  variables = NULL,
  times = NULL,
  y_levels = NULL,
  absorb = NULL,
  comparison = c("none", "difference"),
  time_var = "time",
  y_var = "y",
  p_var = "yprev",
  p2_var = NULL,
  id_var = NULL,
  facet_var = NULL,
  gap_var = NULL,
  time_covariates = NULL,
  seed = NULL,
  n_draws = 100L,
  show_values = TRUE,
  digits = NULL,
  fill_limits = NULL
)

Arguments

x

A trajectory data frame or a fitted Markov model.

newdata

Optional data frame of prediction profiles for model-based plots. If NULL, wrapper-fitted models use their stored data and extract one prediction row per ID.

variables

Optional named list with one counterfactual variable. For comparison = "difference", at least two values are required and the first value is the reference.

times

Optional current-time values to plot. Required for model-based plots.

y_levels

Optional state levels. If omitted for model-based plots, levels are inferred from the model when possible.

absorb

Optional absorbing-state label.

comparison

"none" for transition proportions or "difference" for counterfactual differences in transition proportions.

time_var

Character name of the time column in trajectory data.

y_var

Character name of the current-state column in trajectory data.

p_var

Character name of the previous-state column.

p2_var

Optional second previous-state column for second-order model recursion.

id_var

Optional ID column used to extract one stored prediction row per patient.

facet_var

Optional observed grouping variable. The plot always facets by time; facet_var adds grouping to the time panels.

gap_var

Optional time-gap_var variable used by the fitted model.

time_covariates

Optional time-varying covariate lookup table used by the fitted model.

seed

Optional random seed for blrm posterior draw selection.

n_draws

Integer number of posterior draws to sample for blrm, or NULL to use all stored draws. Defaults to 100.

show_values

Logical. If TRUE, print rounded values in each tile.

digits

Number of digits used for tile labels. Defaults to 2 for proportions and 3 for differences.

fill_limits

Optional fill-scale limits. Difference plots use symmetric limits around zero when this is NULL.

Value

A ggplot object.

Details

Minimum inputs depend on the object type. For trajectory data, object must contain the current time, current state, and previous-state columns named by time_var, y_var, and p_var. For model-based plots, pass a fitted Markov model and times; use newdata for explicit prediction profiles and pass y_levels or absorb when they are not inferable or absorbing-state behavior matters. Difference plots also require comparison = "difference" and variables = list(var = c(reference, comparison)).

Examples

if (FALSE) { # \dontrun{
plot_transitions(data, time_var = "week", p_var = "yprev")

plot_transitions(
  fit,
  times = 1:7,
  variables = list(tx = c(0, 1)),
  comparison = "difference",
  y_levels = 1:8,
  absorb = 8
)
} # }