Plot Average Time in States

Plots output from avg_time(), either as stacked horizontal bars that divide follow-up into the average time spent in each state, or as points with confidence intervals.

Usage

plot_time(
  x,
  type = c("bar", "pointrange"),
  group_var = NULL,
  facet_var = NULL,
  scale = c("time", "proportion"),
  show_labels = TRUE,
  digits = 1,
  show_uncertainty = TRUE,
  bar_width = 0.6,
  point_size = 2,
  line_width = 0.7
)

Arguments

x

A markov_avg_time object returned by avg_time(), optionally after inferences().

type

Character string. The kind of plot:

• "bar" (the default): one horizontal bar per scenario, split into the average time in each state set ("Grotta bars"). Use it to show how follow-up is shared between states. Confidence intervals cannot be shown on stacked segments, so this type ignores them.

• "pointrange": states along the x axis, with one point per scenario and a vertical confidence interval when x has conf.low and conf.high. Scenarios are drawn in black and successively lighter shades of gray, so the plot prints well. Use it to show the uncertainty of each average.

group_var

Character vector or NULL. Columns that identify the scenarios being compared, for example the treatment variable set by variables. They label the bars (type = "bar") or set the point colors (type = "pointrange"). If NULL, every column other than state_set, the estimates, and those in facet_var is used. Several columns are combined into one label.

facet_var

Character vector or NULL. Optional faceting variable, for example a by variable. Use a length-two vector for facet_grid(row ~ column).

scale

Character string. "time" (the default) plots average time in the units of x. "proportion" divides each average by the scenario's total follow-up, so a bar spans 0 to 1. "proportion" requires every state to belong to exactly one state set.

show_labels

Logical. For type = "bar", print each segment's value inside it. Segments shorter than 6% of the longest bar are left unlabeled because the label would not fit.

digits

Number of decimal places for segment labels.

show_uncertainty

Logical. For type = "pointrange", draw confidence intervals when conf.low and conf.high exist.

bar_width

Numeric bar thickness for type = "bar".

point_size

Numeric point size for type = "pointrange".

line_width

Numeric line width for interval lines.

Value

A ggplot object.

Details

A stacked bar only makes sense when no state is counted twice. With type = "bar", the state sets in x must therefore not overlap, which holds for the default state_sets = NULL of avg_time() (every state separately). When the sets also include every state, each bar's length is the total follow-up: the number of visits, or the elapsed time covered when avg_time() used time_map.

To compare scenarios with a confidence interval for the difference, use avg_comparisons(estimand = "time_in_state") and plot_comparisons().

Examples

if (FALSE) { # \dontrun{
tis <- avg_time(
  fit,
  variables = list(tx = c(0, 1)),
  times = 1:28,
  absorb = "6"
) |>
  inferences(method = "delta")

# How the 28 days are divided between states in each arm
plot_time(tis)

# Average days in each state with 95% confidence intervals
plot_time(tis, type = "pointrange")
} # }