plotLongitudinalBySubject: Plot longitudinal data with robustness-weight colored lines

In robustlmm: Robust Linear Mixed Effects Models

Plot longitudinal data with robustness-weight colored lines

Description

Creates a visualization of longitudinal data with one facet per treatment group. Subject trajectories are colored by their robustness weight from a robust mixed-effects model fit, with darker lines indicating lower weights (potential outliers). Fixed-effect predictions are overlaid as reference lines.

Usage

plotLongitudinalBySubject(
  data,
  formula = NULL,
  idVar = "id",
  timeVar = "time",
  treatmentVar = "treatment",
  responseVar = "y",
  rlmerArgs = list(),
  lineAlpha = 0.6,
  fixedLineWidth = 1.2,
  lowColor = "black",
  highColor = "lightgray",
  fixedLineColor = "firebrick",
  fixedLinetype = "solid",
  title = NULL,
  xlab = NULL,
  ylab = NULL
)

Arguments

data	A data frame containing longitudinal data. Must have columns for subject ID, time, treatment group, and response variable.
formula	A formula for the mixed-effects model. Default is y ~ treatment * time + (1 + time | id) where y, treatment, time, and id refer to the standardized internal column names (mapped from responseVar, treatmentVar, timeVar, and idVar).
idVar	Character string naming the subject ID column in data. Default: "id".
timeVar	Character string naming the time column in data. Default: "time".
treatmentVar	Character string naming the treatment column in data. Default: "treatment".
responseVar	Character string naming the response column in data. Default: "y".
rlmerArgs	A list of additional arguments passed to rlmer.
lineAlpha	Numeric in [0, 1]. Transparency of subject lines. Default: 0.6.
fixedLineWidth	Numeric. Width of fixed-effect overlay lines. Default: 1.2.
lowColor	Color for low robustness weights (potential outliers). Default: "black".
highColor	Color for high robustness weights (typical observations). Default: "lightgray".
fixedLineColor	Color for the fixed-effect prediction lines. Default: "firebrick".
fixedLinetype	Linetype for the fixed-effect prediction lines. Can be a single value (e.g., "solid", "dashed") applied to all lines, or "byTreatment" to use different linetypes for each treatment group. Default: "solid".
title	Optional plot title.
xlab	Label for x-axis. If NULL (default), uses the value of timeVar.
ylab	Label for y-axis. If NULL (default), uses the value of responseVar.

Details

The function fits a robust linear mixed-effects model using rlmer and extracts the robustness weights for the random effects. Subjects with low weights (shown in darker colors) are those whose random effects deviate substantially from the assumed distribution.

The fixed-effect prediction lines show the population-average trajectory for each treatment group, ignoring random effects.

Value

A ggplot object.

See Also

rlmer, generateLongitudinalDatasets

Examples

## Not run: 
  ## Using the medication dataset from confintROB
  library(confintROB)
  plotLongitudinalBySubject(
    medication,
    idVar = "id",
    treatmentVar = "treat",
    responseVar = "pos"
  )

  ## Using simulated data
  set.seed(123)
  simdat <- generateLongitudinalDatasets(
    numberOfDatasetsToGenerate = 1,
    numberOfSubjects = 40,
    numberOfTimepoints = 7,
    numberOfTreatmentLevels = 2,
    timeRange = c(0, 18),
    trueBeta = c(200, -2, -5, 3),
    trueSigma = 30
  )
  plotLongitudinalBySubject(simdat$generateData(1))

## End(Not run)

robustlmm documentation built on Jan. 29, 2026, 1:10 a.m.