modelDiagram: Automatic model diagram

In nlmixr2plot: Nonlinear Mixed Effects Models in Population PK/PD, Plot Functions

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

object	model to diagram (see modelGraph()) or a nlmixr2ModelGraph object.
dosing	optional character vector naming the dosing compartments. When NULL the dosing compartments are detected from the dosing records in data (a dataset without dose records has no dosing compartment); when there is no data, or it has no evid/amt columns, the first compartment (the default rxode2 dosing compartment) is used.
data	optional dataset used to detect the dosing compartments (from the dosing records' cmt). For fitted models this defaults to the data the model was fit with.
engine	drawing engine: "DiagrammeR" (a Graphviz htmlwidget from the 'DiagrammeR' package), "ggplot2" (a ggplot object) or "dot" (the Graphviz DOT source as a character string, to customize or render elsewhere). The default is "DiagrammeR" when that package is installed and "ggplot2" otherwise; it may be changed with options(nlmixr2plot.diagram.engine = ...).
labels	logical; when TRUE label the arrows with the model terms.
...	ignored.
x	a nlmixr2ModelGraph object, an rxode2 user interface (rxUi) object or a compiled rxode2 model

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")
}

nlmixr2plot documentation built on Sept. 23, 2026, 1:07 a.m.