RsNLME Installation Guide

System Requirements

  • Windows 8, 10
  • Windows Server 2018, 2019, 2021
  • Linux CentOS8/RHEL8
  • Linux Ubuntu 22.04

Installation Prerequisites

Before installing the packages in R, you must have successfully installed the following on your system.

For Windows please download R from CRAN, run the executable and follow the instructions. For Linux please use the instructions provided here.

Installation of NLME Engine

Certara’s NLME Engine is required to execute models built with RsNLME. Click here to request a 30-day trial of the NLME Engine.

Note: Installation files and license will be emailed by Certara support after contact form has been submitted.

Windows

Installation and configuration of the NLME Engine is done in a few simple steps via the NLME Engine Installer.

1.) Open NLME-Engine-23.10.2.exe - Run as administrator.

2.) Select appropriate installation (e.g., typical).

The installer will install Certara’s NLME Engine, MS MPI (used for parallel execution), and GCC (compiler) inside C:/Program Files/Certara, and configure the appropriate environment variables required to execute Certara.RsNLME models from R.

Note: Existing Phoenix users already have MS MPI and GCC on their system and only need to install the NLME_Engine.

Linux

Note:

GCC version 8.5.0 should be presented on CentOS8/RHEL8 for the NMLE Engine run.

GCC version 11 should be presented on Ubuntu 22.04 for the NLME Engine run.

1.) Unzip NLME_Engine_23.10.2_linux.zip and note the location of the resulting InstallDirNLME folder on your system.

2.) Make sure that all bash scripts in InstallDirNLME folder as well as TDL5 and initpml have flag ‘X’ (executable).

3.) Install OpenMPI to execute models using parallelization (optional):

Note: Below code should be executed in Linux terminal, not R

CentOS8/RHEL8

# List available Open MPI packages
yum list *openmpi*
# Install the default version of Open MPI development package
sudo yum install openmpi-devel.x86_64

Ubuntu 22.04

# List available Open MPI packages
apt list *openmpi*
# Install the default version of Open MPI development package
sudo apt install libopenmpi-dev

4.) Initialize licensing system using the executable initpml, which is located inside InstallDirNLME:

  # Paste the code into Linux console, not R
  cd InstallDirNLME
  sudo ./initpml

5.) Setup environment variables.

Licensing

1.) After receiving your license key from Certara via email, open up your text editor (e.g., Notepad) and paste the license key to the first line of the empty .txt file.

2.) Save this file inside installed C:/Program Files/Certara/NLME_Engine with the name lservrc. Linux users should add license file inside the InstallDirNLME folder.

3.) It is possible to have different storage for the license file, but in such case R session should have access to PhoenixLicenseFile environment variable, see here for details.

4.) If Phoenix NLME is installed and licensed, full RsNLME functionality is available for the user on the current host, no additional license files required.

5.) If the floating license is used, then License server should be installed within NLME Engine (Full installation). The manual explaining the server start and access to that server could be found here. NLME Engine recognizes the license server if the network address is found in PhoenixLicenseServer env.variable.

Installation of R Packages

Please note that R >= 4.0.0 is required (see above).

Define Certara_Packages object in R as a character vector of the required package names:

Certara_Packages <- c("Certara.RsNLME",
                      "Certara.NLME8",
                      "Certara.RsNLME.ModelBuilder",
                      "Certara.RsNLME.ModelExecutor", 
                      "Certara.Xpose.NLME",
                      "Certara.ModelResults",
                      "Certara.VPCResults")

Windows 

install.packages(Certara_Packages, 
  repos = c("https://certara.jfrog.io/artifactory/certara-cran-release-public/", 
  "https://cloud.r-project.org"), method = "libcurl")

Linux

Certara.RsNLME is officially supported on CentOS8/RHEL8/Ubuntu22.04. The package requires the xml2 and ssh dependencies. If the xml2 package is not already installed on your Linux distribution, users may first have to execute the following command from the terminal in order to install the additional Linux system library libxml2-devel.

CentOS8/RHEL8

sudo yum install libxml2-devel

Ubuntu 22.04

sudo apt install libxml2-dev

If the ssh package is not already installed on your Linux distribution, users may first have to execute the following command from the terminal in order to install the additional Linux system library libssh-devel.

CentOS8/RHEL8

sudo yum install epel-release
sudo yum install libssh-devel

Ubuntu 22.04

sudo apt install libssh-dev

Then proceed to install Certara_Packages from R.

install.packages(Certara_Packages, 
  repos = c("https://certara.jfrog.io/artifactory/certara-cran-release-public/", 
            "https://cloud.r-project.org"))

Important for Linux runs: please don’t forget to initialize the license system, see Installation of NLME Engine.

Run Test Example

To verify the successful installation of R packages and NLME-Engine, you may execute the following test code to build and execute an RsNLME model.

1.) Build Model

library(Certara.RsNLME)

model <- pkmodel(parameterization = "Clearance",
                  absorption = "Intravenous",
                  numCompartments = 2,
                  data = pkData,
                  ID = "Subject",
                  Time = "Act_Time",
                  A1 = "Amount",
                  CObs = "Conc")

print(model)
## 
##  Model Overview 
##  ------------------------------------------- 
## Model Name        :  Model_24_05_20_12_36
## Working Directory :  C:/Users/jcraig/Documents/GitHub/R-RsNLME/vignettes/Model_24_05_20_12_36
## Is population     :  TRUE
## Model Type        :  PK
## 
##  PK 
##  ------------------------------------------- 
## Parameterization  :  Clearance
## Absorption        :  Intravenous
## Num Compartments  :  2
## Dose Tlag?        :  FALSE
## Elimination Comp ?:  FALSE
## Infusion Allowed ?:  FALSE
## Sequential        :  FALSE
## Freeze PK         :  FALSE
## 
##  PML 
##  ------------------------------------------- 
## test(){
##     cfMicro(A1,Cl/V, Cl2/V, Cl2/V2)
##     dosepoint(A1)
##     C = A1 / V
##     error(CEps=0.1)
##     observe(CObs=C * ( 1 + CEps))
##     stparm(V = tvV * exp(nV))
##     stparm(Cl = tvCl * exp(nCl))
##     stparm(V2 = tvV2 * exp(nV2))
##     stparm(Cl2 = tvCl2 * exp(nCl2))
##     fixef( tvV = c(,1,))
##     fixef( tvCl = c(,1,))
##     fixef( tvV2 = c(,1,))
##     fixef( tvCl2 = c(,1,))
##     ranef(diag(nV,nCl,nV2,nCl2) =  c(1,1,1,1))
## }
## 
##  Structural Parameters 
##  ------------------------------------------- 
##  V Cl V2 Cl2
##  ------------------------------------------- 
## Observations:
## Observation Name :  CObs
## Effect Name      :  C
## Epsilon Name     :  CEps
## Epsilon Type     :  Multiplicative
## Epsilon frozen   :  FALSE
## is BQL           :  FALSE
##  ------------------------------------------- 
##  Column Mappings 
##  ------------------------------------------- 
## Model Variable Name : Data Column name
## id                  : Subject
## time                : Act_Time
## A1                  : Amount
## CObs                : Conc

2.) Fit Model

fitmodelResults <- fitmodel(model)
print(fitmodelResults$Overall)
##    Scenario RetCode    LogLik     -2LL      AIC      BIC nParm nObs nSub
## 1: WorkFlow       1 -632.7953 1265.591 1283.591 1308.057     9  112   16
##    EpsShrinkage Condition
## 1:      0.17312   4.86919