Package {nlmixr2plot}

Title:	Nonlinear Mixed Effects Models in Population PK/PD, Plot Functions
Version:	5.2.0
Description:	Fit and compare nonlinear mixed-effects models in differential equations with flexible dosing information commonly seen in pharmacokinetics and pharmacodynamics (Almquist, Leander, and Jirstrand 2015 <doi:10.1007/s10928-015-9409-1>). Differential equation solving is by compiled C code provided in the 'rxode2' package (Wang, Hallow, and James 2015 <doi:10.1002/psp4.12052>). This package is for 'ggplot2' plotting methods for 'nlmixr2' objects.
License:	GPL (≥ 3)
URL:	https://github.com/nlmixr2/nlmixr2plot, https://nlmixr2.github.io/nlmixr2plot/
BugReports:	https://github.com/nlmixr2/nlmixr2plot/issues/
Depends:	R (≥ 4.3.0)
Imports:	ggforce, ggplot2 (≥ 3.4.0), ggtibble (≥ 1.0.4), nlmixr2est, nlmixr2extra (≥ 5.0.0), rxode2, stats, tidyr, utils, xgxr
Suggests:	DiagrammeR, knitr, rmarkdown, testthat (≥ 3.0.0), data.table, dplyr, withr, vpc, tidyvpc, nlmixr2data
VignetteBuilder:	knitr
Config/testthat/edition:	3
Encoding:	UTF-8
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-09-22 23:18:19 UTC; matt-fidler
Author:	Matthew Fidler [aut, cre], Bill Denney [ctb], Wenping Wang [aut], Vipul Mann [aut]
Maintainer:	Matthew Fidler <matthew.fidler@gmail.com>
Repository:	CRAN
Date/Publication:	2026-09-22 23:50:08 UTC

Automatic model diagram

Description

Draws a compartment diagram of a model from its differential equations (see modelGraph() for how the equations are interpreted).

Usage

modelDiagram(
  object,
  dosing = NULL,
  data = NULL,
  engine = getOption("nlmixr2plot.diagram.engine"),
  labels = FALSE,
  ...
)

## S3 method for class 'nlmixr2ModelGraph'
plot(x, ..., engine = getOption("nlmixr2plot.diagram.engine"), labels = FALSE)

## S3 method for class 'rxUi'
plot(
  x,
  ...,
  dosing = NULL,
  data = NULL,
  engine = getOption("nlmixr2plot.diagram.engine"),
  labels = FALSE
)

## S3 method for class 'rxode2'
plot(
  x,
  ...,
  dosing = NULL,
  data = NULL,
  engine = getOption("nlmixr2plot.diagram.engine"),
  labels = FALSE
)

Arguments

Details

The layout follows common pharmacometric conventions: dosing and absorption/transit compartments are above the compartment they feed; the central compartment is in the middle with the compartments it exchanges mass with (peripheral compartments) to its left; unidirectional transfer (e.g. to a metabolite) and eliminations go below; compartments that interact with the model without mass transfer (e.g. effect compartments or pharmacodynamic models) go to the right, with their own inputs above, outputs below and exchange compartments further right.

Mass transfer is drawn with solid arrows; interactions without mass transfer are dashed (with a "tee" arrow head for inhibition and a "dot" arrow head when the direction is undetermined with DiagrammeR; dotted for inhibition and dot-dashed when undetermined with ggplot2).

plot() of an rxode2 user interface (rxUi) object, like rxode2::rxode2(modelFunction), or of a compiled rxode2 model draws its model diagram, so plot(rxode2(model)) is the same as modelDiagram(model). (A fitted nlmixr2 model keeps its goodness-of-fit plot(); use modelDiagram(fit) for its diagram.)

Value

the diagram drawn by the requested engine.

Author(s)

Matthew L. Fidler

See Also

Other model diagrams: modelGraph()

Examples

pk.turnover.emax <- function() {
  ini({
    tktr <- log(1)
    tka <- log(1)
    tcl <- log(0.1)
    tv <- log(10)
    poplogit <- 2
    tec50 <- log(0.5)
    tkout <- log(0.05)
    te0 <- log(100)
    prop.err <- 0.1
    pkadd.err <- 0.1
    pdadd.err <- 10
  })
  model({
    ktr <- exp(tktr)
    ka <- exp(tka)
    cl <- exp(tcl)
    v <- exp(tv)
    emax <- expit(poplogit)
    ec50 <- exp(tec50)
    kout <- exp(tkout)
    e0 <- exp(te0)
    DCP <- center / v
    PD <- 1 - emax * DCP / (ec50 + DCP)
    effect(0) <- e0
    kin <- e0 * kout
    d/dt(depot) <- -ktr * depot
    d/dt(gut) <- ktr * depot - ka * gut
    d/dt(center) <- ka * gut - cl / v * center
    d/dt(effect) <- kin * PD - kout * effect
    cp <- center / v
    cp ~ prop(prop.err) + add(pkadd.err)
    effect ~ add(pdadd.err)
  })
}
modelDiagram(pk.turnover.emax, engine = "ggplot2")
if (requireNamespace("DiagrammeR", quietly = TRUE)) {
  modelDiagram(pk.turnover.emax, engine = "DiagrammeR")
}

