MonolixSuite in R
Auto Light Dark
MonolixSuite in R
Auto Light Dark
Breadcrumbs

plotAbsIWRESScatterPlot()

Scatter plot of the absolute individual weighted residuals |IWRES| versus time and/or individual predictions, with a half-normal reference distribution. Since IWRES ~ N(0, 1) then |IWRES| follows a half-normal distribution. Supports empirical/predicted percentiles, VPC-style prediction-interval bands, outlier highlighting, binning, stratification, and full visual customization. The data are read from the project's exported predictions.txt (indivPred_* / indWRes_* columns).

Usage

R
plotAbsIWRESScatterPlot(
  obsName            = NULL,
  xaxis              = c("time", "prediction"),
  settings           = list(),
  stratify           = list(),
  preferences        = list()
  )

Arguments

  • obsName (character) Name of the observation (in dataset header). By default the first observation is used. For multiple modelled outputs, the matching predictions_<output>_<obsName>.txt file is used and a message reports which observation was selected.

  • xaxis (character) Which x-axis to display: time ("time") and/or individual prediction ("prediction"). Default c("time", "prediction") (both).

  • settings (list) Display and computation settings:

    • indivEstimate (character) Calculation of individual estimates: conditional mean ("mean") or conditional mode with EBEs ("mode") (default "mode"). The conditional distribution ("simulated") is not available from predictions.txt.

    • level (integer) Level for prediction-interval computation (default 90).

    • higherPercentile (integer) Higher percentile for empirical and predicted percentiles (default 90). The lower percentile is 100 - higherPercentile, and the median (50th) is always shown.

    • useCensored (logical) Use BLQ data (TRUE) or ignore it (FALSE) when computing the statistics (default TRUE).

    • censoring (character) BLQ residuals are either simulated ("simulated") from the distribution truncated to the censoring interval, or set to the limit of quantification ("loq") (default "simulated").

    • binsSettings (list) Binning settings:

      • criteria (character) Binning criteria: "equalwidth", "equalsize", or "leastsquare" (default "leastsquare").

      • is.fixedNbBins (logical) If TRUE, use a fixed number of bins; otherwise a range for automatic selection (default TRUE).

      • nbBins (integer) Fixed number of bins (default 5).

      • binRange (integer vector) Range for the number of bins (default c(5, 100)). Note: automatic bin-count selection is not fully implemented; when is.fixedNbBins = FALSE, the lower bound binRange[1] is used as the number of bins.

      • nbBinData (integer vector) Range for the number of data points per bin (default c(5, 200)). Currently not used.

    • residuals (logical) If TRUE, display the |IWRES| dots (default TRUE).

    • empPercentiles (logical) If TRUE, display empirical percentiles (default FALSE).

    • predPercentiles (logical) If TRUE, display predicted (half-normal) percentiles (default FALSE).

    • predInterval (logical) If TRUE, display the prediction interval (default FALSE).

    • outlierDots (logical) If TRUE, add red dots marking empirical percentiles outside the prediction intervals (default TRUE).

    • outlierAreas (logical) If TRUE, add red areas between an empirical percentile and the prediction-interval bound it violates (default TRUE).

    • spline (logical) If TRUE, display a smoothing spline (default FALSE).

    • binLimits (logical) If TRUE, add bin limits as vertical lines (default FALSE).

    • linearInterpolation (logical) If TRUE, the prediction-interval bands, empirical percentiles and outlier areas are linearly interpolated between bin centres; if FALSE, they are drawn as steps spanning each bin (default TRUE).

    • legend (logical) Add (TRUE) / remove (FALSE) the plot legend (default FALSE).

    • grid (logical) Add (TRUE) / remove (FALSE) the plot grid (default TRUE).

    • footnote (logical) If TRUE, add a footnote below the plot giving the Monolix project directory and the R script path, styled like the table footers (small, italic, left-aligned) (default FALSE).

    • ncol (integer) Number of columns for the x-axis facets when no split is applied (default 4).

  • stratify (list) Stratification arguments:

    • groups Definition of stratification groups. By default, one group per category for categorical covariates, and two equal-sized groups (split at the median) for continuous covariates. To redefine, for each covariate give a list with name (e.g. "AGE") and definition (continuous: a vector of break values, e.g. c(35, 65); categorical: groups of categories as a list of vectors, e.g. list(c("study101"), c("study201","study202"))).

    • split (character vector) Covariates used to split (facet) the plot rows (default none), e.g. c("SEX").

    • filter (list of pairs) Each pair is a covariate name and a vector of group indices (continuous) or category names (categorical) to keep, e.g. list(list("AGE", c(1, 3)), list("SEX", "F")).

    • color (character vector) Covariates used for point colouring (default none), e.g. c("SEX").

    • colors Vector of colours to use when color is set; takes precedence over colours in preferences, e.g. c("#CD9B1D", "#CD6090").

    • mergedSplits (logical) When TRUE and split is used, split groups are shown on the same panel with different colours instead of separate rows (default FALSE).

    • individualSelection List with ids: character vector of individual ids to display, e.g. list(ids = c("101-01","101-02")).

  • preferences (list) Visual preferences; each element is a list of aesthetics for one plot component:

    • point Observed |IWRES| dots: color, size.

    • censored Censored (BLQ) dots: color, size.

    • empPercentile Empirical percentile lines: color, linewidth.

    • predPercentile Predicted (half-normal) percentile lines: color, linewidth, linetype.

    • predInterval Prediction-interval bands: medianFill, medianAlpha (50th-percentile band) and outerFill, outerAlpha (lower/upper bands).

    • outlier Outlier dots: color, size.

    • outlierArea Outlier areas: fill, alpha.

    • spline Smoothing spline: color, linewidth.

    • binLimit Bin-limit vertical lines: color, linewidth, linetype.

Returns: A ggplot object.

Details: Under the model IWRES ~ N(0, 1), so |IWRES| is half-normal and the p-th predicted percentile is qnorm((1 + p) / 2). The prediction interval is a VPC-style band obtained by simulating the empirical percentile of n i.i.d. |N(0, 1)| draws per bin. Censoring is read from the interpreted dataset (getInterpretedData) and joined to the residuals by id and time; with censoring = "simulated", BLQ residuals are drawn from the distribution truncated to the censoring interval.

Examples

Last updated: