Create residual diagnostic plots — sg_gof

Generates residual diagnostic plots versus time/predictions from GFO $SDTAB. Supports faceting, covariate coloring, quantile binning for continuous covariates, and optional smoothing.

Usage

sg_gof_res(
  fpath_i,
  DVID = 1,
  cov_cols = NULL,
  indiv = TRUE,
  vs_time = TRUE,
  weighted = TRUE,
  addline = TRUE,
  alpha_i = 0.5,
  smooth = TRUE,
  log_x = FALSE,
  abreaks = scales::pretty_breaks(7),
  lab_y = NULL,
  lab_x = NULL,
  col_i = NULL,
  col_lab = NULL,
  facet_i = NULL,
  f_scales = "fixed",
  n_bins = 50,
  min_y = NA,
  max_y = NA,
  min_x = NA,
  max_x = NA,
  legend_fl = FALSE,
  n_quantiles = 3,
  levels_discrete = 10
)

Arguments

fpath_i: String, GFO, or a named list with a GFO component (and optionally GCO). If a string is given, the path to a .RData or .json file with a fit object is expected.
DVID: Restrict SDTAB to one observation type. Numeric values select the DVID column (default 1). If SDTAB has DVNAME, a character or factor is matched to DVNAME first; otherwise a digit-only string is coerced to numeric DVID.
cov_cols: A character vector specifying the names of the columns with covariates.
indiv: Logical. If TRUE, use individual predictions ("IPRED"); otherwise use population predictions ("PRED"). Default is TRUE.
vs_time: Logical. If TRUE, plot residuals vs TIME; otherwise, plot residuals vs predictions (IPRED/PRED).
weighted: Logical. If TRUE, use weighted residuals; otherwise, use RES/IRES
addline: Logical. If TRUE, lines connecting observations of individual subjects will be added. Default is TRUE.
alpha_i: Numeric. Transparency level (from 0 to 1) for points/lines. Default is 0.5.
smooth: Logical. Add LOESS smooth line. Default is TRUE.
log_x: Logical. If TRUE, a logarithmic scale is applied to x-axis. Default is FALSE.
abreaks: A function that generates axis breaks. Default is scales::pretty_breaks(7).
lab_y: String. Y-axis label.
lab_x: String. X-axis label.
col_i: String. Column name for color
col_lab: String. Label for color legend
facet_i: Character vector. Column name(s) for facet panels. Multiple columns are combined with + in facet_wrap. Default is NULL.
f_scales: String, one of "fixed", "free", "free_x", "free_y". User can specify whether the scales (x and y axes) should be fixed across all panels ("fixed"), free for each panel ("free"), or free only in one dimension ("free_x" or "free_y"). Default is "fixed"
n_bins: Integer. Number of bins to use in the histogram. Default is 30.
min_y: Numeric. Y-axis minimum limit. Default is NA.
max_y: Numeric. Y-axis maximum limit. Default is NA.
min_x: Numeric. X-axis minimum limit. Default is NA.
max_x: Numeric. X-axis maximum limit. Default is NA.
legend_fl: Logical. Show legend. Default is FALSE.
n_quantiles: Integer. Number of quantile groups for continuous variables in col_i. Default is 3.
levels_discrete: Integer. Maximum unique values to consider a variable discrete. Default is 10.

Value

A ggplot2 object

Examples

# Basic example with mock data
set.seed(123)  # For reproducibility
n_subjects <- 50
mock_obj <- list(
  SDTAB = do.call(rbind, lapply(1:n_subjects, function(id) {
    n_obs <- 6
    times <- sort(runif(n_obs, min = 0, max = 24))  # random times between 0 and 24h
    data.frame(
      ID    = id,
      TIME  = times,
      DV    = rnorm(n_obs, mean = 10, sd = 2),
      PRED  = rnorm(n_obs, mean = 10, sd = 1.5),
      IPRED = rnorm(n_obs, mean = 10, sd = 1.2),
      IWRES = rnorm(n_obs, mean = 0, sd = 0.8),
      IRES  = rnorm(n_obs, mean = 0, sd = 1.2),
      MDV   = 0
    )
  })),
  COTAB = data.frame(
    ID  = 1:n_subjects,
    AGE = sample(20:80, n_subjects, replace = TRUE)
  ),
  CATAB = data.frame(
    ID   = 1:n_subjects,
    RACE = sample(c("Hispanic", "Asian", "Caucasian"), n_subjects, replace = TRUE)
  )
)

# Basic plot: individual weighted residuals vs TIME (weighted = TRUE, vs_time = TRUE)
p <- sg_gof_res(mock_obj, smooth = FALSE)
p


# With covariates and faceting (use RACE as facet and AGE as color)
p <- sg_gof_res(
  mock_obj,
  smooth = TRUE,
  cov_cols = c("RACE","AGE"),
  col_i = "RACE",
  facet_i = "AGE",
  indiv = TRUE,
  weighted = TRUE,
  vs_time = FALSE,
  legend_fl = TRUE
)
p