Build a compartment graph from a model's differential equations

Description

The differential equations are parsed into additive terms. A term that is subtracted from one compartment and added (identically) to another is mass transfer between the two compartments. A remaining subtracted term that contains the compartment's own amount is an elimination (output); a remaining term that depends on other compartments is an interaction that does not transport mass (for example an effect compartment or a pharmacodynamic stimulation/inhibition); a remaining added term that does not depend on any other compartment is a (zero-order) input. Dependencies through intermediate variables (like cp <- central/v) are followed. A compartment that drives a transfer between two other compartments (like an enzyme) is drawn as an interaction with the destination. Production or loss driven only by another compartment (like ke0*cp in an effect compartment) is represented by the interaction arrow alone, without a separate input/output arrow.

Usage

modelGraph(object, dosing = NULL, data = NULL)

Arguments

Details

Some limitations on how equations must be written:

• Mass transfer is only detected when the same term (up to reordering of the factors of a product) is subtracted from the source and added to the destination, e.g. d/dt(depot) <- -ka*depot and d/dt(central) <- ka*depot - .... Scaled transfer (like a stoichiometric or volume conversion in only one of the equations) is shown as an elimination plus an interaction.

• linCmt() models are converted to ODEs with rxode2::linToOde(), which requires a version of 'rxode2' that provides it.

Value

a nlmixr2ModelGraph object; a list with:

• nodes: data frame with the compartment name, its role ("dosing", "central", "peripheral", "transit", "metabolite", "effect" or "other"), whether it is dosing and the layout coordinates x and y, and an annotation with the compartment's dosing properties (lag, F, rate, dur; "" when there are none), which the diagrams show next to the compartment.

• edges: data frame with from, to (NA for inputs/eliminations), type ("transfer", "elimination", "input" or "interaction"), sign (1 when the term is added, -1 when it is subtracted; for interactions 1 is stimulation, -1 inhibition and 0 an effect whose direction cannot be determined from the equations, e.g. through ifelse() or a conditionally assigned variable), bidirectional (for transfers) and label (the model term(s)).

Author(s)

Matthew L. Fidler

See Also

Other model diagrams: modelDiagram()

Examples

one.cmt <- function() {
  ini({
    tka <- 0.45
    tcl <- 1
    tv <- 3.45
    add.sd <- 0.7
  })
  model({
    ka <- exp(tka)
    cl <- exp(tcl)
    v <- exp(tv)
    d/dt(depot) <- -ka * depot
    d/dt(central) <- ka * depot - cl / v * central
    cp <- central / v
    cp ~ add(add.sd)
  })
}
modelGraph(one.cmt)

Plot a nlmixr2 augPred object

Description

Plot a nlmixr2 augPred object

Usage

## S3 method for class 'nlmixr2AugPred'
plot(x, y, ..., log = "")

Arguments

Value

A ggtibble::gglist object (a list of ggplot2 objects, one per page of individual plots)

Examples

library(nlmixr2est)
## The basic model consiss of an ini block that has initial estimates
one.compartment <- function() {
  ini({
    tka <- 0.45 # Log Ka
    tcl <- 1 # Log Cl
    tv <- 3.45    # Log V
    eta.ka ~ 0.6
    eta.cl ~ 0.3
    eta.v ~ 0.1
    add.sd <- 0.7
  })
  # and a model block with the error sppecification and model specification
  model({
    ka <- exp(tka + eta.ka)
    cl <- exp(tcl + eta.cl)
    v <- exp(tv + eta.v)
    d/dt(depot) = -ka * depot
    d/dt(center) = ka * depot - cl / v * center
    cp = center / v
    cp ~ add(add.sd)
  })
}

## The fit is performed by the function nlmixr/nlmix2 specifying the model, data and estimate
fit <- nlmixr2est::nlmixr2(one.compartment, theo_sd,  est="saem",
                           saemControl(print=0, nBurn = 10, nEm = 20))

# augPred shows more points for the fit:

a <- nlmixr2est::augPred(fit)

# you can plot it with plot(augPred object)
plot(a)

# or with a log-scaled y axis
plot(a, log = "y")

Plot a nlmixr2 data object

Description

Plot some standard goodness of fit plots for the focei fitted object. When the model has between-subject variability (BSV), the returned collection also includes a nested "bsv" element (inside each data/compartment group) with QQ plots for each BSV parameter, BSV-BSV correlation plots (when more than one BSV parameter is present) and, when covariate is supplied, BSV-by-covariate plots.

