Plot State Occupancy Probabilities Over Time

Creates a visualization showing empirical or model-derived state occupancy probabilities over time, with optional faceting by grouping variables (typically treatment). Can display as lines (default) or stacked bars.

Usage

plot_sops(
  x,
  time_var = "time",
  y_var = "y",
  facet_var = "tx",
  linetype_var = NULL,
  geom = c("line", "bar"),
  estimate_var = NULL,
  n_draws = 50,
  draw_alpha = 0.06,
  ribbon_alpha = 0.12,
  show_uncertainty = TRUE
)

Arguments

x

A data frame containing trajectory data, typically from sim_markov(), or a model-derived SOP summary such as a markov_avg_sops object from avg_sops() and inferences().

time_var

Character string. Name of the time variable column (default: "time").

y_var

Character string. Name of the observed state variable column for empirical trajectory data (default: "y").

facet_var

Character vector or NULL. Name of the variable to facet by (default: "tx"). Use a length-two vector for facet_grid(row ~ column). Set to NULL to disable faceting.

linetype_var

Character string or NULL. Name of the variable to map to linetype (default: NULL). Useful for comparing groups within the same plot. When both facet_var and linetype_var are specified, you can facet by one variable (e.g., site) and distinguish groups by linetype (e.g., treatment).

geom

Character string. Type of plot: "line" for line plot (default) or "bar" for stacked bar chart.

estimate_var

Character string or NULL. Name of the probability column for model-derived SOP summary data. Defaults to "estimate" when present.

n_draws

Integer. Maximum number of stored inference draws to overlay for markov_avg_sops bar plots. Draws are selected deterministically.

draw_alpha

Numeric. Alpha level for draw overlays in model-derived bar plots.

ribbon_alpha

Numeric. Alpha level for confidence bands in model-derived line plots.

show_uncertainty

Logical. If TRUE, add confidence ribbons for line plots and draw overlays for markov_avg_sops bar plots when available.

Value

A ggplot object showing state occupancy probabilities over time.

Details

This function creates a visualization of how the distribution of patients across states changes over time.

For empirical trajectory data, probabilities are computed from observed counts at each time point. For model-derived SOP summaries, the function uses the supplied probability column, usually estimate.

When geom = "line" (default), separate lines show the state occupancy probability for each state over time. Model-derived SOP summaries with conf.low and conf.high columns also show uncertainty bands.

When geom = "bar", each bar represents a time point with colors indicating the state occupancy probability for each state. If data is a markov_avg_sops object with stored draws from inferences(..., return_draws = TRUE), a deterministic subset of draws is overlaid with low alpha to show uncertainty in the stacked probabilities.

Faceting allows comparison between groups (e.g., treatment vs. control). The linetype_var parameter allows distinguishing groups by linetype instead of (or in addition to) faceting, enabling more flexible plot layouts.

plot_sops() adds viridis discrete color and fill scales by default. Add another scale_color_*() or scale_fill_*() layer to replace them. Summary data must have only one row for each plotted time, state, facet, and linetype combination.

Examples

if (FALSE) { # \dontrun{
# After simulating trajectories
trajectories <- sim_markov("violet", n_patients = 200, seed = 1)

# Basic line plot
plot_sops(trajectories)

# Stacked bar plot with faceting by treatment
plot_sops(trajectories, geom = "bar")

# Line plot with linetype by treatment (no faceting)
plot_sops(trajectories, geom = "line", facet_var = NULL, linetype_var = "tx")

# Facet by one variable, linetype by another
plot_sops(trajectories, facet_var = "site", linetype_var = "tx", geom = "line")

# Customize variable names
plot_sops(trajectories, time_var = "day", y_var = "state", facet_var = "treatment")
} # }