| Version: | 3.2.0 |
| Title: | Utilities for Certara's Nonlinear Mixed-Effects Modeling Engine |
| Description: | Interface to Certara's Nonlinear Mixed-Effects (NLME) modeling engine ('NLME-Engine') for pharmacokinetic and pharmacodynamic (PK/PD) modeling and simulation. Provides access to the Maximum Likelihood estimation algorithms available in the 'Phoenix' NLME platform for population, individual, and pooled analyses using parametric methods. Includes utilities for setting up NLME installations and parallel settings, running estimation, bootstrap, and covariate search workflows, and updating model files from engine output. Jobs can be executed locally or across high-performance computing resources, including Linux Sun Grid Engine (SGE) and Simple Linux Utility for Resource Management (SLURM) grids as well as multicore Linux and Windows hosts. |
| Depends: | R (≥ 4.0.0) |
| License: | LGPL-3 |
| Suggests: | testthat, brew, withr |
| Imports: | xml2, batchtools (≥ 0.9.9), utils, data.table |
| Encoding: | UTF-8 |
| Config/roxygen2/version: | 8.1.0 |
| NeedsCompilation: | no |
| Packaged: | 2026-09-11 17:12:54 UTC; jcraig |
| Author: | Soltanshahi Fred [aut], Michael Tomashevskiy [aut], James Craig [aut, cre], Shuhua Hu [ctb], Certara USA, Inc. [cph, fnd] |
| Maintainer: | James Craig <james.craig@certara.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-09-11 20:20:02 UTC |
Plan an MPI batch
Description
Returns the per-scenario MPI rank, scenario concurrency, and executable family for the current batch. Centralises decisions previously scattered across 'performParallelNLMERun()', 'startGenericGridJob()', 'multiCoreGeneric()', and 'performBootstrap()'.
Usage
.planMpiBatch(
method,
numProc,
batchSize,
controlFile = NULL,
localDir = NULL,
engineFamily = NULL,
smallestPopulation = NULL,
emitLog = TRUE
)
Arguments
method |
Parallel method (e.g. '"Multicore_MPI"', '"SGE_MPI"', '"Multicore"', '"LOCAL_MPI"', '"None"'). |
numProc |
Raw 'NumProc' string: scalar '"10"' or pair '"10,2"'. |
batchSize |
Number of scenarios to be launched concurrently. |
controlFile |
Path or basename of the NLME control file (used to derive the engine family and smallest population). May be 'NULL'. |
localDir |
Local working directory for resolving 'controlFile' when it is a basename. May be 'NULL'. |
engineFamily |
Optional engine-family override (for example '"FOCE-ELS"', '"Laplacian"', '"QRPEM"', '"FO"', '"IT2S-EM"', '"Naive-Pooled"', or '"Unknown"'). Useful for callers that already know the family from the model. |
smallestPopulation |
Optional smallest-population override; if omitted and 'controlFile'/'localDir' are usable, the planner derives it via 'getMinimumNumSubjects()'. |
emitLog |
Emit a structured '[MPI plan]' log line via 'message()'. Defaults to 'TRUE'. Tests can pass 'FALSE'. |
Update Model text file from NLME output File
Description
This function updates a model file with parameter estimates obtained from a dmp file (R structure format of output generated by NLME) text file. The updated model file includes the estimated fixed effects, error terms and random effects values.
Usage
UpdateMDLfrom_dmptxt(
dmpfile = "dmp.txt",
SharedWorkingDir = getwd(),
model_file = "test.mdl",
compile = TRUE,
output_file = "test.mdx"
)
Arguments
dmpfile |
The path to the DMP text file. |
SharedWorkingDir |
The working directory. Used if |
model_file |
The name of the model file to be updated (with optional full path). |
compile |
A logical value indicating whether to compile the updated
model file into NLME executable. Default is |
output_file |
The name of the new model file with updated estimates. |
Details
TDL5 executable from NLME Engine is used. NLME engine
location is identified by INSTALLDIR environment variable. The current
function will give an error if TDL5 cannot be executed.
Value
The path to the updated model file.
Checks the local host for GCC version in the path
Description
Performs operating system dependent check for availability of GCC.
Usage
checkGCC(OS.type = .Platform$OS.type)
Arguments
OS.type |
Character specifying operating system type. Defaults to |
Value
TRUE if GCC check is successful, otherwise FALSE.
Examples
checkGCC()
Verify NLME Installation Directory
Description
Checks if a specified directory contains all the required files for the NLME engine to operate. It performs platform-specific checks for Unix-like systems and Windows.
Usage
checkInstallDir(installDir)
Arguments
installDir |
A character string specifying the path to the NLME installation directory to be checked. |
Details
The function validates the presence of essential executables, libraries, and scripts.
On Unix systems, if the 'PML_BIN_DIR' environment variable is set (e.g., to "UBUNTU" or "RHEL"), the function searches for files within that subdirectory of 'installDir'. If the variable is not set, it searches directly in 'installDir'.
On Windows, it checks for '.exe', '.dll', and '.ps1' files directly within the specified 'installDir'.
Value
Returns 'TRUE' if all required files are found and permissions are successfully set (on Unix). Returns 'FALSE' if the validation fails.
Side Effects
- On Unix systems, upon successful validation, it sets execute permissions ('0777') on the "TDL5" executable and the "execNLMECmd.sh" script using 'Sys.chmod()'.
Examples
## Not run:
checkInstallDir(Sys.getenv("INSTALLDIR"))
## End(Not run)
Checks if NLME run is licensed
Description
Checks if valid license is available for NLME run.
Usage
checkLicenseFile(installDir, verbose = FALSE, outputGenericInfo = TRUE)
Arguments
installDir |
Directory with NLME executables as specified in 'INSTALLDIR' environment variable. |
verbose |
Flag to output all messages during authorization and licensing. Default is 'FALSE'. |
outputGenericInfo |
Flag to provide TDL5 output when no issues found. Default is 'TRUE'. |
Value
'TRUE' if all checks are successful, otherwise 'FALSE'.
Examples
## Not run:
checkLicenseFile(Sys.getenv("INSTALLDIR"),
verbose = TRUE)
## End(Not run)
Check MPI settings for the given local host
Description
Checks if MPI settings are provided and feasible. Check is done for the hosts where MPI parallel method is used.
Usage
checkMPISettings(obj)
Arguments
obj |
NLME Parallel Host to be checked |
Value
TRUE if MPI executables are ready for running,
otherwise FALSE. If host does not have MPI in parallel method,
it also returns TRUE.
Examples
## Not run:
checkMPISettings(host)
## End(Not run)
Check NLME ROOT DIRECTORY for the given local host
Description
Checks if NLME ROOT DIRECTORY is provided and ready for writing. That directory is used for temporary folders writing.
Usage
checkRootDir(obj)
Arguments
obj |
NLME Parallel Host to be checked |
Value
TRUE if NLME ROOT DIRECTORY exists and accessible for writing,
otherwise FALSE.
Examples
## Not run:
checkRootDir(host)
## End(Not run)
Run TDL5's model-info step against a model file
Description
Runs TDL5 -i on modelFile and returns the path to the
resulting ModelInfo.txt file, which lists the model's fixed
effects, random effects, and residual-error terms.
Usage
generateTDL5ModelInfo(
modelFile,
outputDir,
installDir = Sys.getenv("INSTALLDIR")
)
Arguments
modelFile |
Path to the |
outputDir |
Directory TDL5 should write |
installDir |
Path to the NLME installation. Defaults to the
|
Value
Path to the generated ModelInfo.txt file.
Table names from the column definition file
Description
Extracts table names from the column definition file
Usage
getTableNames(columnDefinitionFilename, columnDefinitionText, simtbl = FALSE)
Arguments
columnDefinitionFilename |
path to NLME column definition file to be read |
columnDefinitionText |
Lines of column definition file to be used (only
if |
simtbl |
logical. |
Value
vector of names of the tables in column definition file if any, empty string otherwise
Examples
## Not run:
getTableNames(columnDefinitionFilename = "cols1.txt",
simtbl = TRUE)
## End(Not run)
NLME Bootstrap Function
Description
Runs an NLME bootstrap job in parallel and produces summaries
Usage
performBootstrap(args, allowIntermediateResults = TRUE, reportProgress = FALSE)
Arguments
args |
Arguments for bootstrap execution |
allowIntermediateResults |
Set to |
reportProgress |
Set to |
Value
Directory path where NLME job was executed
Sort specification for multiple estimations
Description
Runs multiple estimations sorting the input dataset by requested columns and creating multiple data sets
Usage
performEstimationOnSortColumns(args, reportProgress = FALSE)
Arguments
args |
a vector of arguments provided as the following: c(method, install_directory, shared_directory, localWorkingDir, nlmeArgsFile, numColumns, ColumnNames, NumProc, workflowName) |
reportProgress |
whether it is required to report the progress (for local jobs usually) |
Value
Directory path where NLME job was executed
Runs a set of NLME jobs in parallel
Description
Runs a set of NLME jobs in parallel
Usage
performParallelNLMERun(
args,
partialJob = FALSE,
allowIntermediateResults = TRUE,
progressStage = "",
func = "",
func_arg = NULL,
reportProgress = FALSE
)
Arguments
args |
a vector of arguments provided as the following: c(jobType, parallelMethod, install_dir, shared_directory, localWorkingDir, controlFile, NumProc, workflow_name, fixefUnits) |
partialJob |
is |
allowIntermediateResults |
is |
progressStage |
stage of analysis to be reported |
func |
function to be executed after NLME job |
func_arg |
arguments to be provided to the function by name provided above |
reportProgress |
whether it is required to report the progress (for local jobs usually) |
Value
Directory path where NLME job was executed
NLME a profile estimation run on list of fixed effects
Description
This function runs multiple estimations sorting the input dataset by requested columns and creating multiple data sets Runs are also generated for all profiling variables
Usage
performProfileEstimation(args, reportProgress = FALSE)
Arguments
args |
Arguments for profile estimation |
reportProgress |
Set to |
Value
Directory path where NLME job was executed
Shotgun covariate search
Description
Runs a set of possible covariate sets in parallel
Usage
performShotgunCovarSearch(args, reportProgress = FALSE)
Arguments
args |
a vector of arguments provided as the following: c(jobType, parallelMethod, install_dir, shared_directory, localWorkingDir, controlFile, NumProc, workflow_name, fixefUnits) |
reportProgress |
whether it is required to report the progress (for local jobs usually) |
Value
Directory path where NLME job was executed
NLME Stepwise Covariate Search
Description
Performs a stepwise covariate search algorithm on an NLME model. The search consists of a Forward Addition phase followed by a Backward Elimination phase.
Usage
performStepwiseCovarSearch(args, reportProgress = FALSE)
Arguments
args |
A character vector containing command-line style arguments:
|
reportProgress |
Logical; if |
Value
A data frame containing the results of all evaluated scenarios (Scenario, Criteria, Parameters, etc.).
Read a progress.txt file and return iteration data as a data frame.
Description
Read a progress.txt file and return iteration data as a data frame.
Usage
readProgressDotTxt(fileToRead)
Arguments
fileToRead |
Path to the progress.txt file. |
Value
A data frame with columns Iter, Parameter, Value,
or an empty data frame if the file is missing or unparseable.
Use to reconnect to a grid job
Description
Use to reconnect to a grid job
Usage
reconnectToBootstrapNLMERun(args)
Arguments
args |
Arguments for reconnecting to bootstrap grid run |
Value
Directory path where NLME job was executed
Run TDL5's model-render step against a model file with an override block
Description
Runs TDL5 -r on modelFile and returns the path to the
resulting rendered model file. modelFile is expected to already
contain the desired override { ... } block (built by the caller)
appended after the model's own statements; TDL5 applies it and writes the
merged result beside modelFile, replacing the final extension with
.mdx (e.g. model.mdl -> model.mdx).
Usage
renderTDL5Override(modelFile, outputDir, installDir = Sys.getenv("INSTALLDIR"))
Arguments
modelFile |
Path to the |
outputDir |
Directory passed to TDL5 as its output argument. Should be
|
installDir |
Path to the NLME installation. Defaults to the
|
Value
Path to the rendered model file.