Usage

## S3 method for class 'nlmixr2FitData'
plot(x, covariate = NULL, ...)

Arguments

Value

A named, nested ggtibble::gglist object (a list of ggplot2 objects with easier plotting of all of them at the same time)

Author(s)

Wenping Wang & Matthew Fidler

Examples

library(nlmixr2est)
one.compartment <- function() {
  ini({
    tka <- 0.45
    tcl <- 1
    tv <- 3.45
    eta.ka ~ 0.6
    eta.cl ~ 0.3
    eta.v ~ 0.1
    add.sd <- 0.7
  })
  model({
    ka <- exp(tka + eta.ka)
    cl <- exp(tcl + eta.cl)
    v <- exp(tv + eta.v)
    d/dt(depot) = -ka * depot
    d/dt(center) = ka * depot - cl / v * center
    cp = center / v
    cp ~ add(add.sd)
  })
}

## The fit is performed by the function nlmixr/nlmix2 specifying the model, data and estimate
fit <- nlmixr2(one.compartment, theo_sd,  est="saem", saemControl(print=0, nBurn = 10, nEm = 20))

# This shows many goodness of fit plots
plot(fit)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

rxode2

geom_amt(), geom_cens(), stat_amt(), stat_cens()

Produce trace-plot for fit if applicable

Description

Produce trace-plot for fit if applicable

Usage

traceplot(x, ...)

## S3 method for class 'nlmixr2FitCore'
traceplot(x, ...)

Arguments

Value

Fit traceplot or nothing.

Author(s)

Rik Schoemaker, Wenping Wang & Matthew L. Fidler

Examples

library(nlmixr2est)
## The basic model consiss of an ini block that has initial estimates
one.compartment <- function() {
  ini({
    tka <- 0.45 # Log Ka
    tcl <- 1 # Log Cl
    tv <- 3.45    # Log V
    eta.ka ~ 0.6
    eta.cl ~ 0.3
    eta.v ~ 0.1
    add.sd <- 0.7
  })
  # and a model block with the error sppecification and model specification
  model({
    ka <- exp(tka + eta.ka)
    cl <- exp(tcl + eta.cl)
    v <- exp(tv + eta.v)
    d/dt(depot) = -ka * depot
    d/dt(center) = ka * depot - cl / v * center
    cp = center / v
    cp ~ add(add.sd)
  })
}

## The fit is performed by the function nlmixr/nlmix2 specifying the model, data and estimate
fit <- nlmixr2(one.compartment, theo_sd,  est="saem",
               saemControl(print=0, nBurn = 10, nEm = 20))

# This shows the traceplot of the fit (useful for saem)
traceplot(fit)

VPC based on ui model

Description

VPC based on ui model

Usage

vpcPlot(
  fit,
  data = NULL,
  n = 300,
  bins = "jenks",
  n_bins = "auto",
  bin_mid = "mean",
  show = NULL,
  stratify = NULL,
  pred_corr = FALSE,
  pred_corr_lower_bnd = 0,
  pi = c(0.05, 0.95),
  ci = c(0.05, 0.95),
  uloq = fit$dataUloq,
  lloq = fit$dataLloq,
  log_y = FALSE,
  log_y_min = 0.001,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  smooth = TRUE,
  vpc_theme = NULL,
  facet = "wrap",
  scales = "fixed",
  labeller = NULL,
  vpcdb = FALSE,
  verbose = FALSE,
  ...,
  seed = 1009,
  idv = "time",
  cens = FALSE,
  method = c("vpc", "tidyvpc")
)

vpcPlotTad(..., idv = "tad")

vpcCensTad(..., cens = TRUE, idv = "tad")

vpcCens(..., cens = TRUE, idv = "time")

Arguments

Value

Simulated dataset (invisibly)

Author(s)

Matthew L. Fidler

Examples

one.cmt <- function() {
 ini({
   tka <- 0.45; label("Ka")
   tcl <- log(c(0, 2.7, 100)); label("Cl")
   tv <- 3.45; label("V")
   eta.ka ~ 0.6
   eta.cl ~ 0.3
   eta.v ~ 0.1
   add.sd <- 0.7; label("Additive residual error")
 })
 model({
   ka <- exp(tka + eta.ka)
   cl <- exp(tcl + eta.cl)
   v <- exp(tv + eta.v)
   linCmt() ~ add(add.sd)
 })
}

fit <-
  nlmixr2est::nlmixr(
    one.cmt,
    data = nlmixr2data::theo_sd,
    est = "saem",
    control = nlmixr2est::saemControl(print = 0, nBurn = 10, nEm = 20)
  )

vpcPlot(fit, n = 100)