plotLongitudinalBySubject: 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
)

Value

A ggplot object.

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.

Examples

Run this code

if (FALSE) {
  ## 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))
}