modelGraph: Build a compartment graph from a model's differential...

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

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

object	model to diagram: a model function, an rxode2 user interface (rxUi) object, a compiled rxode2 model or a fitted nlmixr2 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.

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)

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