DMAR (version 1.0.0)

plot_trajectories_fitted: Plot Observed and Fitted Individual Trajectories From a Multilevel Model

Description

Given a fitted lme/nlme (nlme) or lmer (lme4) model, plots each subject's observed values and fitted curve on a smooth time grid, faceted one panel per subject. Per-subject \(R^2\) (squared correlation between observed and fitted values) and root-mean-square error are computed and attached to the returned ggplot2 object as the quality_of_fit attribute.

Usage

plot_trajectories_fitted(
  model,
  id = NULL,
  time = NULL,
  outcome = NULL,
  ids = NULL,
  n_random = NULL,
  pct_random = NULL,
  n_grid = 100,
  show_points = TRUE,
  point_size = 1.5,
  linewidth = 0.6,
  alpha = 0.8,
  palette = "okabe_ito",
  nrow = NULL,
  ncol = NULL,
  show_quality = TRUE,
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  seed = NULL
)

Value

A ggplot object. The per-subject quality-of-fit

data.frame (columns: id column, r_squared, rmse) is attached as attr(<plot>, "quality_of_fit").

Arguments

model

A fitted model object of class lme, nlme, or lmerMod.

id, time, outcome

Optional character names of the ID, time, and outcome columns. When NULL (the default), each is auto-detected from the model object: the outcome is the response variable in the formula, the ID is the first random-effect grouping factor, and time is the first fixed-effect predictor. Override these when the auto-detection is wrong.

ids, n_random, pct_random

Subject-subsetting options identical to those of plot_trajectories; at most one may be supplied.

n_grid

Integer. Number of points used to draw each subject's smooth fitted curve (default 100).

show_points

Logical. Whether to draw the observed values (default TRUE).

point_size, linewidth, alpha, nrow, ncol

Visual / layout controls.

palette

Character string naming the color palette; the fitted curve is drawn in the palette's primary color. Defaults to "okabe_ito", base R's colorblind-safe Okabe-Ito palette; "tableau" is also available.

show_quality

Logical. If TRUE (the default), each panel strip text includes the subject's \(R^2\) and RMSE.

title, xlab, ylab

Optional plot labels.

seed

Optional integer random seed used when n_random or pct_random is supplied. Defaults to NULL, which leaves the user's current RNG state intact; supply an integer for reproducible subject sampling.

Author

Ken Kelley [email protected]

Details

Modernizes the original vit_fitted() function by:

• returning a ggplot2 object instead of writing to graphics devices,

• attaching per-subject quality-of-fit as an attribute rather than assigning it into the global environment, a serious side effect of the original,

• drawing a smooth fitted curve from a per-subject time grid via predict(..., re.form = NULL) for lme4 fits and predict(..., level = 1) for nlme fits,

• correctly identifying lme4 fits (which use class lmerMod, not lmer).

See Also

plot_trajectories

Other plotting: plot_R2(), plot_cfa_k(), plot_ci(), plot_equivalence(), plot_forest(), plot_irt_information(), plot_mediation_mbco(), plot_randomization_test(), plot_regions_of_significance(), plot_smd(), plot_trajectories(), power_equivalence_md_plot()

Other within-subjects analysis: anova_within(), anova_within_two_way(), epsilon_corrections(), mauchly_test(), pairwise_within()

Examples

# nlme: linear growth in tooth distance over age for the 27 Orthodont
# children. Four of the children are paneled here so the figure is
# quick to draw; drop n_random to get a panel for every child.
fm_nlme <- nlme::lme(distance ~ age, random = ~ age | Subject,
                     data = nlme::Orthodont)
p <- plot_trajectories_fitted(fm_nlme, n_random = 4, seed = 113)
p
attr(p, "quality_of_fit")  # per-subject R^2 and RMSE

# An lme4 fit is handled the same way: the outcome, the subject
# identifier, and the time variable are read from the model. Six of
# the eighteen sleepstudy subjects are paneled here.
fm_lme4 <- lme4::lmer(Reaction ~ Days + (Days | Subject),
                      data = lme4::sleepstudy)
plot_trajectories_fitted(fm_lme4, n_random = 6, seed = 113)