Plot Empirical or Model-Implied Correlations Over Time

plot_correlation() computes correlations between ordinal state scores at pairs of follow-up times. With a fitted Markov model, correlations are computed from model-implied pairwise moments rather than sampled paths.

Usage

plot_correlation(
  x,
  newdata = NULL,
  times = NULL,
  y_levels = NULL,
  absorb = NULL,
  id_var = "id",
  time_var = "time",
  y_var = "y",
  p_var = "yprev",
  p2_var = NULL,
  facet_var = NULL,
  gap_var = NULL,
  time_covariates = NULL,
  seed = NULL,
  n_draws = 100L,
  triangle = c("upper", "full"),
  show_values = TRUE,
  digits = 2,
  fill_limits = NULL,
  method = c("spearman", "pearson")
)

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.
times: Optional time values to include. Required for model-based plots.
y_levels: Optional state levels. If supplied for raw trajectory data, state scores follow this order.
absorb: Optional absorbing-state label for model-based recursions.
id_var: Character ID column for raw data and stored model-data extraction.
time_var: Character name of the time column.
y_var: Character name of the state column in raw trajectory data.
p_var: Character name of the previous-state column for model recursions.
p2_var: Optional second previous-state column for second-order model recursions.
facet_var: Optional grouping variable. Correlations are computed separately within each observed stratum.
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.
triangle: "upper" to show one triangle or "full" to show both off-diagonal triangles.
show_values: Logical. If TRUE, print rounded correlations in tiles.
digits: Number of digits used for tile labels.
fill_limits: Optional fill-scale limits. By default (NULL), use c(0, 1) when all available correlations are nonnegative, and c(-1, 1) when any are negative or all are missing. Supply limits explicitly to use the same color scale across several plots.
method: Correlation method: "spearman" (default) or "pearson".

Value

A ggplot object.

Details

Minimum inputs depend on the object type. For trajectory data, object must contain the ID, time, and state columns named by id_var, time_var, and y_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 needed. Model-based correlations are computed from exact first- or second-order Markov recursions. For blrm fits, posterior draws are kept separate through the moment calculation and summarized only after correlations are computed for each draw.

Spearman correlation is the default: it measures association between patients' ranks at two times, assigning average ranks to tied states. Observed-data calculations use patients observed at both times and rank each pair separately. Model-based calculations use the corresponding ranks from each time's state probabilities, averaged over prediction profiles within each stratum. Ranks are calculated separately for each posterior draw before summarizing. Correlations are undefined when either time has no variation in state.

With method = "pearson", correlations describe numerical state scores. Model-based scores are positions in y_levels (1 through the number of states). Observed scores use y_levels positions when supplied, factor codes for factors, or integer state values. Use the same y_levels for comparisons. Pearson is useful when differences between these scores are meaningful.

Examples

if (FALSE) { # \dontrun{
plot_correlation(data, id_var = "id", time_var = "day")
plot_correlation(fit, times = 1:14, y_levels = 1:8, absorb = 8)
} # }