Skip to contents

RsNLME Installation Guide

installation.Rmd

RsNLME package logo

System Requirements

  • Windows 10
  • Windows 11
  • Windows Server 2016, 2019, 2022
  • Linux CentOS8/RHEL8
  • Linux Ubuntu 22.04

Note: Only 64bit operating systems supported.

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 Certara.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

The NLME Engine can be easily installed and configured using the NLME Engine Installer. Just follow these simple steps:

  1. Run the Installer as Administrator: Right-click on NLME-Engine-24.09.1.exe and select “Run as administrator”.

  2. Choose Installation Type: Select the desired installation type (e.g., “Typical”).

Components Installed

The installer will install and configure the following components in the C:/Program Files/Certara directory:

  • NLME Engine 24.09.1

  • GCC 8.4 (for model compilation)

  • MS MPI v.10.0 (for parallel execution)

Automatic Environment Variable Configuration

The installer will automatically configure the necessary environment variables for running Certara.RsNLME models within your R environment.

Note for Existing Phoenix Users: If you already have Phoenix installed, you likely have MS MPI and GCC on your system. In this case, you only need to install the NLME Engine component.

Verifying Environment Variables

You can verify that the following environment variables have been set correctly:

  • INSTALLDIR: This should point to the directory where the NLME Engine is installed.

  • NLMEGCCDir64: This should point to the directory containing GCC 8.4.

  • PhoenixMSMPIDir: This is required only if you chose to install MS MPI. It should point to the MS MPI installation directory.

Linux

GCC version 8.5 should be presented on CentOS8/RHEL8 GCC version 11 should be presented on Ubuntu 22.04 for the NLME Engine run.

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

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

OpenMPI installation on RHEL8/CentOS8

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

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

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

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

3.) Setup environment variables:

The Certara.RsNLME package requires the following environment variables to be configured:

  • INSTALLDIR:
    • Purpose: Specifies the location of the NLME Engine.
    • Value: Set this to the directory where you extracted the NLME Engine archive (e.g., the InstallDirNLME folder).
  • PhoenixMPIDir64 (Optional):
    • Purpose: Specifies the location of OpenMPI, if installed and intended for parallel processing.
    • Value: Set this to the root directory of your OpenMPI installation, ensuring it contains the bin and lib subfolders (e.g., ${PhoenixMPIDir64}/bin/ and ${PhoenixMPIDir64}/lib/).
  • PML_BIN_DIR (Ubuntu 22.04 Only):
    • Purpose: Enables access to libraries compiled specifically for Ubuntu 22.04.
    • Value: Set this to UBUNTU2204.

Setting Environment Variables

You can define these environment variables in either your ~/.Renviron file or your ~/.bash_profile file.

Example (~/.bash_profile): 
  # .bash_profile
  
  # ... (other existing content) ...
  
  # Add and modify the following lines:
  export INSTALLDIR=/home/user/InstallDirNLME 
  export PhoenixMPIDir64=/lib64/openmpi/ 
  # Required for Ubuntu 22.04 only:
  export PML_BIN_DIR=UBUNTU2204
Note: Replace the example paths with the actual paths on your system. Remember to source your ~/.bash_profile file or restart your terminal for the changes to take effect.

Additional Libraries Needed on Linux

Certara.RsNLME depends on the xml2 and ssh R packages.

Installing xml2:

If xml2 R package isn’t already installed, you might need to install the libxml2-devel system library first. Open a terminal and run the appropriate command for your distribution:

  • RHEL 8/CentOS 8: sudo yum install libxml2-devel
  • Ubuntu 22.04: sudo apt-get install libxml2-dev

Installing ssh:

Similarly, if the ssh package isn’t installed, you might need to install the libssh-devel system library:

  • RHEL 8/CentOS 8: sudo yum install libssh-devel
  • Ubuntu 22.04: sudo apt-get install libssh-dev

The xml2 and ssh R packages, which are required by Certara.RsNLME, will be automatically installed as part of the Certara.RsNLME installation process in the following step.

Installation of R Packages

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

It is always recommended to install R packages in a new R session, with no other packages loaded. Additionally, ensure no other R/RStudio sessions are running in the background.

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

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

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

Authentication and Licensing

NLME Engine seamlessly integrates with Certara Admin’s OAuth-based licensing system, providing an online solution for accessing NLME features within Phoenix and Certara.RsNLME. Users must authenticate with Certara Admin to unlock the full capabilities of NLME Engine and related R packages.

Prerequisites

Users should have a pre-configured account within Certara Admin before attempting to access NLME Engine. If a user does not have an existing account, they will be redirected to Certara Admin’s registration page to create one.

Ensure the NLME Engine is installed on your system. The default installation directory (extracted from INSTALLDIR environment variable) is used if not specified.

User and License Management

Upon successful login, NLME Engine automatically retrieves and securely stores a license file valid for 30 days of offline usage. This license is automatically refreshed every 24 hours during any NLME Engine execution, ensuring it remains aligned with the latest configurations set by administrators through Certara Admin. Organizational administrators can manage user access and license assignments through Certara Admin’s user management tools. Licenses are granted to individual users by assigning them seats in NLME module inside Phoenix product.

Offline Access

The 30-day license allows users to continue working with NLME Engine even without an active internet connection. However, if 30 days pass without connecting to Certara Admin, users will be prompted to re-authenticate to regain access to the assigned products/modules.

NLME Engine Licensing through Certara Admin

1.) Install/unpack NLME Engine: Download and install/unpack the NLME Engine from the Certara website.

2.) Set INSTALLDIR environment variable: This variable should point to the directory where you unpacked the NLME Engine.

Note: The NLME installer automatically creates this environment variable

3.) Browser configuration (Linux): If you want to use a browser other than /usr/bin/firefox for authentication, you need to modify the appsettings.json file to point to the correct browser path. Make sure the browser supports TLS1.2 for a secure connection to the CAD server.

4.) By default, the configuration file is located within the directory specified by the INSTALLDIR environment variable. If you need to change the location of the configuration file, you can use the CAD_AUTH_PATH environment variable to specify the correct path.

5.) Call the obtain_NLMELicense function:

  obtain_NLMELicense(InstallDir = Sys.getenv("INSTALLDIR"), verbose = TRUE)

Note: You need a stable internet connection to obtain and manage your NLME license

6.) The function will automatically launch the licensing tool, which will guide you through the authentication and license acquisition process in your browser window.

7.) After successful login and license acquisition, you will be redirected to a page that says “You have logged into RsNLME successfully!”.”

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_09_29_21_29
## Working Directory :  C:/Users/jcraig/Documents/GitHub/R-RsNLME/vignettes/Model_24_09_29_21_29
## 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