Package {nlmixr2save}

Title:	Save 'nlmixr2' Fits in a Format Readable Outside 'nlmixr2'
Version:	0.1.0
Description:	Provides tools to save 'nlmixr2' fitted models in a portable format readable outside of 'nlmixr2' and independent of the package version. 'nlmixr2' fits and compares 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 uses compiled C code from the 'rxode2' package (Wang, Hallow, and James 2015 <doi:10.1002/psp4.12052>).
License:	MIT + file LICENSE
Encoding:	UTF-8
Imports:	checkmate, cli, digest, Rcpp, rxode2 (> 5.0.1), zip
Suggests:	babelmixr2, dplyr, knitr, nlmixr2data, nlmixr2est (≥ 5.0.2), PopED, rmarkdown, testthat (≥ 3.0.0), tidyvpc, withr
VignetteBuilder:	knitr
Config/testthat/edition:	3
LinkingTo:	Rcpp
Config/roxygen2/version:	8.0.0
NeedsCompilation:	yes
Packaged:	2026-06-09 23:13:12 UTC; FIDLEMA3
Author:	Matthew Fidler [aut, cre]
Maintainer:	Matthew Fidler <matthew.fidler@gmail.com>
Repository:	CRAN
Date/Publication:	2026-06-17 13:50:02 UTC

This returns or assigns the environment used in the ⁠:=⁠ operator

Description

This returns or assigns the environment used in the ⁠:=⁠ operator

Usage

.assignParent(env = NULL)

Arguments

Value

the environment used in the ⁠:=⁠ operator

Author(s)

Matthew L. Fidler

Examples

.assignParent()

Return if the last ⁠:=⁠ assignment was actually a restore from a file

Description

Return if the last ⁠:=⁠ assignment was actually a restore from a file

Usage

.assignRestore()

Value

TRUE if the last ⁠:=⁠ assignment was a restore from a file, FALSE otherwise

Author(s)

Matthew L. Fidler

Examples

.assignRestore()

This gets the properties of the nlmixr2 call for saving and loading purposes

Description

This is used to:

• Determine if this is a simulation method like rxSolve

Usage

.nlmixr2saveProps(object, data, est = NULL, control = NULL, table = NULL, ...)

Arguments

Details

• Determine the simplified core dataset that is used for estimation that allows caching on the minimum dataset.

Value

A list containing

• object: the rxode2 model to be estimated

• data: the simplified dataset used for estimation

• est: the estimation method

• control: the control list used for estimation

• table: the table used for estimation

• shaOrig: the sha1 hash of the original data

• dataOrig: the original data

• sha: the sha1 hash of the list of properties used for estimation

Author(s)

Matthew L. Fidler

This assignment operator is meant to assign or load a nlmixr2 fit (and other objects)

Description

By default it is equivalent to the standard assignment operator ⁠<-⁠, but it is a S3 generic so it can have other behaviors for specific classes.

Arguments

Details

For example, when used with a nlmixr2 call, say:

fit := nlmixr2(one.cmt, theo_sd, est="focei")

the ⁠:=⁠ operator will assign the result of the nlmixr2 call to fit, but it will also save the fit to a file named "fit.zip" in the current working directory.

If the "fit.zip" file already exists, it will be loaded instead of running the possibly expensive fitting process (as long as the sha1 hash of the arguments are the same).

This allows for easy saving and loading of fitted models without having to explicitly call a save function.

This S3 generic can be extended to other classes as needed, allowing for custom behaviors when assigning values to objects of those classes.

When trying to save expensive evaluations like the output of a nlmixr2() fit, the s3 dispach would be to ⁠:=.assign_nlmixr2(x, value)⁠ or whatever function is used in the call. This allows checking the arguments to see if there can be a cache that will be loaded.

Otherwise, the default s3 method would be ⁠:=.class⁠ where class instead. Unlike the un-evaluated function dispach there is no way to check the arguments for a cache, so loading from cache is not possible.

Value

the value that was assigned to the object, invisibly. It also has the side effect of assigning the value to the parent environment.

Author(s)

Matthew L. Fidler

See Also

saveFit() for saving fitted model objects to files, loadFit() for loading fitted model objects from files, and .assignParent() for getting or setting the environment used in the ⁠:=⁠ operator.

