Package 'nlmixr2save'

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

x	the name of the object to assign the value to
value	the value to assign to the object, because R can use non-standard evaluation, this expression may not be evaluated when passed to the function. In the case of the nlmixr2 function, the expression will be evaluated only if the fit needs to be refit (i.e. if the zip file does not exist or if the sha1 hash of the arguments does not match).

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

---

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()

---

Load a fitted model object from a file

Description

Load a fitted model object from a file

Usage

loadFit(file)

Arguments

file	the base name of the files to load the fit from.

Value

the fitted model object

---

Standardize and simplify data for nlmixr2 estimation

Description

This function is typically not needed by end users.

Usage

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

Arguments

data	nlmixr data
object	an nlmixr_ui object (e.g. the output of running nlmixr(object = model)
table	The output table control object (like 'tableControl()')

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

fit	the fitted model object
file	the base name of the files to save the fit to.
zip	Boolean indicating if the files should be zipped.

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

---

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

fun	Function name(s) to add or remove. If NULL, the current registry is returned without modification.
remove	Boolean indicating if fun should be removed from the registry instead of added.

Value

Character vector of registered function names.

Author(s)

Matthew L. Fidler

Examples

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

---