Breaking Changes

• The model properties was moved from $params to $props so it does not conflict with the low level rxode2 model $params

• Error when specifying wd without modName

• With Linear and midpoint of a time between two points, how rxode2 handles missing values has changed. When the missing value is lower than the requested time, it will look backward until it finds the first non-missing value (or if all are missing start looking forward). When the missing value is higher than the requested time, the algorithm will look forward until it finds the first non-missing value (or if all are missing, start looking backward).

• The order of ODEs is now only determined by the order of cmt() and d/dt(). Compartment properties, tad() and other compartment related variables no no longer affect compartment sorting. The option rxode2.syntax.require.ode.first no longer does anything.

• The handling of zeros “safely” has changed (see #775)

  • when safeZero=TRUE and the denominator of a division expression is zero, use the Machine’s small number/eps (you can see this value with .Machine$double.eps)

  • when saveLog=TRUE and the x in the log(x) is less than or equal to zero, change this to log(eps)

  • when safePow=TRUE and the expression x^y has a zero for x and a negative number for y replace x with eps.

  Since the protection for divide by zero has changed, the results will also change. This is a more conservative protection mechanism than was applied previously.

• Random numbers from rxode2 are different when using dop853, lsoda or indLin methods. These now seed the random numbers in the same way as liblsoda, so the random number provided will be the same with different solving methods.

• The arguments saved in the rxSolve for items like thetaMat will be the reduced matrices used in solving, not the full matrices (this will likely not break very many items)

Possible breaking changes (though unlikely)

• iCov is no longer merged to the event dataset. This makes solving with iCov slightly faster (#743)

New features

• You can remove covariances for every omega by piping with %>% ini(diag()) you can be a bit more granular by removing all covariances that have either eta.ka or eta.cl by: %>% ini(diag(eta.ka, eta.cl)) or anything with correlations with eta.cl with %>% ini(diag(eta.cl))

• You can also remove individual covariances by %>% ini(-cov(a, b)) or %>% ini(-cor(a,b)).

• You can specify the type of interpolation applied for added dosing records (or other added records) for columns that are kept with the keep= option in rxSolve(). This new option is keepInterpolation and can be locf for last observation carried forward, nocb which is the next observation carried backward, as well as NA which puts a NA in all imputed data rows. See #756.

  • Note: when interpolation is linear/midpoint for factors/characters it changes to locf with a warning (#759)

  • Also note, that the default keep interpolation is na

• Now you can specify the interpolation method per covariate in the model:

  • linear(var1, var2) says both var1 and var2 would use linear interpolation when they are a time-varying covariate. You could also use linear(var1)

  • locf() declares variables using last observation carried forward

  • nocb() declares variables using next observation carried backward

  • midpoint() declares variables using midpoint interpolation

• linear(), locf(), locb(), midpoint(), params(), cmt() and dvid() declarations are now ignored when loading a rxode2 model with rxS()

• Strings can be assigned to variables in rxode2.

• Strings can now be enclosed with a single quote as well as a double quote. This limitation was only in the rxode2 using string since the R-parser changes single quotes to double quotes. (This has no impact with rxode2({}) and ui/function form).

• More robust string encoding for symengine (adapted from utils::URLencode() and utils::URLdecode())

• Empty arguments to rxRename() give a warning (#688)

• Promoting from covariates to parameters with model piping (via ini()) now allows setting bounds (#692)

• Added assertCompartmentName(), assertCompartmentExists(), assertCompartmentNew(), testCompartmentExists(), assertVariableExists() testVariableExists(), assertVariableNew(), assertVariableName(), and assertParameterValue() to verify that a value is a valid nlmixr2 compartment name, nlmixr2 compartment/variable exists in the model, variable name, or parameter value (#726; #733)

• Added assertRxUnbounded(), testRxUnbounded(), warnRxBounded() to allow nlmixr2 warn about methods that ignore boundaries #760

• Added functions tad0(), tafd0(), tlast0() and tfirst0() that will give 0 instead of NA when the dose has not been administered yet. This is useful for use in ODEs since NAs will break the solving (so can be used a bit more robustly with models like Weibull absorption).

• rxode2 is has no more binary link to lotri, which means that changes in the lotri package will not require rxode2 to be recompiled (in most cases) and will not crash the system.

• rxode2 also has no more binary linkage to PreciseSums

• The binary linkage for dparser is reduced to C structures only, making changes in dparser less likely to cause segmentation faults in rxode2 if it wasn’t recompiled.

• A new model property has been added to $props$cmtProp and $statePropDf. Both are data-frames showing which compartment has properties (currently ini, f, alag, rate and dur) in the rxode2 ui model. This comes from the lower level model variable $stateProp which has this information encoded in integers for each state.

• A new generic method rxUiDeparse can be used to deparse meta information into more readable expressions; This currently by default supports lower triangular matrices by lotri, but can be extended to support other types of objects like ’nlmixr2’s foceiControl() for instance.

Bug fixes

• Fix ui$props$endpoint when the ui endpoint is defined in terms of the ode instead of lhs. See #754

• Fix ui$props when the ui is a linear compartment model without ka defined.

• Model extraction modelExtract() will now extract model properties. Note that the model property of alag(cmt) and lag(cmt) will give the same value. See #745

• When assigning reserved variables, the parser will error. See #744

• Linear interpolation will now adjust the times as well as the values when NA values are observed.

• Fix when keeping data has NA values that it will not crash R; Also fixed some incorrect NA interpolations. See #756

• When using cmt() sometimes the next statement would be corrupted in the normalized syntax (like for instance locf); This bug was fixed (#763)

• keep will now error when trying to keep items that are in the rxode2 output data-frame and will be calculated (#764)

Big change

• At the request of CRAN, combine rxode2parse, rxode2random, and rxode2et into this package; The changes in each of the packages are now placed here:

Fix for merged packages

• Fix a bug when simulating nested variables for random simulation (was in rxode2random #25)

• As requested by CRAN remove the C code SET_TYPEOF which is no longer part of the C R API for rxode2parse

What is an ABI?

An ABI stands for application binary interface and is determined by the compiler and the platform at the time of compile. Each function has an address in memory. This is why when some down-stream dependency like rxode2parse are updated the functions that are specified change memory addresses. When rxode2 tries to call a function from the parser, R memory’s is corrupted and R crashes. Of course you can fix this by recompiling the rxode2 version but usually waiting for the binary that links was a better solution.

Addresses of other items other than C functions can also change (like C/C++ structures), so direct access of these items is also something that can cause memory corruption.

This ABI interface is what happens when you register a C callable in any package.

The solution – creating an API

An API is the Application Programming Interface. It has been popularized by web APIs and can be created for your R package with packages like plumber, however it can be any application programming interface.

double *getIndLhs(rx_solving_options_ind* ind) {
  return ind->lhs;
}

SEXP _rxode2_rxode2Ptr(void) {
  int pro = 0;  // Counter for the number of PROTECT calls
  // Create an external pointer for _lotriLstToMat
  SEXP rxode2rxRmvnSEXP = PROTECT(R_MakeExternalPtrFn((DL_FUNC)&_rxode2_rxRmvnSEXP, R_NilValue, R_NilValue)); pro++;
  // more code here
  // Unprotect all protected objects
  UNPROTECT(pro);

  // Return the list of external pointers
  return ret;
}

void R_init_rxode2(DllInfo *info){
  R_CallMethodDef callMethods[]  = {
    {"_rxode2_rxode2Ptr", (DL_FUNC) &_rxode2_rxode2Ptr, 0},
    // more registered functions
    {NULL, NULL, 0}
  };
  static const R_CMethodDef cMethods[] = {
    {NULL, NULL, 0, NULL}
  };

  R_registerRoutines(info, cMethods, callMethods, NULL, NULL);
  R_useDynamicSymbols(info, FALSE);
}

useDynLib(rxode2, .registration=TRUE)

#' @useDynLib rxode2, .registration=TRUE

#' Get the rxode2 function pointers
#'
#' This function is used to get the function pointers for rxode2.  This is
#' used to allow rxode2 to have binary linkage to nlmixr2est.
#'
#' @return a list of function pointers
#' @export
#' @author Matthew L. Fidler
#' @examples
#' .rxode2ptrs()
.rxode2ptrs <- function() {
  .Call(`_rxode2_rxode2Ptr`, PACKAGE = "rxode2")
}

rxode2::.rxode2ptrs()[1:3]

## $rxode2rxRmvnSEXP
## <pointer: 0x735bc70c68f0>
## 
## $rxode2rxParProgress
## <pointer: 0x735bc72c49c0>
## 
## $rxode2getRxSolve_
## <pointer: 0x735bc72c5ba0>

typedef double *(*getIndLhs_t)(rx_solving_options_ind* ind);
extern getIndLhs_t getIndLhs;

static inline SEXP iniRxodePtrs0(SEXP p) {
  if (_rxode2_rxRmvnSEXP_ == NULL) { // only assign if not already assigned
    // more code
    getIndLhs = (getIndLhs_t) R_ExternalPtrAddrFn(VECTOR_ELT(p, 23));
    // more code
  }
  return R_NilValue;
}

#define iniRxode2ptr                                    \
  _rxode2_rxRmvnSEXP_t _rxode2_rxRmvnSEXP_ = NULL;      \
  // more code
getIndLhs_t getIndLhs = NULL;                         \
SEXP iniRxodePtrs(SEXP ptr) {                         \
  return iniRxodePtrs0(ptr);                          \
}                                                     \

#include <rxode2ptr.h>

#include <rxode2ptr.h>
// if in C++ wrap with extern "C" {}

// if you want to change the name of the function you can use #define
// iniRxodePtrs _your_fn_name

iniRxode2ptr // do not include a ; since it will be flagged as a significant warning by CRAN

SEXP iniRxodePtrs(SEXP ptr);
/// some code

void R_init_nlmixr2est(DllInfo *info){
  R_CallMethodDef callMethods[]  = {
    {"iniRxodePtrs", (DL_FUNC) &iniRxodePtrs, 1},
    // more registered functions
    {NULL, NULL, 0}
  };
  static const R_CMethodDef cMethods[] = {
    {NULL, NULL, 0, NULL}
  };

  R_registerRoutines(info, cMethods, callMethods, NULL, NULL);
  R_useDynamicSymbols(info, FALSE);
}

# This will be saved when compiled
# This way you will know if something has changed in the API
rxode2.api <- names(rxode2::.rxode2ptrs())

.iniRxode2Ptr <- function() {
  .ptr <- rxode2::.rxode2ptrs()
  .nptr <- names(.ptr)
  # Cheks for API changes
  if (length(rxode2.api) > length(.nptr)) {
    stop("nlmixr2est requires a newer version of rxode2 api, cannot run nlmixr2est\ntry `install.packages(\"rxode2\")` to get a newer version of rxode2", call.=FALSE)
  } else {
    .nptr <- .nptr[seq_along(rxode2.api)]
    if (!identical(rxode2.api, .nptr)) {
      .bad <- TRUE
      stop("nlmixr2est needs a different version of rxode2 api, cannot run nlmixr2est\ntry `install.packages(\"rxode2\")` to get a newer version of rxode2, or update both packages", call.=FALSE)
    }
  }
  .Call(`iniRxodePtrs`, .ptr,
        PACKAGE = "nlmixr2est")
}

.onLoad <- function(libname, pkgname) {
  # other code
  .iniRxode2Ptr()
}