Examples

 if (requireNamespace("nlmixr2est", quietly=TRUE) && requireNamespace("withr")) {
   library(nlmixr2est)
  library(nlmixr2data)
  withr::with_tempdir({
     one.cmt <- function() {
       ini({
         tka <- 0.45
         tcl <- log(c(0, 2.7, 100))
         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)
        linCmt() ~ add(add.sd)
       })
    }
    # First fit creates fit.zip
    fit := nlmixr2(one.cmt, theo_sd, est="focei")

    # Second fit loads from fit.zip since it had the same options
    fit := nlmixr2(one.cmt, theo_sd, est="focei")

    # Third fit refits since the options are different
    fit := nlmixr2(one.cmt, theo_sd, est="saem")
  })
 }

Load a fitted model object from a file

Description

Load a fitted model object from a file

Usage

loadFit(file)

Arguments

Value

the fitted model object

Fix nlmixr2 save output

Description

This function modifies the output of nlmixr2's save function to ensure that the "Estimate" and "SE" fields are numeric vectors with appropriate names, rather than data frames. This is necessary for compatibility with other functions that expect these fields to be numeric vectors.

Usage

nlmixr2saveParFixedDf(obj)

Arguments

Value

A modified data.frame object with "Estimate" and "SE" as named numeric vectors

Standardize and simplify data for nlmixr2 estimation

Description

This function is typically not needed by end users.

Usage

nlmixrDataSimplify(data, object, table = list())

Arguments

Details

The standardization keeps columns that rxode2 and nlmixr2 use along with the covariates. Column order is standardized (rxode2 then nlmixr2 then alphabetically sorted covariates), and rxode2 and nlmixr2 column names are converted to lower case.

Value

The data with the nlmixr2 column lower case and on the left and the covariate columns on the right and alphabetically sorted.

Author(s)

William S. Denney with minor modifications from Matt Fidler

Save a fitted model object to a series of files

Description

Save a fitted model object to a series of files

Usage

saveFit(fit, file, zip = TRUE)

## S3 method for class 'nlmixr2FitCore'
saveFit(fit, file, zip = TRUE)

## S3 method for class 'nlmixr2FitData'
saveFit(fit, file, zip = TRUE)

## Default S3 method:
saveFit(fit, file, zip = TRUE)

Arguments

Value

nothing, called for side effects

Author(s)

Matthew L. Fidler

Examples

  if (requireNamespace("nlmixr2est", quietly=TRUE) && requireNamespace("withr")) {
    library(nlmixr2est)
    library(nlmixr2data)
    withr::with_tempdir({
      one.cmt <- function() {
        ini({
          tka <- 0.45
          tcl <- log(c(0, 2.7, 100))
          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)
          linCmt() ~ add(add.sd)
        })
      }

      fit <- nlmixr2(one.cmt, theo_sd, est="focei")

      saveFit(fit) # saved to fit.zip
      fit2 <- loadFit(fit) # load fit.zip

      if (file.exists("fit.zip")) {
         unlink("fit.zip")
      }

      print(fit2)
    })
  }

Save a fitted model item to a file

Description

This is a generic function to save a fitted model item to a file.

Usage

saveFitItem(item, name, file)

## S3 method for class 'rxUi'
saveFitItem(item, name, file)

## S3 method for class 'data.frame'
saveFitItem(item, name, file)

## S3 method for class 'nlmixr2estSessionInfo'
saveFitItem(item, name, file)

## Default S3 method:
saveFitItem(item, name, file)

## S3 method for class 'saemFit'
saveFitItem(item, name, file)

## S3 method for class 'foceiModelList'
saveFitItem(item, name, file)

Arguments

Value

boolean to determine if the item was saved; if it wasn't it will be saved into the general list of items.

Author(s)

Matthew L. Fidler

Manage functions treated as random by ⁠:=⁠

Description

Functions registered here are saved with random-state metadata so cached restores behave like the original call was run again.

Usage

saveFitRandom(fun = NULL, remove = FALSE)

Arguments

Value

Character vector of registered function names.

Author(s)

Matthew L. Fidler

Examples

saveFitRandom()
saveFitRandom("myRandomFun")
saveFitRandom("myRandomFun", remove=TRUE)