Plot the estimated subject-specific or marginal longitudinal trajectory

This generic plot method for predict.stanjm objects will plot the estimated subject-specific or marginal longitudinal trajectory using the data frame returned by a call to posterior_traj. To ensure that enough data points are available to plot the longitudinal trajectory, it is assumed that the call to posterior_traj would have used the default interpolate = TRUE, and perhaps also extrapolate = TRUE (the latter being optional, depending on whether or not the user wants to see extrapolation of the longitudinal trajectory beyond the last observation time).

# S3 method for predict.stanjm
plot(
  x,
  ids = NULL,
  limits = c("ci", "pi", "none"),
  xlab = NULL,
  ylab = NULL,
  vline = FALSE,
  plot_observed = FALSE,
  facet_scales = "free_x",
  ci_geom_args = NULL,
  grp_overlay = FALSE,
  ...
)

Arguments

x	A data frame and object of class predict.stanjm returned by a call to the function posterior_traj. The object contains point estimates and uncertainty interval limits for the fitted values of the longitudinal response.
ids	An optional vector providing a subset of subject IDs for whom the predicted curves should be plotted.
limits	A quoted character string specifying the type of limits to include in the plot. Can be one of: "ci" for the Bayesian posterior uncertainty interval for the estimated mean longitudinal response (often known as a credible interval); "pi" for the prediction interval for the estimated (raw) longitudinal response; or "none" for no interval limits.
xlab, ylab	An optional axis label passed to labs.
vline	A logical. If TRUE then a vertical dashed line is added to the plot indicating the event or censoring time for the individual. Can only be used if each plot within the figure is for a single individual.
plot_observed	A logical. If TRUE then the observed longitudinal measurements are overlaid on the plot.
facet_scales	A character string passed to the scales argument of facet_wrap when plotting the longitudinal trajectory for more than one individual.
ci_geom_args	Optional arguments passed to geom_ribbon and used to control features of the plotted interval limits. They should be supplied as a named list.
grp_overlay	Only relevant if the model had lower level units clustered within an individual. If TRUE, then the fitted trajectories for the lower level units will be overlaid in the same plot region (that is, all lower level units for a single individual will be shown within a single facet). If FALSE, then the fitted trajectories for each lower level unit will be shown in a separate facet.
...	Optional arguments passed to geom_smooth and used to control features of the plotted longitudinal trajectory.

Value

A ggplot object, also of class plot.predict.stanjm. This object can be further customised using the ggplot2 package. It can also be passed to the function plot_stack_jm.

See also

posterior_traj, plot_stack_jm, posterior_survfit, plot.survfit.stanjm

Examples

# \donttest{
  # Run example model if not already loaded
  if (!exists("example_jm")) example(example_jm)
#> 
#> exmpl_>   # set.seed(123)
#> exmpl_>   if (.Platform$OS.type != "windows" || .Platform$r_arch !="i386")
#> exmpl_+   example_jm <- 
#> exmpl_+      stan_jm(formulaLong = logBili ~ year + (1 | id), 
#> exmpl_+              dataLong = pbcLong[1:101,],
#> exmpl_+              formulaEvent = survival::Surv(futimeYears, death) ~ sex + trt, 
#> exmpl_+              dataEvent = pbcSurv[1:15,],
#> exmpl_+              time_var = "year",
#> exmpl_+              # this next line is only to keep the example small in size!
#> exmpl_+              chains = 1, seed = 12345, iter = 100, refresh = 0)
#> Fitting a univariate joint model.
#> 
#> Please note the warmup may be much slower than later iterations!
#> Warning: The largest R-hat is 1.24, indicating chains have not mixed.
#> Running the chains for more iterations may help. See
#> http://mc-stan.org/misc/warnings.html#r-hat
#> Warning: Bulk Effective Samples Size (ESS) is too low, indicating posterior means and medians may be unreliable.
#> Running the chains for more iterations may help. See
#> http://mc-stan.org/misc/warnings.html#bulk-ess
#> Warning: Tail Effective Samples Size (ESS) is too low, indicating posterior variances and tail quantiles may be unreliable.
#> Running the chains for more iterations may help. See
#> http://mc-stan.org/misc/warnings.html#tail-ess

  # For a subset of individuals in the estimation dataset we will
  # obtain subject-specific predictions for the longitudinal submodel 
  # at evenly spaced times between 0 and their event or censoring time.
  pt1 <- posterior_traj(example_jm, ids = c(7,13,15), interpolate = TRUE)
  plot(pt1)                  # credible interval for mean response
#> `geom_smooth()` using formula 'y ~ x'
#> `geom_smooth()` using formula 'y ~ x'
#> `geom_smooth()` using formula 'y ~ x'
  plot(pt1, limits = "pi")   # prediction interval for raw response
#> `geom_smooth()` using formula 'y ~ x'
#> `geom_smooth()` using formula 'y ~ x'
#> `geom_smooth()` using formula 'y ~ x'
  plot(pt1, limits = "none") # no uncertainty interval
#> `geom_smooth()` using formula 'y ~ x'

  # We can also extrapolate the longitudinal trajectories.
  pt2 <- posterior_traj(example_jm, ids = c(7,13,15), interpolate = TRUE,
                        extrapolate = TRUE)
  plot(pt2)
#> `geom_smooth()` using formula 'y ~ x'
#> `geom_smooth()` using formula 'y ~ x'
#> `geom_smooth()` using formula 'y ~ x'
  plot(pt2, vline = TRUE)    # add line indicating event or censoring time
#> `geom_smooth()` using formula 'y ~ x'
#> `geom_smooth()` using formula 'y ~ x'
#> `geom_smooth()` using formula 'y ~ x'
  plot(pt2, vline = TRUE, plot_observed = TRUE)  # overlay observed longitudinal data
#> `geom_smooth()` using formula 'y ~ x'
#> `geom_smooth()` using formula 'y ~ x'
#> `geom_smooth()` using formula 'y ~ x'

  # We can change or add attributes to the plot
  plot1 <- plot(pt2, ids = c(7,13,15), xlab = "Follow up time",
                     vline = TRUE, plot_observed = TRUE,
                     facet_scales = "fixed", color = "blue", linetype = 2,
                     ci_geom_args = list(fill = "red"))
#> `geom_smooth()` using formula 'y ~ x'
#> `geom_smooth()` using formula 'y ~ x'
  plot1
#> `geom_smooth()` using formula 'y ~ x'

  # Since the returned plot is also a ggplot object, we can
  # modify some of its attributes after it has been returned
  plot1 +
    ggplot2::theme(strip.background = ggplot2::element_blank()) +
    ggplot2::labs(title = "Some plotted longitudinal trajectories")
#> `geom_smooth()` using formula 'y ~ x'
# }