nonmem2rx and babelmixr2

By Matt Fidler and the nlmixr2 Development Team in nlmixr2 babelmixr2 nonmem2rx nonmem

June 2, 2023

nonmem2rx/babelmixr2

I am really excited to announce that the nlmixr2 team has released a new version of babelmixr2 and a new package nonmem2rx that allows you to convert NONMEM to rxode2 or even a nlmixr2 object. To install, simply upgrade babelmixr2 with:

install.packages(c("nonmem2rx", "babelmixr2"))

What you can do with `nonmem2rx`/`babelmixr2`

You can do many useful tasks directly converting between nlmixr2 and NONMEM models; you can:

Convert a NONMEM model to a rxode2 model
Do development in nlmixr2 and then run NONMEM from a nlmixr2 model for reviewers who want to know about NONMEM results.
In both conversions, automatically make sure the model is translated correctly (for babelmixr2)

Then with nlmixr2 fit models coming from both conversions, you can:

Perform simulations of new dosing from the NONMEM model or even simulate using the uncertainty in your model to simulate new scenarios
Modify the model to calculate derived parameters (like AUC). These parameters slow down NONMEM’s optimization, but can help in your simulation scenario.

With nonmem2rx and babelmixr2, convert the imported rxode2 model to a nlmixr2 object, allowing:

Generation of Word and PowerPoint plots with nlmixr2rpt
Easy VPC creation (with vpcPlot())
Easy Individual plots with extra solved points. This will show the curvature of individual and population fits for sparse data-sets (with augPred())

You can even use this conversion to help debug your NONMEM model (or even try it in nlmixr2 instead)

Understand how to simplify the NONMEM model to avoid rounding errors
Run nlmixr2’s covariance step when NONMEMs covariance step has failed (in the linked example, there was no covariance step because rounding errors)

I am most excited about the ability to help debug NONMEM models since I spent so much time of my life trying to figure out rounding errors and covariance steps.

Another validation metric – why?

With nonmem2rx we introduce a new validation metric: IWRES.

Both babelmixr2 and mrgsolve have used IPRED and PRED (see nlmixr2 blog and mrgsolve blog #1, mrgsolve blog #2). They validate the model for each eta and the population.

What the previous approaches miss is the way the unexplained variability is coded. In general, nlmixr2 estimates residual standard deviation instead of variability. The IWRES allows the model translations to be back-checked to make sure that the residual variability is coded correctly.

It is quite handy to finish the rxode2 conversion from NONMEM and make sure it matches nlmixr2-type model.

With this extra check, you may wonder will there be any other checks of model coding or translation? The current checks check the overall model, the individual model, and the residual model.

The only other item that isn’t validated by the checks is the between subject variability covariance matrix. Note that the structure of the between subject variability etas is tested with the IPREDs. This means as long as the covariance matrix is imported correctly, all simulations should be reasonable.

There a three different things that can be used to validate the imported covariance matrix:

Manual check of between subject variability covariance matrix
Indirect check of between subject variability covariance matrix with a VPC
Direct check of between subject variability covariance matrix with conditional weighted residuals

Manual check of imported between subject variability matrix

The most straightforward way to validate this matrix is to do a manual check of the covariance matrix import. With simple covariance matrices this shouldn’t take too much time and is simply checking that the listed covariance matches the NONMEM output. In all likelihood this is going to match if you a importing the matrix with nonmem2rx, so this check isn’t included at this time.

Indirect check of imported between subject variability matrix

Another way to validate a reasonable between subject variability covariance matrix is simply to perform a VPC. If the PRED, IPRED and IWRES all validate, a good VPC will also show that the imported between subject variability matrix is correct (otherwise the simulated values would not match).

nlmixr2 `CWRES` vs NONMEM `CWRES` validation of between subject covariance matrix

The last way is to directly compare nlmixr2 and NONMEM’s CWRES values (noting that nlmixr2 will have simulated CWRES values when censored; NONMEM does not output values for censored values). If they match for non-censored observations, then the between subject variability also match.

This check works because CWRES uses the between subject variability matrix in its calculation. Therefore if these values match, everything will match.

One last question about validation metrics

So, if CWRES validates all components, why not use it exclusively? Well, by using the incremental approach you can see where the model may start to fall apart in the validation:

When PRED validation fails tells the structural model or population parameters are not describing the same model
When IPRED validation fails means that there are some individuals that behave differently between rxode2 and NONMEM; Perhaps NONMEM or rxode2 is using different protection algorithms for divide by zero etc.
When IWRES validation fails, the residual specification is likely different between the two models.
When CWRES validation fails (currently a manual step), the imported between subject variability matrix is likely incorrect.

Future work for automatic validation:

In the future, when a model is completely translated to a nlmixr2 fit, IWRES and CWRES validation will be performed in addition to the PRED/IPRED validation that is currently performed.

Visit our poster at PAGE

We will have a poster about this at PAGE. Stop by and say hi and get some hex stickers for these new projects. Also let us know what you think about nlmixr2 right now.

If you are astute, you may see a communication suggestion from Stacey Tannenbaum on the poster; We are open to new ideas about how to effectively communicate our open-source tools (if you have any ideas also let us know).

As always, we are grateful for all the community support and hope this is useful for your analysis as well.

Next steps

In addition to expanding our validation in babelmixr2, we want to extend babelmixr2 even more!

For babelmixr2 the next steps include creating other estimation methods (like nlmer from lme4 and saemix) and importing models from other tools (like Monolix).

I think these extra features could be useful for many people; Let us know what you think! If there is something missing or something doesn’t work quite right, let us know with a github issue or discussion!