Using Pre-compiled models in your packages

If you have a package and would like to include pre-compiled RxODE models in your package it is easy to create the package. You simple make the package with the rxPkg() command.

library(RxODE);
## Now Create a model
idr <- RxODE({
    C2 = centr/V2;
    C3 = peri/V3;
    d/dt(depot) =-KA*depot;
    d/dt(centr) = KA*depot - CL*C2 - Q*C2 + Q*C3;
    d/dt(peri)  =                    Q*C2 - Q*C3;
    d/dt(eff)  = Kin - Kout*(1-C2/(EC50+C2))*eff;
})

## You can specify as many models as you want to add

rxPkg(idr, package="myPackage"); ## Add the idr model to your package

This will:

  • Add the model to your package; You can use the package data as idr once the package loads

  • Add the right package requirements to the DESCRIPTION file. You will want to update this to describe the package and modify authors, license etc.

  • Create skeleton model documentation files you can add to for your package documentation. In this case it would be the file idr-doc.R in your R directory

  • Create a configure and configure.win script that removes and regenerates the src directory based on whatever version of RxODE this is compiled against. This should be modified if you plan to have your own compiled code, though this is not suggested.

  • You can write your own R code in your package that interacts with the RxODE object so you can distribute shiny apps and similar things in the package context.

Once this is present you can add more models to your package by rxUse(). Simply compile the RxODE model in your package then add the model with rxUse()

rxUse(model)

Now both model and idr are in the model library. This will also create model-doc.R in your R directory so you can document this model.

You can then use devtools methods to install/test your model

devtools::load_all() # Load all the functions in the package
devtools::document() # Create package documentation
devtools::install() # Install package
devtools::check() # Check the package
devtools::build() # build the package so you can submit it to places like CRAN

Using Models in a already present package

To illustrate, lets start with a blank package

library(RxODE)
library(usethis)
pkgPath  <- file.path(rxTempDir(),"MyRxModel")
create_package(pkgPath);
use_gpl3_license("Matt")
use_package("RxODE", "LinkingTo")
use_package("RxODE", "Depends") ##  library(RxODE) on load; Can use imports instead.
use_roxygen_md()
##use_readme_md()
library(RxODE);
## Now Create a model
idr <- RxODE({
    C2 = centr/V2;
    C3 = peri/V3;
    d/dt(depot) =-KA*depot;
    d/dt(centr) = KA*depot - CL*C2 - Q*C2 + Q*C3;
    d/dt(peri)  =                    Q*C2 - Q*C3;
    d/dt(eff)  = Kin - Kout*(1-C2/(EC50+C2))*eff;
});

rxUse(idr); ## Add the idr model to your package
rxUse(); # Update the compiled RxODE sources for all of your packages

The rxUse() will: - Create RxODE sources and move them into the package’s src/ directory. If there is only R source in the package, it will also finish off the directory with an library-init.c which registers all the RxODE models in the package for use in R. - Create stub R documentation for each of the models your are including in your package. You will be able to see the R documentation when loading your package by the standard ? interface.

You will still need to: - Export at least one function. If you do not have a function that you wish to export, you can add a re-export of RxODE using roxygen as follows:

##' @importFrom RxODE RxODE
##' @export
RxODE::RxODE

If you want to use Suggests instead of Depends in your package, you way want to export all of RxODE’s normal routines

##' @importFrom RxODE RxODE
##' @export
RxODE::RxODE

##' @importFrom RxODE et
##' @export
RxODE::et

##' @importFrom RxODE etRep
##' @export
RxODE::etRep

##' @importFrom RxODE etSeq
##' @export
RxODE::etSeq

##' @importFrom RxODE as.et
##' @export
RxODE::as.et

##' @importFrom RxODE eventTable
##' @export
RxODE::eventTable

##' @importFrom RxODE add.dosing
##' @export
RxODE::add.dosing

##' @importFrom RxODE add.sampling
##' @export
RxODE::add.sampling

##' @importFrom RxODE rxSolve
##' @export
RxODE::rxSolve

##' @importFrom RxODE rxControl
##' @export
RxODE::rxControl

##' @importFrom RxODE rxClean
##' @export
RxODE::rxClean

##' @importFrom RxODE rxUse
##' @export
RxODE::rxUse

##' @importFrom RxODE rxShiny
##' @export
RxODE::rxShiny

##' @importFrom RxODE genShinyApp.template
##' @export
RxODE::genShinyApp.template

##' @importFrom RxODE cvPost
##' @export
RxODE::cvPost

# This is actually from `magrittr` but allows less imports
##' @importFrom RxODE %>%
##' @export
RxODE::`%>%`
  • You also need to instruct R to load the model library models included in the model’s dll. This is done by:
# In this case `rxModels` is the package name
##' @useDynLib rxModels, .registration=TRUE

If this is a R package with RxODE models and you do not intend to add any other compiled sources (recommended), you can add the following configure scripts

#!/bin/sh
# This should be used for both configure and configure.win
echo "unlink('src', recursive=TRUE);RxODE::rxUse()" > build.R
${R_HOME}/bin/Rscript build.R
rm build.R

Depending on the check you may need a dummy autoconf script,

## dummy autoconf script
## It is saved to configure.ac

If you want to integrate with other sources in your Rcpp or C/Fortan based packages, you need to include rxModels-compiled.h and: - Add the define macro compiledModelCall to the list of registered .Call functions. - Register C interface to allow model solving by R_init0_rxModels_RxODE_models() (again rxModels would be replaced by your package name).

Once this is complete, you can compile/document by the standard methods:

devtools::load_all()
devtools::document()
devtools::install()

If you load the package with a new version of RxODE, the models will be recompiled when they are used.

However, if you want the models recompiled for the most recent version of RxODE, you simply need to call rxUse() again in the project directory followed by the standard methods for install/create a package.

devtools::load_all()
devtools::document()
devtools::install()

Note you do not have to include the RxODE code required to generate the model to regenerate the RxODE c-code in the src directory. As with all RxODE objects, a summary will show one way to recreate the same model.

An example of compiled models package can be found in the rxModels repository.