Package {Certara.RsNLME}

Create a self-contained per-run SCM folder from NLME8 archive output.

Description

For local runs, renames the SCM_<runId>/ directory into the final timestamped folder. For remote runs, materialises the run folder from the SCM_<runId>.tar.gz bundle and removes both the bundle and any loose SCM_<runId>/ directory that the remote retrieve downloaded alongside it. If the bundle is missing but the loose directory is present (abnormal: NLME8 bundling step failed), warns and falls back to the local rename path so the user still gets a usable run folder. Saves the base model and run-context (resolved engine params, package version, runMode, wall-clock runTime) into a single rsnlme_run.rds for self-contained archive recovery.

Usage

.archiveScmRunFolder(
  cwd,
  runId,
  searchType,
  isRemote,
  model,
  params = NULL,
  runMode = NULL,
  runTime = NULL,
  selectionCriterion = NULL
)

Arguments

Value

Path to the created run folder, or NULL on failure.

Derive the user-facing fastOptimization mode from internal AD slots.

Description

Derive the user-facing fastOptimization mode from internal AD slots.

Usage

.fastOptimization_mode(x)

Arguments

Value

FALSE or a character string ("InnerAD", "HessianAD", "OuterAD").

Back-compat alias for is_cov_numeric_value()

Description

Several internal call sites still use the dotted name. Kept as a thin alias.

Usage

.is_numeric(x)

Arguments

Value

Logical vector.

Load fitmodel-compatible results from an archived SCM scenario folder.

Description

Reads the archived raw files and assembles a list structure compatible with the output of fitmodel() / xposeNlmeModel().

Usage

.loadScmFitResults(scenarioDir)

Arguments

Value

A named list compatible with fitmodel() output.

QRPEM compatibility check for time-varying covariates inside stparm()

Description

Synchronous, engine-free. Returns structured issues when method is QRPEM (or IMPEM), a mapped covariate has multiple values within at least one subject, and that covariate is referenced on the RHS of a stparm() statement. A corrected split model (covariate only in a body assignment) returns no errors. When method is omitted or cannot be resolved, the check assumes the engineParams() default, which is never QRPEM (FOCE-ELS or Laplacian for population models, Naive-Pooled otherwise) - so an omitted method never blocks here; pass method explicitly to check a QRPEM fit. Nonlinear covariate forms inside stparm() can also fail under QRPEM even when subject-constant; that case is not auto-detected here (see the KB antipattern).

Usage

.mcp_qrpem_time_varying_covariate_check(model, method)

Arguments

Value

A list with ok, checked, errors (character messages), and issues (structured rows).

Normalize the conditionNumber argument of engineParams() to an xcondmode integer code.

Description

Normalize the conditionNumber argument of engineParams() to an xcondmode integer code.

Usage

.normalizeConditionNumber(conditionNumber)

Arguments

Value

Integer xcondmode code (0-3).

Parse a dmp.txt file into the structured R object used by fitmodel/Xpose.

Description

Parse a dmp.txt file into the structured R object used by fitmodel/Xpose.

Usage

.parseDmpFile(dmpFilePath, stripLargeFields = TRUE, warnMissing = TRUE)

Arguments

Value

The parsed dmp.txt R object, or NULL on failure.

Parse a "ParamName-CovName" string into its components.

Description

Parse a "ParamName-CovName" string into its components.

Usage

.parseEffectPair(effectString)

Value

A list with paramName and covName, or NULL.

Parse enable IDs from a comma-separated string or numeric vector.

Description

Parse enable IDs from a comma-separated string or numeric vector.

Usage

.parseEnableIDs(ids)

Arguments

Value

An integer vector of enable IDs, or integer(0) if ids is empty or cannot be parsed.

Build a compact fit summary from a working directory.

Description

Reads dmp.txt and nlme7engine.log from workingDir and returns a seven-column data frame (Parameter, Type, Estimate, SE, %RSE, Shrinkage, Diagonal) describing the prior fit's fixed effects, omega variances and block covariances, and sigma diagonals at raw scale. Diagonal is TRUE for thetas, sigmas, secondaries, and omega variances, and FALSE for omega off-diagonal covariances; downstream consumers use it to keep covariances out of transformed, variance-scale summaries.

Usage

.readFitSummary(workingDir)

Arguments

Details

Failure / degradation policy (deliberately gracefully degraded relative to an all-or-nothing rule):

• dmp.txt missing or unparseable – returns NULL with a single warning. Callers must treat NULL as "no embedded fit summary" rather than as a failure.

• nlme7engine.log missing or unreadable – returns the full data frame with Shrinkage = NA for every row, plus a single warning naming the missing/unreadable file. The Estimate / SE / %RSE columns come from dmp.txt alone and stay valid.

• nlme7engine.log present and readable but contains zero eta-shrinkage / Epsilon shrinkage for lines – silent. This is the legitimate state for LL() observation models, naive-pooled fits, and any other topology where the engine doesn't compute eta/eps shrinkage.

• Eta-shrinkage line count in the log doesn't match length(colnames(dmp.txt$omega)) – returns the data frame with NA-padding/truncation, plus a single warning (mirrors Certara.Xpose.NLME::get_etaShrinkage's warning).

Value

A data frame with the columns above, or NULL when dmp.txt is missing/unparseable.

Reconstruct a model for a given SCM scenario by disabling effects that are not in the scenario's active enable IDs.

Description

Reconstruct a model for a given SCM scenario by disabling effects that are not in the scenario's active enable IDs.

Usage

.reconstructScmModel(model, scenarioEnableIDs)

Arguments

Value

A modified copy of the model with non-active effects disabled.

Require the MCP tool-builder dependency (ellmer) or stop with guidance

Description

Require the MCP tool-builder dependency (ellmer) or stop with guidance

Usage

.require_mcp_deps(packages = names(.mcp_dep_floors()))

Arguments

Value

Invisibly TRUE when satisfied; otherwise stops.

Validate PML syntax for textual models before engine launch.

Description

Runs TDL5 -i (via createModelInfo()) to verify that the PML in model@statements is syntactically valid. Returns invisibly on success; stop()s with a descriptive message on failure.

Usage

.validateTextualPml(model)

Arguments

Details

Built-in models (model@isTextual == FALSE) are always valid (PML is generated by RsNLME) and skip this check immediately.

Value

NULL, invisibly.

Represents parameters for a bootstrap run

Description

Class initializer for BootstrapParams that represents parameters for a bootstrap run.

Slots

numReplicates

Number of bootstrap replicates to run

initialEstimates

Get model final estimates to run bootstrap (T|F)

numRetries

Number of times to retry a failed replicated

randomNumSeed

Seed for random number generator

confidenceLevel

Confidence level

stratifyColumns

What columns to stratify on(comma separated)

Examples

# same object as BootstrapParams()
boot <- BootstrapParams(
  numReplicates = 100,
  initialEstimates = FALSE,
  numRetries = 2,
  randomNumSeed = 1234,
  confidenceLevel = 95
)

NLME covariate effects model object class

Description

Class represents an NLME covariate effects model

Slots

numCovariates

Number of covariate effects

covariateList

Comma separated list of covariate effects names

scenarioNames

Comma separated list of scenario names

isDefault

Comma separated list of flags

degreesOfFreedom

Comma separated list of degrees of freedom

enableIDs

Comma separated list of enable() IDs from the model

Examples

CovariateEffectModel(numCovariates = 2,
                     covariateList = "V-Age,Cl-BW",
                     scenarioNames = "S,S",
                     isDefault = "1,1",
                     degreesOfFreedom = "1,1",
                     enableIDs = "0,1")

Creates an extra dose parameter

Description

Creates an extra dose parameter

Arguments

Defines an extra dose point

Description

Defines an extra dose point

Slots

name

Dose point name

type

Character; Options are "Bolus" or "Infusion"

amount

Optional; Character specifying corresponding column in data or numeric specifying dose amount

rate

Optional; Character specifying corresponding column in data or numeric specifying dose rate

deltaTime

Optional; Character specifying corresponding column in data or numeric specifying delta time

isSecondDose

Use second dose point on compartment?

data

Optional data frame. Must specify data if supplying column as character value to amount, rate, deltaTime arguments

Class represents map between a model variable and a dataset column

Description

Class represents map between a model variable and a dataset column

Arguments

Class represents mapping list between model variables and dataset columns

Description

Class represents mapping list between model variables and dataset columns

Class represents an NLME Covariate parameter

Description

Class represents an NLME Covariate parameter

Arguments

NlmeCovariateParameter

Description

Class represents an NLME Covariate parameter

Arguments

NLME dataset object

Description

Class represents an NLME dataset object

Arguments

Examples

dataset <- NlmeDataset(workingDir)

Class represents mapping list between model variables and dose columns

Description

Class represents mapping list between model variables and dose columns

Class represents an NLME/PML Emax model parameters

Description

Class represents an NLME/PML Emax model parameters

Arguments

Create a new NlmeEngineExtraParams object

Description

This function creates a new instance of the NlmeEngineExtraParams class

Usage

NlmeEngineExtraParams(...)

Arguments

Value

An object of class NlmeEngineExtraParams.

NlmeEngineExtraParams : Defines all engine parameters for NLME models Wrapped up by engineParams function.

Description

NlmeEngineExtraParams : Defines all engine parameters for NLME models Wrapped up by engineParams function.

Slots

isPopulation

logical; TRUE if the model is a population model, FALSE for an individual model.

sort

character; String to pass sorting options to the NLME engine. Typically " -sort " to enable sorting or "" to disable it.

csv

character; String to control CSV input options. Typically " -csv " to strict the input data to comma-separated-values. Use "" to disable it (NLME will try to guess the input format).

method

numeric; Integer code specifying the estimation method.

• 1: QRPEM

• 2: IT2S-EM

• 3: FOCE-LB

• 4: FO

• 5: FOCE-ELS/LAPLACIAN (see below for choice between FOCE-ELS and LAPLACIAN)

• 6: NAIVE-POOLED

The choice between FOCE-ELS and LAPLACIAN (when method is 5) depends on the xfocehess slot: xfocehess = 1 selects FOCE-ELS, and xfocehess = 0 selects LAPLACIAN.

numIterations

numeric; The maximum number of iterations allowed for the estimation algorithm. Values must be non-negative integers.

odeToUse

numeric; Integer code specifying the ODE solver to be used. Possible values are:

• 1: LSODE with numerical Jacobian

• 2: LSODE with analytical Jacobian

• 3: Runge-Kutta

• 4: LSODA with numerical Jacobian

• 5: LSODA with analytical Jacobian

• 6: Matrix Exponent

• 7: DOPRI5

rtol

numeric; Specifies the relative tolerance for the ODE solver.

atol

numeric; Specifies the absolute tolerance for the ODE solver.

nmxstep

numeric; Specifies the maximum number of steps allowed for the ODE solver.

anagrad

numeric; Flag controlling the differentiation method used during the optimization of random effects (etas). 0 uses a finite difference approach, and 1 uses automatic differentiation where possible. Corresponds to the engine flag -anagrad.

popad

numeric; Flag controlling population-level (outer-loop) automatic differentiation. 0 disables (default), 1 enables. When enabled, inner-loop AD (anagrad) is also required and will be forced on by the NLME engine. Corresponds to the engine flag -popad.

xnp

numeric; Controls the use of non-parametric (NP) optimization.

• 0: No NP optimization.

• 1: NONMEM-style NP optimization using posthoc estimates as support points.

• >1: Evolutionary NP algorithm with xnp generations.

xnorderagq

numeric; Specifies the number of quadrature points per dimension for Adaptive Gaussian Quadrature (AGQ). Only applicable when method is FOCE-ELS or LAPLACIAN.

• 1: Standard FOCE-ELS/LAPLACIAN computation (no AGQ).

• >1: AGQ is performed. The total number of quadrature points used is (number of ETAs)^xnorderagq.

xfocehess

numeric; Determines the method for calculating the Hessian matrix when using FOCE methods.

• 0: Use numerical second derivatives.

• 1: Use the FOCE approximation.

Applicable only when method is FOCE-ELS or LAPLACIAN.

xstderr

numeric; Specifies the method for standard error estimation.

• 0: No standard error estimation.

• 1: Central difference method.

• 2: Forward difference method.

xcondmode

numeric; Selects the basis and scope for the reported condition number when standard errors are computed.

• 0 (default): Covariance matrix of the estimated fixed effects only.

• 1: Correlation matrix of the estimated fixed effects only.

• 2: Covariance matrix of all estimated population parameters (fixed effects, standard deviations of residual errors, Omega).

• 3: Correlation matrix of all estimated population parameters. This is the only mode directly comparable to the condition number calculated from NONMEM's reported eigenvalues.

Independent of xstderr; controls only how the selected standard-error block is converted for the reported condition number. Corresponds to the engine flag -xcondmode (omitted when 0 to preserve the engine default). The basis actually used is also echoed in the engine's out.txt as a # conditionNumberBasis = ... comment following the condition = line.

sand

character; String to request sandwich standard error calculation. Typically " -sand " or "".

fisher

character; String to request Fisher score standard error calculation. Typically " -fscore " or "".

autodetect

character; String to request auto-detection of standard error method. Typically " -AutoSE " or "".

xlandig

numeric; Specifies the optimization accuracy (NDIGIT) for the outer loop (thetas and sigmas) when using FOCE-ELS or LAPLACIAN methods.

xlatol

numeric; Specifies the relative step size used for numerical computation of the Hessian matrix (second derivatives) during standard error calculation.

xblndig

numeric; Specifies the optimization accuracy (NDIGIT) for the inner loop (optimization of etas). Also applies to the single optimization loop in the NAIVE-POOLED method.

xbltol

numeric; Specifies the relative step size for numerical differentiation during model linearization.

gradTolOuter

Numeric maximum gradient tolerance in the outer (Theta/Omega/Sigma) optimization loop. Applicable to FOCE-ELS and LAPLACIAN methods.

stepTolOuter

Numeric maximum step tolerance in the outer (Theta/Omega/Sigma) optimization loop. Applicable to FOCE-ELS and LAPLACIAN methods.

gradTolInner

Numeric maximum gradient tolerance in the inner (Eta) optimization loop. Applicable to FOCE-ELS and LAPLACIAN methods.

stepTolInner

Numeric maximum step tolerance in the inner (Eta) optimization loop. Applicable to FOCE-ELS and LAPLACIAN methods.

refDeltaLagl

Numeric LL Delta tolerance value used during Theta/Omega/Sigma optimization. Applicable to FOCE-ELS and LAPLACIAN methods.

isPCWRES

numeric; Flag indicating if Population Conditional Weighted Residuals (PCWRES) should be computed. A value of 1 indicates computation, while 0 indicates no computation. Only applicable to population models.

xpcwresnrep

numeric; Stores the number of simulation replicates used for PCWRES computation. Applicable only when isPCWRES is 1.

xisample

numeric; Specifies the number of sample points used in the QRPEM algorithm. Only applicable when method is QRPEM.

xmapassist

numeric; Controls the use of MAP assistance in the QRPEM algorithm.

• 0: No MAP assistance.

• >0: The inner ETAs optimization loop is used in the QRPEM outer optimization loop with a periodicity equal to the value of xmapassist.

Only applicable when method is QRPEM.

xmapnp

numeric; Specifies the number of iterations for a preliminary Naive-Pooled optimization run before the main estimation. Applicable when the method is not NAIVE-POOLED.

ximpsampdof

numeric; Controls the importance sampling distribution used in the QRPEM algorithm. Only applicable when method is QRPEM.

• 0: Multivariate Normal distribution.

• 1: Multivariate Double Exponential (Laplace) distribution.

• 2: Direct sampling from the prior.

• 3-30: Multivariate T distribution with degrees of freedom equal to the value of ximpsampdof.

• -2: Mixture-2 distribution.

• -3: Mixture-3 distribution.

xmcpem

numeric; Controls the sampling method used in the QRPEM algorithm.

• 0: Quasi-Random sampling.

• 1: Monte-Carlo sampling.

Only applicable when method is QRPEM.

xpemrunall

numeric; Set to 1 to execute all requested iterations specified in numIterations. Only applicable to population models with method = "QRPEM".

xsirsamp

numeric; Specifies the number of samples per eta per subject used in the Sampling Importance Resampling (SIR) algorithm within QRPEM. Only applicable when method is QRPEM.

xburnin

numeric; Specifies the number of burn-in iterations in the QRPEM algorithm. During burn-in, omegas can be frozen (see xnonomegaburn). Only applicable when method is QRPEM.

xnonomegaburn

numeric; Controls whether omegas are frozen during the burn-in phase of the QRPEM algorithm.

• 0: burn-in with frozen omegas is off.

• 1: burn-in with frozen omegas is on.

Only applicable when method is QRPEM. See also xburnin.

xaccratio

numeric; Specifies the acceptance ratio used in the QRPEM algorithm for scaling the covariance matrix. Only applicable when method is QRPEM. Only applicable to population models with method = "QRPEM".

xscramble

numeric; Specifies the scrambling method for quasi-random number generation in the QRPEM algorithm.

• 0: No scrambling.

• 1: Owen-type scrambling.

• 2: Faure-Tezuka scrambling.

Only applicable when method is QRPEM.

emTolType

Numeric specifying QRPEM convergence check type:

0

Default (no rollout, LL & Thetas)

1

LL & Params with rollout

2

LL with rollout

3

Params with rollout

Only applicable when method is QRPEM.

emConvLen

Numeric specifying the number of iterations to check for convergence. Only applicable when method is QRPEM.

emConvCritVal

Numeric specifying the convergence critical value. Only applicable when method is QRPEM.

pardern

numeric; Specifies the number of time steps used for outputting partial derivatives of observed variables with respect to parameters. Only applicable to individual models.

parderd

numeric; Specifies the step size for numerical calculation of partial derivatives of observed variables with respect to parameters. Only applicable to individual models.

logtran

numeric; Engine flag controlling log-transformation behavior for single LogAdditive error model.

See Also

engineParams()

Examples

param <- NlmeEngineExtraParams(
  method = 3,
  numIterations = 1000
)
param <- NlmeEngineExtraParams(
  method = 1,
  numIterations = 300
)
param <- NlmeEngineExtraParams(
  method = 1,
  numIterations = 300,
  isPopulation = TRUE,
  odeToUse = 2
)

Class represents an NLME/PML error model

Description

Class represents an NLME/PML error model

Arguments

Class represents an NLME/PML Indirect PD model parameters

Description

Class represents an NLME/PML Indirect PD model parameters

Arguments

Reads progress file and returns the status of a job

Description

Reads progress file and returns the status of a job

Usage

NlmeJobStatus(job)

Arguments

Value

Character. Job status messages.

Examples

## Not run: 
  model <- pkmodel(
    parameterization = "Clearance",
    numCompartments = 2,
    data = pkData,
    ID = "Subject",
    Time = "Act_Time",
    A1 = "Amount",
    CObs = "Conc",
    workingDir = tempdir()
  )

  params <- NlmeEngineExtraParams(
    method = 3,
    numIterations = 1
  )

  host <- hostParams(
    sharedDirectory = tempdir(),
    parallelMethod = "LOCAL_MPI",
    hostName = "local_mpi",
    numCores = 4
  )

  profile1 <- ProfileVar(
    "tvV",
    9.548,
    "-2,0"
  )

  profile2 <- ProfileVar(
    "tvCl",
    0.919,
    "-0.5,0"
  )

  profiles <- ProfileParameters(
    "USE_DELTA",
    c(profile1, profile2)
  )

  job <- profilePertubate(
    hostPlatform = host,
    params = params,
    profiles = profiles,
    model = model
  )

  status <- NlmeJobStatus(job)

## End(Not run)

Class initializer for NlmeObservationVar-class

Description

Describes an observation(observe,multi,...)

Arguments

Examples

var <- NlmeObservationVar(
  name = "Cobs",
  xaxis = "t",
  binningMethod = "none",
  quantilesValues = c(5, 50, 95)
)

NlmeParallelHost Class

Description

This class defines an NLME parallel host, which can be either local or remote, for running jobs.

Slots

sharedDirectory

character. The directory where the run will take place. On Windows, UNC paths are mapped to a drive letter for local execution.

installationDirectory

character. The directory containing NLME libraries and scripts.

hostName

character. A user-friendly name for the host (e.g., "local_mpi").

machineName

character. The IP address or hostname of the machine. Defaults to the local system's node name.

hostType

character. The operating system of the host, either "windows" or "linux". For remote Linux systems, you can specify a supported distribution (e.g., "RHEL", "UBUNTU") to configure the PML_BIN_DIR environment variable. linux will be treated as "RHEL".

numCores

numeric. The number of compute cores to be used.

isLocal

logical. TRUE if the host is local, FALSE if remote.

rLocation

character. The path to the Rscript executable on a remote host. This is ignored for local runs.

scriptPath

character. The path to a script to execute on the remote host before Rscript is started. This is ignored for local runs.

userAuthentication

NlmeUserAuthentication. An object containing user credentials for remote host authentication. See NlmeUserAuthentication.

parallelMethod

NlmeParallelMethod. The parallel computing method to use (e.g., "LOCAL_MPI", "SGE", "TORQUE"). See NlmeParallelMethod.

mpiCoresPerJob

integer. Per-scenario MPI rank for the "Multicore_MPI" method. NA_integer_ (default) lets NLME8 size the rank from the current batch; any positive integer fixes the per-job MPI width. Must be ⁠<= numCores⁠ and divide numCores evenly.

gridQueue

character. Scheduler queue or partition for grid methods (e.g. "bg.q" on SGE, "batch" on SLURM). Empty (default) uses the cluster default queue. Ignored for local methods.

gridWalltime

integer. Wall-clock limit in seconds for grid jobs. NA_integer_ (default) imposes no limit. Ignored for local methods.

gridMemory

character. Memory request for grid jobs (e.g. "16G"). Empty (default) requests no explicit memory. Ignored for local methods.

gridJobNamePrefix

character. Prefix for the scheduler job name shown in qstat/squeue. Empty (default) derives a name from the workflow. Ignored for local methods.

gridResourceExtra

character. Additional site-specific resource request appended verbatim to the scheduler directive (e.g. "h_data=4G"). Ignored for local methods.

Examples

host <- hostParams(
  parallelMethod = "LOCAL_MPI",
  hostName = "local_mpi",
  numCores = 4
)

Class initializer for NlmeParallelMethod

Description

Use to define NlmeParallelMethod as for parallelMethod argument in NlmeParallelHost.

Slots

method

Options are: None|Multicore|Multicore_MPI|LOCAL_MPI|SGE|SGE_MPI|TORQUE|TORQUE_MPI|LSF|LSF_MPI|SLURM|SLURM_MPI.

Multicore_MPI runs several MPI jobs concurrently on a single local machine; pair it with mpiCoresPerJob in hostParams() to fix the per-job MPI rank, or omit mpiCoresPerJob to let NLME8 size it from the current batch.

Class represents mapping list between model variables and data columns

Description

Class represents mapping list between model variables and data columns

Class represents an NLME/PML PK model parameters

Description

Class represents an NLME/PML PK model parameters

Arguments

Class initializaer for NlmePmlModel object

Description

The following class represents an NLME/PML model object.

Slots

isPopulation

Is this a population model (TRUE) or individual (FALSE)?

modelType

Taken from NlmeModelType

isTimeBased

Is model time-based?

linearModelType

Type of linear model

isLinearFrozen

Is linear model frozen?

pkModelAttrs

Taken from NlmePkParameters

indirectModelAttrs

Taken from NlmeIndirectParameters

emaxModelAttrs

Taken from NlmeEmaxParameters

hasEffectsCompartment

Is there data available for an effects compartment?

errorModel

Taken from NlmeErrorModel

structuralParams

List of structural parameters

outputParams

List of output parameters

diffEquations

List of differential equations

statements

List of PML statements

dosePoints

List of dosepoints

covariateList

List of covariates

columnMapping

Taken from NlmeColumnMapping

doseMapping

Taken from NlmeDoseMapping

paramsMapping

Taken from NlmeParamsMapping

randParamsMapping

Taken from NlmeRandParamsMapping

inputData

Input data source

doseData

Dose data source

fixedParamData

Fixed effect parameter data source

randParamData

Random effect parameter data source

isTextual

Is model textual (TRUE) or graphical (FALSE)?

pmloutput

List of PML output to generate

modelInfo

Taken from NlmePmlModelInfo

objects

deprecated

objectsNeedRegenerating

deprecated

randomEffectsStatements

Custom random effects statements

randomOccasionalEffectsStatements

Custom random occasional effects statements

userDefinedExtraDefs

Custom definition for extra column and table generation

Examples

# helper class
setClass("NlmePmlModelInfo",
         slots = c(modelName = "character",
                   workingDir = "character"))
Model <-
  new("NlmePmlModel",
  modelInfo = new("NlmePmlModelInfo", modelName = "Model", workingDir = "."))

Class initializer for NlmeRemoteExecutor

Description

Creates Remote Executor object class

Slots

sharedDirectory

The directory in which the run executes

installationDirectory

Directory containing NLME libraries/scripts

hostName

IP or name of remote host

userAuthentication

Credential for user to log into remote system

Class represents an NLME/PML residual error model

Description

Class represents an NLME/PML residual error model

Arguments

Class initializer for NlmeScenario

Description

Creates NlmeScenario class object

Arguments

Examples

CovariateEffectNames <- c("dVdBodyWeight",  "dCldBodyWeight")
#   Do not use any covariate effects
scenario1 <- NlmeScenario("no_covariates", "")
#   Use covariate effect index 1
scenario2 <- NlmeScenario("dVdBodyWeight", "1")
#   Use second covariate effect in the model
scenario3 <- NlmeScenario("dCldBodyWeight", "2")
#   Use 1st and 2nd covariate effect
scenario4 <- NlmeScenario("dVdBodyWeight_dCldBodyWeight", "1,2")

Class initializer for NlmeSimTableDef

Description

Creates NlmeSimTableDef class object used to specify parameters for VPC/Simulation runs

Arguments

Class initializer for NlmeSimulationParams

Description

Use to create set of parameters for simulation runs. Parameters numPoints, maxXRange, yVariables, simAtObs are related to the model in individual mode. They will be outputted to the file specified in model@dataset@simoutFilename, simout.csv by default

Arguments

See Also

tableParams, NlmeSimTableDef

Examples

table1 <- tableParams(
  name = "simulate.csv",
  timesList = "0,2,4,12,24",
  variablesList = "V,Cl",
  timeAfterDose = TRUE,
  forSimulation = TRUE
)

simParam <- NlmeSimulationParams(
  numReplicates = 10,
  seed = 29423,
  simulationTables = c(table1)
)

simParam <- NlmeSimulationParams(
  numPoints = 100,
  maxXRange = 50,
  yVariables = "C,A1",
  simulationTables = table1
)

Class represents style of structural parameter

Description

Class represents style of structural parameter

Slots

style

Parameter style: 1=LogNormal, 2=Normal, 3=Combination, 4=Log, 5=Logit

Class initializer for NlmeTableDef

Description

Creates NlmeTableDef class object used to specify parameters for fitting runs

Arguments

Class initializer for NlmeUserAuthentication

Description

Use for authentication records

Slots

userName

How the user is identified to the remote system

privateKeyFile

path to private key file, see keyfile for details

userPassword

either a string or a callback function for password prompt, see passwd for details

Arguments for VPC runs

Description

Class initializer for arguments of visual predictive check (VPC) runs

Arguments

See Also

tableParams, NlmeSimTableDef, NlmeObservationVar

Examples

## Not run: 
model <- pkmodel(
  parameterization = "Clearance",
  numCompartments = 2,
  data = pkData,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc",
  workingDir = tempdir()
  )

# Define the host
host <- hostParams(parallelMethod = "NONE",
                   hostName = "local",
                   numCores = 1,
                   sharedDirectory = tempdir())
job <- fitmodel(model,
                hostPlatform = host)

# View estimation results
print(job)

finalModelVPC <- copyModel(model,
                           acceptAllEffects = TRUE,
                           modelName = "model_VPC",
                           workingDir = tempdir())

# View the model
print(finalModelVPC)

# Set up VPC arguments to have PRED outputted to simulation output dataset "predout.csv"
vpcSetup <- NlmeVpcParams(outputPRED = TRUE)

# Run VPC using the default host, default values for the relevant NLME engine arguments
finalVPCJob <-
  vpcmodel(model = finalModelVPC, vpcParams = vpcSetup, )


## End(Not run)

Pharmacokinetic dataset containing 100 subjects with single dose given by infusion

Description

Pharmacokinetic dataset containing 16 subjects with single dose given by infusion.

Usage

OneCpt_IVInfusionData

Format

A data frame with 800 rows and 6 variables:

Subject

Subject ID

Time

Time point

Dose

Amount of dose

CObs

Observations of drug concentration in blood

Rate

Rate of infusion

Duration

Duration of infusion

Source

The data is simulated using a PK model described by a one-compartment model with IV infusion

Class initializer for ProfileParameters

Description

Class represents an NLME profile perturbation variable

Slots

howToPertubate

How to apply profile variables. Options are USE_DELTA or USE_PERCENTAGE

profileVars

List of profile variables

Examples

profile1 <- ProfileVar("tvV", 9.548, "-2,-1,0,1,2")
profile2 <- ProfileVar("tvCl", 3.219, "-1,0,1")
profiles <- ProfileParameters("USE_DELTA", c(profile1, profile2))

NLME Profile variable

Description

Class initializer for an NLME profile perturbation variable

Arguments

Examples

ProfileVar("tvV", 9.95, "-2,-1,0,1,2")

Class initializer for ResetColumnInfo

Description

Class initializer for ResetColumnInfo

Arguments

Backgrounded NLME job classes

Description

S4 classes for NLME runs launched with runInBackground = TRUE. SimpleNlmeJob is the shared base; the run-specific subclasses (BootNlmeJob, FitNlmeJob, StepwiseNlmeJob, ShotgunNlmeJob, ProfileNlmeJob, SortByNlmeJob, and NlmeSimulationJob) carry the launch context for their run mode and are materialised with collectJob. They are returned to the caller as handles; you rarely construct them directly.

Slots

jobType

GENERIC/ESTIMATION_RUN/COVAR_SEARCH/PROFILE_RUN/STEPWISE_SEARCH/BOOTSTRAP/Sort_By_Column

localDir

where the data/model files are taken and the results are loaded for the local and remote runs

remoteDir

where the data/model files are taken and the results are loaded on remote host

host

local/remote job parallelization type

argsList

list of arguments for run

argsFile

file for arguments for run

scriptFile

initial script generation

workflow

workflow name

runInBackground

should the job be executed in background or not

Class initializer for SortColumns

Description

Class represents an NLME sort columns object

Arguments

Examples

# The following two setups are equivalent
sortColumnSetUp <- SortColumns("Country,City")
sortColumnSetUp <- SortColumns(c("Country","City"))

# The following two setups are equivalent
sortColumnSetUp <- SortColumns("Sort1 Sort2", "Sort3")
sortColumnSetUp <- SortColumns(c("Sort1, Sort2 "), "Sort3 ")

Class initializer for NLME StepwiseParams

Description

Class represents an NLME Stepwise search parameters

Arguments

Examples

StepwiseParams(0.001, 0.001, "BIC")

Subset SCM search results

Description

Preserves SCM-specific attributes when subsetting still returns a data frame.

Usage

## S3 method for class 'scmSearchResult'
x[...]

Arguments

Value

The subsetted object. If the result is still a data frame, it keeps the scmSearchResult class.

Accepts all estimates for fixed effects, Sigma, and random effects

Description

Updates PML statements in model object with estimates returned from model execution. Use copyModel and set argument acceptAllEffects = TRUE to create new model object with final estimates from base model run.

Usage

acceptAllEffects(model)

Arguments

Value

NlmePmlModel object

See Also

copyModel

Examples

## Not run: 
# Define the model
model <- pkmodel(numComp = 1,
                 absorption = "Intravenous",
                 ID = "Subject",
                 Time = "Act_Time",
                 CObs = "Conc",
                 A1 = "Amount",
                 data = pkData,
                 modelName = "PkModel",
                 workingDir = tempdir())

# Fit model
res <- fitmodel(model = model,
                hostPlatform = hostParams(sharedDirectory = tempdir()))
model <- acceptAllEffects(model)

## End(Not run)

Adds ADDL extra column definition to model object

Description

Specify ADDL column definition in model object instead of specifying ADDL through addDoseCycle

Usage

addADDL(.Object, ADDL, II)

Arguments

Value

Modified NlmePmlModel object

Examples

pkData1 <- pkData
pkData1$ii <- 0
pkData1$addl <- 0
 model <- pkmodel(numComp = 2,
                  absorption = "FirstOrder",
                  ID = "Subject",
                  Time = "Act_Time",
                  CObs = "Conc",
                  Aa = "Amount",
                  data = pkData1,
                  modelName = "PkModel",
                  workingDir = tempdir())
 model <- addADDL(model, ADDL = "addl", II = "ii")

Add covariate to model object

Description

Add a continuous, categorical, or occasion covariate to model object and set covariate effect on structural parameters.

Usage

addCovariate(
  .Object,
  covariate,
  effect = NULL,
  type = c("Continuous", "Categorical", "Occasion"),
  direction = c("Forward", "Interpolate", "Backward"),
  option = c("Yes", "PlusOne", "No"),
  center = NULL,
  centerValue = NULL,
  levels = NULL,
  labels = NULL,
  isDiagonal = TRUE,
  values = NULL,
  isPositive = TRUE
)

Arguments

Details

The following relationships are applicable for covariates:

• direction = "Forward" is equivalent to PML code 'fcovariate(CovName)';

• direction = "Backward" is equivalent to PML code 'covariate(CovName)';

• direction = "Interpolate" is equivalent to PML code 'interpolate(CovName)'.

  If the structural parameter has style = "LogNormal", the options are reflected in PML code as follows:

• option = "Yes" is equivalent to stparm(V = tvV * wt^dVdwt * exp(dVdsex1*(sex==1)) * exp(nV));

• ⁠option = "PlusOne⁠ is equivalent to stparm(V = tvV * (1+wt*dVdwt) * (1+dVdsex1*(sex==1)) * exp(nV)).

Value

Modified NlmePmlModel object

Examples

model <- pkmodel(
  numCompartments = 2,
  data = pkData,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc",
  workingDir = tempdir()
)

# Add Gender covariate of type categorical
model <- addCovariate(model,
  covariate = "Gender",
  type = "Categorical",
  effect = c("V2", "Cl2"),
  levels = c(0, 1),
  labels = c("Female", "Male")
)

# Add BodyWeight covariate of type continuous
model <- addCovariate(model,
  covariate = "BodyWeight",
  type = "Continuous",
  direction = "Backward",
  center = "Mean",
  effect = c("V", "Cl")
)

Adds a dosing cycle to model

Description

Add Steady State or ADDL dosing cycle to model object.

Usage

addDoseCycle(
  .Object,
  type = "SteadyState",
  name,
  administration = "Bolus",
  amount = NULL,
  II = NULL,
  rate = NULL,
  duration = NULL,
  isSecondDose = FALSE,
  colName = NULL
)

Arguments

Value

Modified NlmePmlModel object

See Also

doseNames

Examples

model <- addDoseCycle(pkmodel(columnMap = FALSE,
                              isPopulation = FALSE,
                              workingDir = tempdir()),
                      type = "SteadyState",
                      name = "A1",
                      amount = "Amount",
                      II = "II")

Adds user defined extra column/table definitions to column definition file

Description

Adds user defined extra column/table definitions to column definition file

Usage

addExtraDef(.Object, value)

Arguments

Value

Modified NlmePmlModel object

Examples

model <- pkmodel(columnMap = FALSE,
                 workingDir = tempdir())
model <- addExtraDef(model, c("addlcol(ADDL)",
                              "table(file=\"res.csv\",time(0),Ka,V,Cl,Tlg)"))

Change existing dosing compartment to infusion

Description

Allows user to switch any dosing compartment to infusion

Usage

addInfusion(
  .Object,
  doseCptName,
  isDuration = FALSE,
  isSecondDose = FALSE,
  colName = NULL
)

Arguments

Value

Modified NlmePmlModel object

Examples

 pkData1 <- pkData
 pkData1$A1_1 <- 0
 model <- pkmodel(numComp = 2,
 absorption = "Intravenous",
 ID = "Subject",
 Time = "Act_Time",
 CObs = "Conc",
 A1 = "Amount",
 data = pkData1,
 modelName = "PkModel",
 workingDir = tempdir())
 newModel <- addInfusion(model, "A1", FALSE, FALSE, "A1_1")

Add levels and labels to categorical or occasion covariate

Description

Allows users to specify the name and the associated value for each category/occasion of a categorical/occasion covariate in a textual model object. Only applicable to the case where the corresponding input data column of a categorical/occasion covariate is of class character.

Usage

addLabel(.Object, covariate, levels, labels)

Arguments

Value

Modified NlmePmlModel object

Examples

model <- pkmodel(columnMap = FALSE,
                 isPopulation = FALSE,
                 workingDir = tempdir())

model <- suppressWarnings(addCovariate(model,
                      covariate = "Gender",
                      type = "Categorical",
                      effect = c("V"),
                      levels = c(0, 1)))
model@isTextual <- TRUE
model <- addLabel(model, "Gender", c(1, 2), c("male", "female"))

Adds MDV extra column definition to model object

Description

Use to add MDV statement to model@userDefinedExtraDefs

Usage

addMDV(.Object, MDV)

Arguments

Value

Modified NlmePmlModel object

Examples

pkData1 <- pkData
pkData1$MDV <- 0
model <- pkmodel(data = pkData1,
                 ID = "Subject",
                 Time = "Act_Time",
                 A1 = "Amount",
                 CObs = "Conc",
                 workingDir = tempdir()
                 )
model <- addMDV(model, MDV = "MDV")

Adds reset instructions to the model

Description

Adds reset instructions to the model

Usage

addReset(.Object, low, hi, Reset = NULL)

## S4 method for signature 'NlmePmlModel'
addReset(.Object, low, hi, Reset = NULL)

Arguments

Value

Depends on the specific methods

Returns the 'NlmePmlModel' object with updated reset information and definitions.

Functions

• addReset(NlmePmlModel): Method for the 'NlmePmlModel' class

  This method adds reset instructions to the NlmePmlModel object. It updates the reset information, checks column mappings if input data is not null, and adds a reset definition to user-defined extra definitions.

Adds a secondary parameter to model definition

Description

Adds a secondary parameter to model definition

Usage

addSecondary(.Object, name, definition, unit = "")

## S4 method for signature 'NlmePmlModel'
addSecondary(.Object, name, definition, unit = "")

Arguments

Value

Depends on the specific methods

Returns the 'NlmePmlModel' object with the added secondary parameter.

Functions

• addSecondary(NlmePmlModel): Method for the 'NlmePmlModel' class

  This method adds a secondary parameter to the NlmePmlModel object. It checks for duplicate parameter names, and if there is no duplicate, it adds the new secondary parameter to the object and updates the PML model.

Examples

model <- pkmodel(columnMap = FALSE,
                 absorption = "FirstOrder",
                 workingDir = tempdir())
model <- addSecondary(model, "Ke", "tvCl/tvV")
model <- addSecondary(
  model, "Tmax",
  "CalcTMax(tvA,tvCl/tvV)"
)

Adds Steady State extra column definition to model object

Description

Use to add Steady State column definition statement to model@userDefinedExtraDefs

Usage

addSteadyState(.Object, SS, II, SSOffset = NULL)

Arguments

Value

Modified NlmePmlModel object

Examples

pkData1 <- pkData
pkData1$SS <- 0
pkData1$II <- 0
model <- pkmodel(data = pkData1,
                 ID = "Subject",
                 Time = "Act_Time",
                 A1 = "Amount",
                 CObs = "Conc",
                 workingDir = tempdir()
                 )
model <- addSteadyState(model, SS = "SS", II = "II")

Add to the NLME Error model

Description

Add to the NLME Error model

Usage

addToErrorModel(model, effectsList)

Arguments

Advance a sequential-LRT session by one bounded, idempotent transition

Description

Call this repeatedly to drive a session from start_sequential_lrt() through to completion. Each call performs at most one bounded pass: resolve the anchor (refit status + OFV parity) while state == "anchoring", or - once state == "testing" - collect any finished candidate fits, decide the current phase's winner (forward addition accepts the most significant approved effect with p < alpha_add; backward elimination removes the least-supported approved effect with p >= alpha_remove; ties/order come only from the approved plan), advance the reference on acceptance, and launch newly-ready operations up to host_resources$max_concurrent_fits and the remaining fit_budget. Safe to call again while running (it just re-polls); pauses with requires_user_attention = TRUE on OFV-parity failure, a failed reference fit, an altered plan.json, or exhausted budget.

Usage

advance_sequential_lrt(
  session_id,
  project_dir = ".",
  candidate_updates = NULL,
  force_continue = FALSE
)

Arguments

Value

A compact session status: state, phase, reference, fit_budget/fit_budget_used, status_counts, per-operation test_results, anchor_ofv_parity (once resolved), requires_user_attention/explanation when paused, and next_action.

See Also

get_sequential_lrt_status() for a read-only peek without advancing, collect_sequential_lrt() for the final report.

Analyze a NONMEM control stream

Description

Parses a NONMEM control stream and returns a structured, understanding-led analysis: which records are present, the ADVAN/TRANS structure, parameter counts, an ⁠$INPUT⁠-derived column-mapping hint, the recommended translation path (builtin model vs textual PML), an estimation summary, and explicit open_questions / unsupported lists for constructs without a clean PML analog. It fails loud on an unparseable stream and extracts partially rather than silently mis-parsing. It does not write PML; use draft_pml_from_nonmem() for that.

Usage

analyze_nonmem_control(control_text = NULL, path = NULL)

Arguments

Value

A list describing the parsed model (see the function's sections, structure, parameters, column_mapping_hint, estimation, open_questions, unsupported, and ok/partial fields).

Executes an NLME Bootstrap

Description

Method to execute an NLME Bootstrap

Usage

bootstrap(
  model,
  hostPlatform = NULL,
  params,
  bootParams,
  runInBackground = FALSE,
  saveResult = TRUE,
  overwriteFitDir = FALSE,
  ...
)

Arguments

Value

When runInBackground = FALSE, an rsnlme_boot object: a named list of bootstrap result tables with class c("rsnlme_boot", "list") and metadata attributes. The list carries the existing aggregates (BootOverall, BootTheta, BootOmega, BootOmegaCorrelation, BootOmegaStderr, BootVarCoVar, BootSecondary) plus the per-replicate stacks and per-parameter CI tables emitted by recent NLME8 builds (BootThetaStacked, BootOmegaStacked, BootSigmaStacked, BootOmegaCI, BootSigmaCI, BootEtaShrinkage, BootEpsShrinkage). When bootParams@initialEstimates is TRUE, a compact fitSummary table built from dmp.txt + nlme7engine.log is also embedded. See ?rsnlme_boot for the full field and attribute contract and ?print.rsnlme_boot for the rendered output.

When saveResult = TRUE (the default), the rsnlme_boot is also written to disk; see the saveResult parameter for the exact path.

When runInBackground = TRUE, the bare BootNlmeJob is returned; pass it to collectJob() to obtain the rsnlme_boot (the RDS write, if requested, happens at that point).

See Also

hostParams, engineParams, BootstrapParams, rsnlme_boot, collectJob

Examples

## Not run: 
input_data <- pkData

model <-
  pkmodel(
    numCompartments = 2,
    data = input_data,
    ID = "Subject",
    Time = "Act_Time",
    A1 = "Amount",
    CObs = "Conc",
    workingDir = tempdir()
  )

# multicore
multicoreHost <- hostParams(
  sharedDirectory = tempdir(),
  parallelMethod = "Multicore",
  hostName = "local_multicore",
  numCores = 4
)

bootstrapdf <- bootstrap(model,
  hostPlatform = multicoreHost,
  params = engineParams(model),
  numReplicates = 5,
  randomNumSeed = 1234,
  runInBackground = FALSE
)

## End(Not run)

Generic function for cancelling a job

Description

Generic function for cancelling a job

Usage

cancelJob(.Object)

## S4 method for signature 'SimpleNlmeJob'
cancelJob(.Object)

Arguments

Value

Depends on the specific methods

Prints the 'SimpleNlmeJob' object after attempting to cancel the job. No return value.

Functions

• cancelJob(SimpleNlmeJob): Method for cancelling a job of the 'SimpleNlmeJob' class

  This method attempts to cancel a job of the 'SimpleNlmeJob' class. If the job is running on a local host or is not running in the background, it throws an error and does nothing. Otherwise, it uploads a 'STOP' command to the host's remote executor.

Certara.RsNLME MCP tool definitions (NLME provider slice)

Description

Returns the NLME-specific authoring, data, execution, comparison, and interpretation tools as a list of ellmer::tool() objects. This is the builder named by inst/mcp/tools/manifest.json; the Certara.R MCP host discovers it and merges these tools with its own knowledge/memory/meta tools. The generic KB, memory, and capabilities tools live in the host, not here.

Usage

certara_mcp_tools(
  groups = c("knowledge", "data", "execution", "comparison", "interpretation",
    "qualification")
)

Arguments

Value

A list of ellmer ToolDef objects.

Check Host Parameters

Description

Checks NLME Parallel Host object for correct settings for GCC, NLME Installation, MPI and Root directories.

Usage

checkHostParams(obj, verbose = FALSE)

Arguments

Value

TRUE if all checks are successful, otherwise FALSE

Examples

## Not run: 

# multicore
multicoreHost <- hostParams(
  parallelMethod = "Multicore",
  hostName = "local_multicore",
  numCores = 4
)
checkHostParams(multicoreHost)

## End(Not run)

Reconcile a Darwin search candidate's OFV against an RsNLME refit's -2LL

Description

Before trusting a recovered pyDarwin (Certara.RDarwin) candidate as a structural anchor for sequential LRT, its results.csv$ofv (the raw -2LL; never fitness, which adds pyDarwin's penalties/postprocess terms) must be reconciled against this job's RsNLME refit ⁠-2LL⁠. A mismatch beyond tolerance most often means the metamodel's chained ⁠##ESTARGS⁠ estimation stages, BLQ handling, or starting estimates were not fully mirrored in the refit - and any likelihood comparison built on an unreconciled anchor is not trustworthy.

Usage

check_ofv_parity(job_id, darwin_ofv, project_dir = ".", tolerance = NULL)

Arguments

Value

A list with job_id, darwin_ofv, refit_neg2ll, tolerance, abs_delta, and parity_ok (TRUE/FALSE, or NA when the refit is not yet terminal-successful or darwin_ofv was not numeric). On a mismatch (or NA), also sets requires_user_attention = TRUE and an explanation of the likely cause.

Clean up stale or old MCP runs

Description

Clean up stale or old MCP runs

Usage

cleanup_mcp_runs(older_than = 90, project_dir = ".")

Arguments

Value

A list of removed job ids.

Add column mappings

Description

Piping compatible function for modelColumnMapping used to add column mappings from input data to model object

Usage

colMapping(.Object, mappings = NULL, ...)

Arguments

Value

modified NlmePmlModel object

See Also

dataMapping modelVariableNames

Examples

pkData$id2 <- pkData$Subject
model <- pkmodel(columnMap = FALSE,
                 data = pkData,
                 workingDir = tempdir())

modelvar <- unlist(modelVariableNames(model))

colnames <- c("Subject", "Act_Time", "Amount", "Conc")
names(colnames) <- modelvar
# will map subject directly
colnames <- colnames[-c(1)]

model <- colMapping(model, colnames, id = c(Subject, id2))
# also possible:
model <- colMapping(model, colnames, id = c("Subject", "id2"))
# not recommended since only not quoted names are identified
# if both types are provided:
model <- colMapping(model, colnames, id = c("Subject", id2))

Collect the typed result of a finished NLME job

Description

Polls a backgrounded NlmeJob via NlmeJobStatus until the engine reports "Finished", then materialises the typed result. Remote-results download (when applicable) and CSV/log parsing are handled by the class-specific method body. collectJob() is the single canonical entry point for any runInBackground = TRUE run.

Usage

collectJob(job, timeout = Inf, pollInterval = 5, ...)

## S4 method for signature 'BootNlmeJob'
collectJob(job, timeout = Inf, pollInterval = 5, ...)

## S4 method for signature 'FitNlmeJob'
collectJob(job, timeout = Inf, pollInterval = 5, ...)

## S4 method for signature 'StepwiseNlmeJob'
collectJob(job, timeout = Inf, pollInterval = 5, ...)

## S4 method for signature 'ShotgunNlmeJob'
collectJob(job, timeout = Inf, pollInterval = 5, ...)

## S4 method for signature 'ProfileNlmeJob'
collectJob(job, timeout = Inf, pollInterval = 5, ...)

## S4 method for signature 'SortByNlmeJob'
collectJob(job, timeout = Inf, pollInterval = 5, ...)

## S4 method for signature 'NlmeSimulationJob'
collectJob(job, timeout = Inf, pollInterval = 5, ...)

Arguments

Details

Background jobs are only started on Linux hosts (local hostType "linux" or remote "linux" / "RHEL" / "UBUNTU"). Wrappers on Windows do not support runInBackground = TRUE; see ?fitmodel for the platform rule shared by all job executors.

Dispatches on BootNlmeJob, FitNlmeJob, StepwiseNlmeJob, ShotgunNlmeJob, ProfileNlmeJob, SortByNlmeJob, and NlmeSimulationJob (the shared class behind both vpcmodel and simmodel, discriminated by its validated runMode slot).

Value

A class-specific result object. For BootNlmeJob, an rsnlme_boot. For FitNlmeJob and SortByNlmeJob, the same result list fitmodel / sortfit produces. For StepwiseNlmeJob and ShotgunNlmeJob, an scmSearchResult (zero-row when Overall.csv is missing). For ProfileNlmeJob, a profileResult data frame (zero-row when Profile.csv is missing). For NlmeSimulationJob, the same named list of data.tables that vpcmodel / simmodel produces, with additive runMode/runTime/RsNLMEVersion list elements.

Functions

• collectJob(BootNlmeJob): Wait for a backgrounded BootNlmeJob to finish and return its rsnlme_boot. Downloads remote artefacts idempotently when file.path(localDir, "BootOverall.csv") is absent, then reads the bootstrap CSVs from job@localDir into the typed rsnlme_boot (forwarding job@boot for replicate counts / confidence level and job@argsList$engine for the engine attribute) and – if job@saveResult is TRUE – writes the result to <localDir>/bootstrap_<sanitizedModelName>_<YYYYMMDD_HHMMSS>.rds, where sanitizedModelName is job@model@modelInfo@modelName with every character outside [A-Za-z0-9._-] replaced by _ (falling back to model when empty) and the timestamp is job@runStart formatted as YYYYMMDD_HHMMSS in local time.

• collectJob(FitNlmeJob): Wait for a backgrounded FitNlmeJob to finish and return the same result list that fitmodel's foreground branch produces. Downloads remote artefacts idempotently when file.path(localDir, "nlme7engine.log") is absent, then reads engine outputs via .get_resultList() and – if job@saveResult is TRUE – writes the result to <localDir>/fitmodel_<sanitizedModelName>_<YYYYMMDD_HHMMSS>.rds, where sanitizedModelName is job@model@modelInfo@modelName with every character outside [A-Za-z0-9._-] replaced by _ (falling back to model when empty) and the timestamp is job@runStart formatted as YYYYMMDD_HHMMSS in local time.

• collectJob(StepwiseNlmeJob): Wait for a backgrounded StepwiseNlmeJob to finish and return the same scmSearchResult that stepwiseSearch's foreground branch produces. Downloads remote artefacts idempotently when file.path(localDir, "Overall.csv") is absent, then reads the search results via .read_covsearch_results() (which archives the run folder when job@archiveResults is TRUE) and applies the stepwise-only BestScenario flag from Stepwise.txt. Returns an empty scmSearchResult (zero-row, searchType attribute set) when Overall.csv is missing.

• collectJob(ShotgunNlmeJob): Wait for a backgrounded ShotgunNlmeJob to finish and return the same scmSearchResult that shotgunSearch's foreground branch produces. Downloads remote artefacts idempotently when file.path(localDir, "Overall.csv") is absent, then reads the search results via .read_covsearch_results() (which archives the run folder when job@archiveResults is TRUE). Returns an empty scmSearchResult (zero-row, searchType attribute set) when Overall.csv is missing.

• collectJob(ProfileNlmeJob): Wait for a backgrounded ProfileNlmeJob to finish and return the same profileResult that profilePertubate's foreground branch produces. Downloads remote artefacts idempotently when file.path(localDir, "Profile.csv") is absent, then reads the profile table via .read_profile_results() and – if job@saveResult is TRUE – writes a self-describing profile_<sanitizedModelName>_<YYYYMMDD_HHMMSS>.rds alongside the result, where sanitizedModelName is job@model@modelInfo@modelName with every character outside [A-Za-z0-9._-] replaced by _ (falling back to model when empty) and the timestamp is job@runStart formatted as YYYYMMDD_HHMMSS in local time. Returns an empty profileResult (zero-row, runMode = "profile" attribute set) when Profile.csv is missing.

• collectJob(SortByNlmeJob): Wait for a backgrounded SortByNlmeJob to finish and return the same result list that sortfit's foreground branch produces. Downloads remote artefacts idempotently when file.path(localDir, "nlme7engine.log") is absent, then reads engine outputs via .get_resultList() (the shared fitmodel/sortfit reader) with runMode = "sortfit" and – if job@saveResult is TRUE – writes the result to <localDir>/sortfit_<sanitizedModelName>_<YYYYMMDD_HHMMSS>.rds, where sanitizedModelName is job@model@modelInfo@modelName with every character outside [A-Za-z0-9._-] replaced by _ (falling back to model when empty) and the timestamp is job@runStart formatted as YYYYMMDD_HHMMSS in local time.

• collectJob(NlmeSimulationJob): Wait for a backgrounded NlmeSimulationJob (constructed by either vpcmodel or simmodel) to finish and return the same named list of data.tables the foreground branch produces. Sentinel is mode-specific: predout.csv when job@params@isPopulation is TRUE (population runs), otherwise simout.csv (individual runs). Reads the engine output via .read_vpcsim_results() and attaches the canonical runMode / runTime / RsNLMEVersion list elements.

See Also

bootstrap, fitmodel, stepwiseSearch, shotgunSearch, profilePertubate, sortfit, vpcmodel, simmodel, NlmeJobStatus

Collect a finished NLME job

Description

Returns a compact summary plus artifact paths. Does not stream large files.

Usage

collect_nlme_job(
  job_id,
  project_dir = ".",
  refresh_fit_health = TRUE,
  darwin_ofv = NULL,
  ofv_tolerance = NULL
)

Arguments

Details

The summary includes a fit_health block (data file size, engine status, return code, ⁠-2LL⁠, and whether stderr mentions a missing dataset) so a state == "succeeded" is not mistaken for a good fit - the common failure mode where a metamodel with a missing ⁠## DATA⁠ path "succeeds" on an empty data1.txt.

Value

A list summary with state, run_dir, artifact_dir, artifacts (paths relative to artifact_dir), fit_health, tail of logs, and a next_action directive: save_analysis_plan with blocking = TRUE when no plan is saved and this job was not launched under an approved allow_unplanned exception; get_project_workflow_status (non-blocking) on success once a plan exists or the exception is on record; NULL for a failed/dead job (see ⁠$failure⁠ instead). For failed/dead jobs requires_user_attention is TRUE and a failure block carries a normalized error_class, suggested_fix, and related_kb entry. When darwin_ofv is supplied, also includes ofv_parity. artifact_integrity reports whether the artifacts still match the manifest recorded for this job; a "violation" takes precedence over every other directive and yields a blocking artifact_integrity_violation next_action.

Collect the sequential-LRT report (decisions, telemetry, downstream gates)

Description

Readable at any point (not only once terminal): while a session is still "anchoring"/"testing", the report reflects progress so far and is_final = FALSE. Once state is "completed"/"budget_exhausted"/ "stopped", is_final = TRUE and downstream_proposals lists user-gated next steps (VPC, opt-in qpc_score, AIC/BIC re-confirmation against the original Darwin candidates, bootstrap, or a constrained Darwin rerun) - none of which launch automatically.

Usage

collect_sequential_lrt(session_id, project_dir = ".")

Arguments

Value

A list with state, phase, is_final, final_reference, anchor_job_id, anchor_ofv_parity, the full decisions ledger, accepted_effects/rejected_or_kept_effects, telemetry (fit counts, elapsed timestamps, budget usage, and session_provenance for later benchmarking via record_run()), and (once final) downstream_proposals.

Compare NLME fits on information criteria

Description

Synchronous, base-R comparison of two or more fits. Reads each source's Overall.csv (a registered job_id, a fit .rds path, or an Overall.csv path), builds a table of ⁠-2LL⁠, AIC, BIC, and the parameter count, and ranks by AIC and BIC with deltas against a reference (the best-AIC model by default, falling back to BIC then ⁠-2LL⁠ when AIC is unavailable). Replaces ad-hoc model-comparison scripts.

Usage

compare_nlme_jobs(
  job_ids,
  project_dir = ".",
  reference_job_id = NULL,
  nested = FALSE
)

Arguments

Details

Likelihood-ratio p-values are computed ONLY when nested = TRUE, because an LRT is valid only for nested models fit to the same data with comparable likelihoods. The function reports the numbers; the caller is responsible for the nesting claim.

Value

A structured, JSON-serializable list with models, ranking_by_aic, ranking_by_bic, reference, optional lrt, and notes.

Detect and advise on below-quantification (BLQ/BQL) handling

Description

Read-only, base-R inspection of a PK/PD dataset that recommends how (and whether) to handle below-quantification data. It is deliberately gated: it recommends censored-likelihood handling only when a real signal is present

• a censoring indicator column with censored rows, an LOQ/LLOQ column, or an explicit user_requested = TRUE - and otherwise recommends plain observe() with no bql. This prevents BLQ handling from being applied everywhere by default.

Usage

configure_blq_handling(
  data_path,
  dv_col = NULL,
  blq_col = NULL,
  loq_col = NULL,
  obs_name = "CObs",
  user_requested = FALSE,
  model_rds = NULL,
  apply = FALSE,
  project_dir = "."
)

Arguments

Details

The advice is staged, reflecting the engine constraint that observe(..., bql) (Beal's M3) and LL() disable Gaussian FO/FOCE: for early structural-model exploration with BLQ present, excluding BLQ under FOCE (M1) is an acceptable provisional step; the final/inferential model should use M3 with a likelihood method (Laplacian/QRPEM) when BLQ is material. M4 and other non-M3 schemes are only available via a custom LL() expression; LOQ/2 (M5) and zero-imputation (M7) are discouraged (sensitivity-only).

Value

A list with warranted, warrant_reason, blq_fraction, detected, loq_kind, mapping_token, method_guidance, recommended, a next_action directive (tool/args/reason; advisory text in reason), warnings, and (when apply) apply results. blq_fraction is NA_real_ when detected$dv_detected is FALSE (DV column not found); callers must not use bare ⁠if (blq_fraction > 0.05)⁠ because NA is falsy in ⁠if()⁠ without signalling unknown fraction.

Confirm a PML draft's structure matches the intended counts

Description

Engine-free structural confirmation: counts the fixef/ranef/error/ observe (and related) statements in a PML draft and, when an expected named list is supplied, reports any mismatches. Optionally attempts a textualmodel() build with a synthesized one-row dataset from a column-mapping spec and runs validate_nlme_model() for a deeper check; the build is best-effort and its failure is reported, not fatal.

Usage

confirm_pml_structure(
  code = NULL,
  expected = NULL,
  column_map = NULL,
  try_build = FALSE,
  path = NULL
)

Arguments

Value

A list: counts, expected, mismatches, and (when try_build) build.

Copy model object to iterate over base model

Description

Copies previously executed model into a new object and optionally accept all estimates returned from model execution. A new working directory is created and all files from base model are copied into it.

Usage

copyModel(model, acceptAllEffects = FALSE, modelName = "", workingDir = "")

Arguments

Value

Modified NlmePmlModel object

Examples

## Not run: 
model <- pkmodel(
  parameterization = "Clearance",
  numCompartments = 2,
  data = pkData,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc",
  workingDir = tempdir()
  )
 host <- hostParams(sharedDirectory = tempdir(),
                    parallelMethod = "None",
                    hostName = "local",
                    numCores = 1)
job <- fitmodel(model,
                numIterations = 3,
                hostPlatform = host)

finalModelVPC <- copyModel(model,
                           acceptAllEffects = TRUE,
                           modelName = "model_VPC",
                           workingDir = tempdir())

## End(Not run)

Sets style for a covariate/variable

Description

Sets style for a covariate/variable

Usage

covariateEffect(.Object, covariateName, parameterName) <- value

Arguments

Creates set of covariate effects

Description

Use to create set of covariate effects to be checked during Stepwise or Shotgun covariate search

Usage

covariateModel(model)

Arguments

Value

CovariateEffectModel class object

Examples

## Not run: 
# Define the model
model <- pkmodel(
  numCompartments = 2,
  data = pkData,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc",
  workingDir = tempdir()
)

# Add Gender covariate of type categorical
model <- addCovariate(model,
  covariate = "Gender",
  type = "Categorical",
  effect = c("V2", "Cl2"),
  levels = c(0, 1),
  labels = c("Female", "Male")
)

# Add Bodyweight covariate of type continuous
model <- addCovariate(model,
  covariate = "BodyWeight",
  type = "Continuous",
  direction = "Backward",
  center = "Mean",
  effect = c("V", "Cl")
)
covariateModel(model)

## End(Not run)

Return covariate names

Description

Use to return character vector of covariate names available in model object.

Usage

covariateNames(model)

Arguments

Value

Character vector of covariate names defined in model

Examples

model <- pkmodel(columnMap = FALSE,
                 workingDir = tempdir())
model <- addCovariate(model, covariate = "BW", effect = "V")
model <- addCovariate(model, covariate = "Age", effect = "Cl")

covariateNames(model)

Creates string from each covariate attribute

Description

Creates string from each covariate attribute

Usage

covariatePartsString(obj)

Arguments

Parse the model and get the list of terms

Description

Calls TDL5 to parse the model and get the list of terms

Usage

createModelInfo(model, ForceRun = FALSE)

Arguments

Value

List of model information

Examples

## Not run: 
  model <- pkmodel(columnMap = FALSE,
                   workingDir = tempdir())
  createModelInfo(model)

## End(Not run)

Create a metamodel file from an NlmePmlModel

Description

Creates (or overwrites) a textual metamodel file (e.g. .mmdl) from a supplied NlmePmlModel object. This is the inverse of read_mmdl().

Usage

create_metamodel_from_model(
  model,
  metamodelFile,
  datafile,
  author = "",
  engineParams = NULL,
  tableParams = NULL,
  absolutePaths = FALSE
)

Arguments

Value

Invisible model.

Examples

## Not run: 
tmp_data <- tempfile(fileext = ".csv")
write.csv(Certara.RsNLME::pkData, tmp_data, row.names = FALSE)

m <- Certara.RsNLME::pkmodel(data = Certara.RsNLME::pkData, workingDir = tempdir())
ep <- Certara.RsNLME::engineParams(m, method = "FOCE-ELS", numIterations = 200)

out_mmdl <- file.path(tempdir(), "example.mmdl")
Certara.RsNLME::create_metamodel_from_model(m, out_mmdl, datafile = tmp_data, engineParams = ep)

## End(Not run)

Use to create model object from parsed metamodel

Description

Legacy entry point retained for sister-package compatibility. New code should call read_mmdl() instead – it is the canonical user-facing importer and gains future improvements first.

Usage

create_model_from_metamodel(mmdlfile, directoryToRun)

Arguments

Details

Builds an NlmePmlModel (plus engine / simulation parameters) from a metamodel file. See Metamodel overview.

Value

a list with the resulted model class instance and engine parameters. If multiple ESTARGS/SIMARGS blocks are used, a list of estimation argument classes (NlmeEngineExtraParams()) and simulation argument classes (simParamsBlock) are returned.

See Also

read_mmdl(), run_metamodel()

Examples

 ## Not run: 
   ModelParamsList <-
     create_model_from_metamodel(
       mmdlfile = system.file("extdata/mmdlNoTime", "test.mmdl",
                              package = "Certara.RsNLME"),
       directoryToRun = tempdir())
 
## End(Not run)

Initialize input data for PK/PD model

Description

Used to initialize input data for PK/PD model

Usage

dataMapping(.Object, data)

Arguments

Value

Modified NlmePmlModel object

See Also

colMapping

Examples

model <- pkmodel(columnMap = FALSE,
                 workingDir = tempdir())

model <- dataMapping(model, pkData)

Deletes a secondary parameter from the model

Description

Deletes a secondary parameter from the model

Usage

deleteSecondary(.Object, name)

## S4 method for signature 'NlmePmlModel'
deleteSecondary(.Object, name)

Arguments

Value

Depends on the specific methods

Returns the 'NlmePmlModel' object with the secondary parameter removed.

Functions

• deleteSecondary(NlmePmlModel): Method for the 'NlmePmlModel' class

  This method deletes a secondary parameter from the NlmePmlModel object. It searches for the parameter by name, and if it is found, it removes it from the object and updates the PML model.

Return dose names

Description

Use to return character vector of dose point names in model object.

Usage

doseNames(model)

Arguments

Value

Character vector of dose names defined in model

Examples

model <- pkmodel(columnMap = FALSE,
                 workingDir = tempdir())

doses <- doseNames(model)

Draft PML from a NONMEM control stream

Description

Translates a conservative common-model subset of a NONMEM control stream into a PML draft and returns a translation report with per-area confidence. Built on analyze_nonmem_control(): standard ADVAN/TRANS structures, deterministic ⁠$THETA⁠/⁠$OMEGA⁠/⁠$SIGMA⁠ conversions (including the ⁠$SIGMA⁠ variance to error() standard-deviation square-root), recognized ⁠$PK⁠/⁠$ERROR⁠ idioms, and an ⁠$INPUT⁠-derived column-mapping spec. Anything outside the subset is preserved as a needs_review item rather than guessed. v1 does not rewrite the dataset.

Usage

draft_pml_from_nonmem(control_text = NULL, path = NULL)

Arguments

Value

A list: ok, pml (draft text), recommended_path, builtin_constructor, translation_report (summary, per-area confidence, deterministic, needs_review, data_requirements, column_mapping_spec, estimation_notes), and the underlying analysis.

Directly edit PML text in model object

Description

Allows user to edit PML text in model object using internal text editor and return a new textual model containing the edited PML statements.

Usage

editModel(.Object)

Arguments

Value

Modified NlmePmlModel object

Examples

model <- pkmodel(columnMap = FALSE,
                 workingDir = tempdir())

if (FALSE) {
  # will open an additional window with the model text:
  newModel <- editModel(model)
}

Create an Emax or Imax model

Description

Use to create an Emax or Imax model

Usage

emaxmodel(
  isPopulation = TRUE,
  checkBaseline = FALSE,
  checkFractional = FALSE,
  checkInhibitory = FALSE,
  checkSigmoid = FALSE,
  data = NULL,
  columnMap = TRUE,
  modelName = "",
  workingDir = "",
  ...
)

Arguments

Value

NlmePmlModel object

Column mapping

Note that quoted and unquoted column names are supported. Please see colMapping.

Examples

model <- emaxmodel(data = pkpdData, ID = "ID", C = "CObs", EObs = "EObs")

model <- emaxmodel(
  checkBaseline = TRUE,
  checkFractional = TRUE,
  checkInhibitory = TRUE,
  data = pkpdData,
  ID = "ID",
  C = "CObs",
  EObs = "EObs"
)

# View PML Code
print(model)

Emax model mapping parameters

Description

Emax model mapping parameters

Usage

emaxmodel_MappingParameters(ID = NULL, C = NULL, EObs = NULL)

Arguments

Main function to specify engine parameters

Description

Use to define engine parameters for model execution.

Usage

engineParams(
  model,
  sort = NULL,
  ODE = "MatrixExponent",
  rtolODE = 1e-06,
  atolODE = 1e-06,
  maxStepsODE = 50000,
  numIterations = 1000,
  method = NULL,
  stdErr = NULL,
  isCentralDiffStdErr = TRUE,
  stepSizeStdErr = NULL,
  conditionNumber = c("CovarianceFixef", "CorrelationFixef", "CovarianceFull",
    "CorrelationFull"),
  logTransform = NULL,
  numIntegratePtsAGQ = 1,
  numIterNonParametric = 0,
  allowSyntheticGradient = FALSE,
  fastOptimization = FALSE,
  numIterMAPNP = 0,
  numRepPCWRES = 0,
  stepSizeLinearize = 0.002,
  numDigitLaplacian = 7,
  numDigitBlup = 13,
  gradTolOuter = 2e-04,
  stepTolOuter = 1e-04,
  gradTolInner = 1.71e-05,
  stepTolInner = 7.07e-08,
  refDeltaLagl = 0.001,
  mapAssist = 0,
  iSample = 300,
  iAcceptRatio = 0.1,
  impDist = "Normal",
  tDOF = 4,
  numSampleSIR = 10,
  numBurnIn = 0,
  freezeOmega = FALSE,
  MCPEM = FALSE,
  runAllIterations = FALSE,
  scramble = "Owen",
  emTolType = 0,
  emConvLen = 10,
  emConvCritVal = 5,
  stepSizePartialDeriv = 1e-05,
  numTimeStepPartialDeriv = 20
)

Arguments

Details

Both "DVERK" and "DOPRI5" are non-stiff solvers. "AutoDetect" represents LSODA solver implemenation, which solves the initial value problem for stiff or nonstiff systems of first order ordinary differential equations. "Stiff" is a LSODE (Livermore solver). It is best suited for stiff problems. "MatrixExponent" is a matrix exponential solver.

For the QRPEM method, the impDist parameter controls the importance sampling distribution. The ximpsampdof slot in the internal NlmeEngineExtraParams object is set based on impDist as follows:

• "Normal": ximpsampdof = 0

• "DoubleExponential": ximpsampdof = 1

• "Direct": ximpsampdof = 2

• "T": ximpsampdof is set to the value of tDOF.

• "Mixture-2": ximpsampdof = -2

• "Mixture-3": ximpsampdof = -3

The conditionNumber argument controls both the scope (which parameters) and the basis (covariance vs. correlation) used to derive the reported eigenvalues and condition in the engine's out.txt. Let C be the variance-covariance matrix of the selected parameters, as produced by the standard-error step (Hessian, sandwich, or Fisher-score, selected by stdErr); its diagonal entries are the squared standard errors of the estimates and its off-diagonals are their estimated covariances.

Scope (which parameters make up C):

• "...Fixef": only the estimated fixed effects.

• "...Full": all estimated population parameters (fixed effects, standard deviations of residual errors, elements of variance/covariance matrix of the random effects).

Basis (how C is used):

• "Covariance..." (default scope is Fixef): eigenvalues are those of C directly, and condition = sqrt(lambda_max / lambda_min), where lambda_min and lambda_max are the smallest and largest strictly positive eigenvalues, respectively. This value is scale-dependent: parameters spanning many orders of magnitude (e.g. typical PK fixed effects) inflate it even when the fit is well-conditioned in correlation terms.

• "Correlation...": C is first normalised to the correlation matrix R = D^(-1/2) * C * D^(-1/2), where D = diag(C) (the parameter variances); reported eigenvalues are those of R and condition = lambda_max / lambda_min. The result is scale-invariant and reflects only the correlation structure of the estimates. If any diagonal of C is non-positive or non-finite the correlation matrix is undefined and both lines are suppressed.

Only "CorrelationFull" matches NONMEM's condition-number scope (all estimated THETA/OMEGA/SIGMA, correlation basis); use it for direct comparison with NONMEM output. The other three options are not NONMEM-comparable.

Value

List of engine parameters to be used during fitting or simulation

Return extra dose lines

Description

Use to return extra dose lines for model object

Usage

extraDoseLines(model)

Arguments

Value

List of extra dose information

Examples

data <- pkData
data$II <- 24
data$ADDL <- 1

model <-
pkmodel(
  parameterization = "Clearance",
  numCompartments = 2,
  data = data,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc",
  workingDir = tempdir())
addDoseCycle(
  model,
  name = "A1",
  amount = 30000,
  II = 24,
  type = "ADDL",
  colName = "ADDL")

extraDoseLines(model)

Return extra dose names

Description

Use to return extra dose names for model object

Usage

extraDoseNames(model)

Arguments

Value

Character vector of extra dose names

Examples

data <- pkData
data$II <- 24
data$ADDL <- 1

model <-
pkmodel(
  parameterization = "Clearance",
  numCompartments = 2,
  data = data,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc",
  workingDir = tempdir())
addDoseCycle(
  model,
  name = "A1",
  amount = 30000,
  II = 24,
  type = "ADDL",
  colName = "ADDL")

extraDoseNames(model)

extract files used for powershell script

Description

Use for extraction of the NLME files from mmdl file.

Usage

extract_mmdl(
  mmdlfile,
  directoryToExtract,
  dataFileName = "data1.txt",
  mdlOutput = "test.mdl",
  cols1Output = "cols1.txt",
  nlmeargsOutput = "nlmeargs.txt"
)

Arguments

Details

mdlOutput, dataFileName, cols1Output, nlmeargsOutput files are extracted into the folders, the names of the folders are built as ⁠{Number of estimation/simulation block in metamodel}⁠- ⁠{'est' for estimation block/'sim' for simulation block}⁠. All estimation blocks are going first irrespective of the simulation blocks presence, all simulation blocks are going next.

Value

The results of read_mmdl() run are returned.

See Also

read_mmdl()

Examples

## Not run: 
# path to metamodel should be specified, all other arguments set to default
extract_mmdl(system.file("extdata/mmdlNoTime", "test.mmdl",
                              package = "Certara.RsNLME"),
             directoryToExtract = tempdir())

## End(Not run)

Executes an NLME simple estimation

Description

Executes an NLME simple estimation

Usage

fitmodel(
  model,
  hostPlatform = NULL,
  params,
  simpleTables,
  runInBackground = FALSE,
  filesToReturn = "*",
  ...,
  saveResult = TRUE
)

Arguments

Value

if runInBackground is FALSE, a list with main resulted dataframes is returned:

• Overall

• ConvergenceData

• residuals

• Secondary

• StrCovariate - if continuous covariates presented

• StrCovariateCat - if categorical covariates presented

• theta

• posthoc table

• posthocStacked table

• Requested tables

nlme7engine.log textual output is returned and loaded with the main information related to fitting. dmp.txt structure with the results of fitting (including LL by subject information) is returned and loaded. These 2 files are returned and loaded irrespective of filesToReturn argument value.

For individual models, additional dataframe with partial derivatives is returned:

• ParDer

For population models and the method specified is NOT Naive-Pooled, additional dataframes are returned:

• omega

• Eta

• EtaStacked

• EtaEta

• EtaCov

• EtaCovariate - if continuous covariates presented

• EtaCovariateCat - if categorical covariates presented

• bluptable.dat

If standard error computation was requested and it was successful, additional dataframes are returned:

• thetaCorrelation

• thetaCovariance

• Covariance

• omega_stderr

If nonparametric method was requested (numIterNonParametric > 0) and the method specified in engineParams is NOT Naive-Pooled, additional dataframes are returned:

• nonParSupportResult

• nonParStackedResult

• nonParEtaResult

• nonParOverallResult

if runInBackground is TRUE, a FitNlmeJob object is returned. Pass it to collectJob() when the engine has finished to materialise the same list described above.

filesToReturn with Certara.Xpose.NLME

If filesToReturn is used and "ConvergenceData.csv" and "residuals.csv" are not in the patterns, these files won't be returned and loaded. These files are essential for Certara.Xpose.NLME::xposeNlmeModel and Certara.Xpose.NLME::xposeNlme functions. This makes impossible to use the resulted object in Certara.Xpose.NLME functions.

Non-loaded but returned files

The non-loaded but returned files in the model working directory are:

• err1.txt - concatenated for all runs detailed logs for all steps of optimization,

• out.txt - general pivoted information about results,

• doses.csv - information about doses given for all subjects,

• iniest.csv - information about initial estimates

Self-describing run context

The returned list also carries five run-context elements that make the object self-describing:

• model - the input NlmePmlModel as it was at the start of the run (with @modelInfo@workingDir pointing at the artifacts).

• params - the resolved NlmeEngineExtraParams actually used.

• runMode - the string "fitmodel".

• runTime - a list with start, end, and elapsed wall-clock times measured around the engine call. This is distinct from the engine-reported CPU time in nlme7engine.log.

• RsNLMEVersion - the package version that produced the result.

No host, machine name, user name, password, or private key path is ever placed in the returned value or in the saved file.

See Also

tableParams, hostParams, engineParams, collectJob

Examples

## Not run: 

 # Define the host
 host <- hostParams(sharedDirectory = tempdir(),
                    parallelMethod = "None",
                    hostName = "local",
                    numCores = 1)
 # Define the model
 model <- pkmodel(numComp = 2,
                  absorption = "FirstOrder",
                  ID = "Subject",
                  Time = "Act_Time",
                  CObs = "Conc",
                  Aa = "Amount",
                  data = pkData,
                  modelName = "PkModel",
                  workingDir = tempdir())

 Table01 <- tableParams(name = "SimTableObs.csv",
                        timesList = "0,1,2,4,4.9,55.1,56,57,59,60",
                        variablesList = "C, CObs",
                        timeAfterDose = FALSE,
                        forSimulation = FALSE)

 # Update fixed effects
 model <- fixedEffect(model,
                     effect = c("tvV", "tvCl", "tvV2", "tvCl2"),
                     value = c(16, 41, 7, 14))

 # Define the engine parameters
 params <- engineParams(model)
 # Fit model
 res <- fitmodel(model = model,
                 hostPlatform = host,
                 params = params,
                 simpleTables = Table01)

## End(Not run)

Specifies the initial values, lower bounds, upper bounds, and units for fixed effects in a model

Description

Built-in-model structural setter for fixed-effect (theta) initials, bounds, freeze status, and units. Use during model construction when units are needed, or when configuring several thetas together as part of setup. Cannot be used on textual or edited models; for pipe-friendly value, bounds, and freeze edits on built-in or textual models, see update_Thetas() (textual models also support enable; neither API sets units except this one).

Usage

fixedEffect(
  .Object,
  effect,
  value = NULL,
  lowerBound = NULL,
  upperBound = NULL,
  isFrozen = NULL,
  unit = NULL
)

Arguments

Value

Modified NlmePmlModel object

See Also

update_Thetas()

Examples

model <- pkmodel(
  numCompartments = 2,
  data = pkData,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc",
  modelName = "TwCpt_IVBolus_FOCE_ELS",
  workingDir = tempdir()
  )

 # View initial/current fixed effect values
 initFixedEffects(model)

model <-
fixedEffect(
  model,
  effect = c("tvV", "tvCl", "tvV2", "tvCl2"),
  value = c(15, 5, 40, 15)
  )

Generates PML statements based on the current model

Description

Generates PML statements based on the current model

Usage

generatePML(.Object)

Arguments

Return random effect names in model

Description

Use to return character vector of random effect names (if available) in model object

Usage

getRandomEffectNames(model)

Arguments

Value

Characters vector of random effect names

Examples

model <- pkmodel(columnMap = FALSE,
                 workingDir = tempdir())
getRandomEffectNames(model)

Retrieve model and fitmodel-style results for a selected covariate search scenario.

Description

Dispatches on the type of x to resolve an archived covariate-search run folder and scenario, then loads the base model and run context from rsnlme_run.rds and reconstructs the scenario-specific model. Use listSCMRuns to enumerate scenarios in one or more such folders.

Usage

getSCMResults(x, scenario = NULL, enableIDs = NULL)

Arguments

Details

When x is a row-subset of a search-result data frame and the caller does not specify a scenario explicitly, selection is restricted to the subset: if the archive's flagged best scenario is filtered out, the row with the lowest value of the search's selection criterion (-2LL, AIC, or BIC; recorded for stepwise searches and always -2LL for shotgun) within the subset is returned. For stepwise this need not match the engine's chosen winner, because the user has explicitly excluded that row by subsetting.

Value

An scmResult object (list-like, with a custom print method) containing three elements:

model

The reconstructed NlmePmlModel for the scenario, with accepted parameter estimates.

fitmodelOutput

A list compatible with fitmodel() output. In addition to the file-derived elements, this list carries the self-describing fields: model (the reconstructed scenario model), params (resolved NlmeEngineExtraParams), runMode ("stepwise" or "shotgun"), runTime (wall-clock list), and RsNLMEVersion.

scenarioInfo

A single-row data frame with scenario metadata.

Archived run folders

Archived folders are created when shotgunSearch() or stepwiseSearch() is run with archiveResults = TRUE. During the engine run, NLME8 writes scenario outputs under a temporary SCM_<runId>/ directory in the model working directory (runId is a wall-clock timestamp, optionally suffixed with runLabel). After the engine finishes, collectJob() materialises the search result and the package renames that tree into a durable folder named stepwise_<runId> or shotgun_<runId> (on remote hosts the bundle SCM_<runId>.tar.gz is extracted first, then the bundle and any loose SCM_<runId>/ copy are removed). The final folder holds scenario_index.csv, per-scenario subfolders, Overall.csv, optional stepwise logs, and rsnlme_run.rds.

See Also

shotgunSearch, stepwiseSearch, summary(), print(), listSCMRuns

Return theta names and values

Description

Returns named character vector of theta values by parsing PML fixed effect statements

Usage

getThetas(model)

Arguments

Value

Character vector of theta names defined in model

Examples

## Not run: 
model <- emaxmodel(
  checkBaseline = TRUE,
  checkFractional = TRUE,
  checkInhibitory = TRUE,
  data = pkpdData,
  ID = "ID",
  C = "CObs",
  EObs = "EObs"
)
getThetas(model)

## End(Not run)

Get the structured fit summary for a job

Description

Lightweight companion to collect_nlme_job() that returns just the parsed numeric summary (fit_summary) plus fit_health, for any completed fit - including .mmdl/run_metamodel jobs started by start_nlme_fit() that have no fit.rds. In that case the estimates, omega diagonal, and shrinkage are parsed from the engine artifacts (Overall.csv, theta.csv, omega.csv) so the agent reads numbers rather than hand-parsing CSVs. fit_summary$estimates_source reports whether the values came from fit.rds or the artifacts.

Usage

get_fit_summary(job_id, project_dir = ".", full_omega = FALSE)

Arguments

Details

By default only the omega diagonal and shrinkage are surfaced. Set full_omega = TRUE to also return the full symmetric omega matrix as fit_summary$random_effects_matrix (with random_effects_eta_names); this is what block random-effects models such as FREM need for covariate post-processing (e.g. beta = Omega_pc %*% solve(Omega_cc)).

Value

A list with job_id, state, job_kind, run_dir, fit_health, fit_summary, and artifact_integrity. fit_summary additionally carries parameter_table (per-parameter estimate/SE/%RSE/CI/shrinkage plus se_missing and boundary_status), a single uncertainty_status, and a diagnosis block that proposes - never launches - a bootstrap when a converged fit has missing standard errors and boundary evidence. When artifact_integrity$status is "violation" the directory was overwritten after this fit was recorded and fit_summary$next_step says so. For an unknown id, state == "not_found".

See Also

collect_nlme_job(), get_nlme_job_status()

Get the status of an NLME job

Description

The lifecycle field is state (not status): one of running, succeeded, failed, dead, unknown, or not_found. The artifacts directory is artifact_dir (not artifacts_dir) and equals file.path(run_dir, "artifacts"). This is a single-shot progress snapshot - it reads the latest status once and returns immediately:

Usage

get_nlme_job_status(
  job_id,
  project_dir = ".",
  wait_seconds = 0,
  poll_interval = 2
)

Arguments

Details

st <- get_nlme_job_status(job_id, project_dir)
artifact_dir <- st$artifact_dir

To watch a long fit without burning agent turns, prefer wait_for_nlme_job(), which blocks server-side using the launch-configured watch budget. The wait_seconds/poll_interval arguments here are retained for backward compatibility and advanced manual R use; wait_for_nlme_job() is the agent-facing watcher.

Value

A list with job_id, state, timing (started/finished/ exit_code), pid, run_dir, artifact_dir, live progress, and (for a terminal job) fit_health. This is the raw snapshot primitive; the agent-facing next_action directive is added by wait_for_nlme_job().

See Also

wait_for_nlme_job() for the preferred long-job watcher.

Project workflow status: state, blocking issues, and next tools

Description

Read-only aggregation of the artifacts a project already produces - the saved analysis plan, the job registry (jobs.jsonl), and the covariate-search directory - into one snapshot so an agent can see where it is and what to do next without inferring from scattered files. Nothing is written.

Usage

get_project_workflow_status(project_dir = ".")

Arguments

Value

A list with analysis_plan, jobs, covariate_search, vpc, qualification (sequential-LRT session summary; see list_sequential_lrt_sessions()), data_inspection, blocking_issues, and recommended_next_tools.

Read the latest saved PopPK analysis plan

Description

Read-only companion to save_analysis_plan(): returns the latest versioned plan persisted under ⁠<project_dir>/analysis-plan/⁠ so downstream tools and agents reference the plan by its stable handle instead of re-reading files by hand. When no plan has been saved, returns saved = FALSE with a next_action directive (blocking) pointing at save_analysis_plan().

Usage

get_saved_analysis_plan(project_dir = ".")

Arguments

Value

A list with saved and, when a plan exists, analysis_plan_id, analysis_plan_version, intended_use, content_sha256, created, latest_path, open_critical_issues, and the full plan body.

Read-only sequential-LRT session status (no state transition)

Description

Unlike advance_sequential_lrt(), this never launches a fit, decides a phase winner, or mutates the persisted session; it only attaches a live state peek (via a single-shot, non-blocking get_nlme_job_status()) for the anchor or any running candidate jobs.

Usage

get_sequential_lrt_status(session_id, project_dir = ".")

Arguments

Value

The same status shape as advance_sequential_lrt(), with a live_state field added to operations[[i]] while status == "running" (and top-level anchor_live_state while anchoring).

Create an NLME Parallel Host Configuration

Description

This helper function simplifies the creation and configuration of an NlmeParallelHost object, which defines the environment for running NLME jobs.

Usage

hostParams(
  sharedDirectory,
  installationDirectory = NULL,
  hostName = Sys.info()[["nodename"]],
  machineName = "127.0.0.1",
  hostType = Sys.info()[["sysname"]],
  numCores = 4,
  parallelMethod = "LOCAL_MPI",
  mpiCoresPerJob = NA_integer_,
  userName = "",
  privateKeyFile = NULL,
  userPassword = "",
  scriptPath = "",
  rLocation = "",
  isLocal = TRUE,
  gridQueue = "",
  gridWalltime = NA_integer_,
  gridMemory = "",
  gridJobNamePrefix = "",
  gridResourceExtra = ""
)

Arguments

Details

Remote Windows hosts are not supported. Background execution (runInBackground = TRUE on fitmodel() and the other job wrappers) is available only on Linux hosts (local or remote); on Windows hosts use runInBackground = FALSE.

Value

An NlmeParallelHost object configured with the specified parameters.

Examples

host <- hostParams(sharedDirectory = tempdir(),
                   parallelMethod = "LOCAL_MPI",
                   hostName = "Local",
                   numCores = 4)

# Local hybrid: run several models concurrently, each with its own MPI ranks.
# numCores = 10 with mpiCoresPerJob = 2 fits up to 5 models at a time,
# 2 MPI ranks each.
hybridHost <- hostParams(sharedDirectory = tempdir(),
                         parallelMethod = "Multicore_MPI",
                         hostName = "LocalHybrid",
                         numCores = 10,
                         mpiCoresPerJob = 2)

# Omit mpiCoresPerJob to let NLME8 size the per-job rank from the batch.
autoHybridHost <- hostParams(sharedDirectory = tempdir(),
                             parallelMethod = "Multicore_MPI",
                             hostName = "LocalHybridAuto",
                             numCores = 10)

# Grid host routing long batch work to a non-interactive queue, with an
# informative job name shown in qstat/squeue.
gridHost <- hostParams(sharedDirectory = "~",
                       parallelMethod = "SGE_MPI",
                       hostName = "sge",
                       numCores = 32,
                       gridQueue = "bg.q",
                       gridMemory = "16G",
                       gridJobNamePrefix = "BOOT_prod",
                       isLocal = FALSE)

Impute missing covariate values

Description

Replaces user-defined sentinel values (default -99) in covariate columns with values that the NLME engine can consume, leaving the PML model code untouched. Within a reset block, masked rows are left as NA so the engine performs row-level propagation via fcovariate() / covariate() / interpolate(); only blocks (and subjects) where the engine has nothing to propagate receive an externally-computed fallback value.

Usage

imputeMissingCovariates(
  model,
  data = NULL,
  missingToken = c(-99),
  method = c("subject", "population"),
  continuousFn = stats::median,
  categoricalFn = imputeMode,
  centralValueWeighting = c("subject", "row"),
  stratifyBy = NULL,
  minStratumFraction = 0.1,
  keepOriginal = TRUE,
  logFile = NULL
)

Arguments

Details

The function returns a modified clone of the input NlmePmlModel (with ⁠@inputData⁠ replaced by the imputed data.frame), along with the imputed data, a traceability summary, and a log file. All other model slots (⁠@columnMapping⁠, ⁠@covariateList⁠, ⁠@statements⁠, ⁠@hasResetInfo⁠, ⁠@resetInfo⁠, etc.) are preserved verbatim so custom mappings like WT -> BodyWeight survive the round-trip.

Imputation cascade (method = "subject", default). The NLME engine propagates covariate values within a reset block but cannot carry them across blocks, so the cascade classifies each (subject, reset block):

1. Block has at least one non-missing value – masked rows are left as NA (source "engine"). The engine fills them via fcovariate() / covariate() / interpolate().

2. Block is fully missing but the subject has non-missing values in other blocks – the masked rows are filled with the subject aggregate computed by continuousFn / categoricalFn over the subject's non-missing values across all blocks (source "propagated").

3. Subject is fully missing across every block – the masked rows are filled with the population (or stratum) central value (source "population" or "stratum").

method = "population" skips subject-level lookups and replaces every masked row with the population (or stratum) central value.

Note the two methods differ in their effect on covariate centering. method = "subject" leaves masked rows as NA, and the engine excludes missing rows when it computes mean() / median() centering values, so centering is unaffected. method = "population" writes a value into every masked row, and those values do take part in centering.

Value

A list with elements:

• model – clone of input NlmePmlModel with ⁠@inputData⁠ replaced by the imputed data.frame.

• data – imputed data.frame (same object as result$model@inputData).

• summary – data.frame with one row per (covariate, column, imputation_source, stratum) combination. Columns: covariate, column, type, imputation_source, stratum, imputed_value, n_imputed, n_subjects_affected. imputed_value is NA for "engine" (no value written; the engine fills at run time), a truncated list of distinct per-subject donors for "propagated", and the pooled central value for "stratum" / "population".

• logFile – absolute path of the written log file.

Examples

## Not run: 
  model <- pkmodel(...)
  model <- addCovariate(model, "WT", type = "Continuous")
  model <- colMapping(model, c(WT = "BodyWeight"))

  result <- imputeMissingCovariates(model)
  model <- result$model
  fit <- fitmodel(model)
  print(result$summary)

## End(Not run)

Modal value with deterministic tie-break (default categorical aggregator)

Description

Returns the most frequent value in x. Used as the built-in default for imputeMissingCovariates()'s categoricalFn argument, and exposed publicly so callers can plug it into their own workflows or compose it with other rules.

Usage

imputeMode(x, missingToken = NULL)

Arguments

Details

Properties:

• Deterministic tie-break. When two or more values tie for the highest frequency, the one that appears first in x wins. This makes the result stable across runs and independent of locale- sensitive ordering inside table().

• Factor-preserving. If x is a factor, the return value is a factor with the same levels(x). Plain character / numeric vectors return a length-1 value of the same atomic type.

• NA-tolerant. NA entries are ignored when computing the mode. If every entry is NA the function errors.

• Optional token avoidance. When missingToken is supplied, values matching any element of it are excluded from the candidate set. imputeMissingCovariates() masks the input pool up-front so this is normally a no-op there; the parameter is useful when calling imputeMode() standalone on a raw vector that may still contain sentinels.

Value

A length-1 value of the same atomic type as x (factor for factor input).

Examples

imputeMode(c("M", "F", "M", "F"))                       # "M" (ties: first wins)
imputeMode(factor(c("M", "F", "M"), levels = c("F","M"))) # factor "M"
imputeMode(c(70, 70, 65, -99), missingToken = -99)        # 70

Attach input data to a model and initialize its column mapping

Description

⁠initColMapping<-⁠ attaches an input dataset to an NlmePmlModel and builds its column mapping in one step. Use it when the data arrives separately from the model - for example after read_mmdl returned a model with @inputData = NULL because the ## DATA file was missing. To edit an existing mapping instead (the data is already attached), use colMapping(model) <- c(...).

Usage

initColMapping(.Object) <- value

## S4 replacement method for signature 'NlmePmlModel'
initColMapping(.Object) <- value

Arguments

Value

The updated NlmePmlModel with @inputData and @columnMapping set.

See Also

colMapping, read_mmdl

Examples

## Not run: 
res <- read_mmdl("model.mmdl")     # ## DATA missing -> @inputData is NULL
initColMapping(res$model) <- myData

## End(Not run)

Display/Set initial estimates for fixed effects

Description

Display/Set initial estimates for fixed effects

Usage

initFixedEffects(.Object)

## S4 method for signature 'NlmePmlModel'
initFixedEffects(.Object)

initFixedEffects(.Object) <- value

## S4 replacement method for signature 'NlmePmlModel'
initFixedEffects(.Object) <- value

Arguments

Value

Named numeric vector of fixed effects estimates

See Also

fixedEffect

Examples

model <- pkmodel(
  numCompartments = 2,
  data = pkData,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc",
  modelName = "TwCpt_IVBolus_FOCE_ELS",
  workingDir = tempdir()
  )

# View initial/current fixed effect values
 initFixedEffects(model)

# May also use as a 'replacement function' to set the values
initFixedEffects(model) <- c(tvV = 15, tvCl = 5, tvV2 = 40, tvCl2 = 15)

Inspect a built NlmePmlModel

Description

Read-only introspection of a model saved as .rds: the current column mapping (with any unmapped model terms called out), dose points, the additional-dose / steady-state / MDV flags wired via addADDL()/addSteadyState()/addMDV(), declared covariates, structural parameters, and random-effect statements. Use it to see what a model still needs before fitting (e.g. an observation term mapped to "?", or whether an ADDL column was actually registered) instead of hand-parsing the object.

Usage

inspect_nlme_model(model_rds)

Arguments

Value

A list with is_textual, model_type, is_population, structural_params, column_mapping (term/column/type rows), unmapped_terms, dose_points, extra_dose_defs, covariates, random_effects, and mapping_complete.

Inspect a PK dataset (read-only)

Description

Synchronous, base-R, read-only exploratory summary of a PK/PD dataset so an agent can assess data adequacy through MCP instead of ad-hoc Python/shell R. Never writes or modifies the dataset. A tiny last-inspect stamp may be written under the pinned project's ⁠.certara-mcp/⁠ so get_project_workflow_status() can report that inspection ran. Data cleaning that writes output is a separate, explicit step (see prepare_pk_data.R).

Usage

inspect_pk_dataset(
  data_path,
  id_col = NULL,
  time_col = NULL,
  dv_col = NULL,
  amt_col = NULL,
  rate_col = NULL,
  mdv_col = NULL,
  dvid_col = NULL,
  na_strings = c("NA", ".", ""),
  max_dup_report = 20
)

Arguments

Details

Auto-detects the standard columns (ID/time/DV/amt/rate/MDV/DVID) by common names; override any of them with the corresponding argument. Reports subject/observation/dose counts, MDV and DVID breakdowns, a dose-regimen summary, observation ranges, per-covariate distributions, duplicate ⁠(ID, time)⁠ records, and a suggested column_map for a pkmodel fit (oral/first-order when dose rates are all -1/-2, otherwise IV bolus). When NONMEM-style C/BLQ flag columns are present a nonmem_filter_hints block points at the safe %in% filter idiom. When subject-constant continuous covariates are present, it also returns a read-only frem_suggestion pointing at the FREM KB recipe (it does not prepare data).

Value

A structured, JSON-serializable list.

Inspect a textual PML model without fitting

Description

Builds an NlmePmlModel from a textual PML .mdl file and a CSV dataset with textualmodel(), then returns a read-only summary - no engine fit, no output files. The headline field is covariate_effect_names (from listCovariateEffectNames()): the effects, in canonical order, that you turn into NlmeScenario() scenarios for sortfit(). Also returns the structural projection from inspect_nlme_model() (column mapping with any UNMAPPED terms, dose points, covariates, structural/random parameters) and the validate_nlme_model() verdict (ready_for_fit).

Usage

inspect_textual_model(mdl_path, data_path, mappings_json = NULL, n_rows = NULL)

Arguments

Details

Building a textual model and listing its covariate effects is pure R, so this needs no NLME engine license. Use it before authoring a sortfit batch to discover the covariate effects and confirm the data attaches and maps.

Value

A list with covariate_effect_names, the inspect_nlme_model() fields, and a validation block, or an error string on failure.

Interpret parameter estimates against literature

Description

Builds a reconciliation scaffold (units, parameterization, allometry, population) and a citation policy, then instructs the agent (or the MCP host, when fetch = TRUE) to retrieve literature with its own web tools. This provider does not perform the retrieval itself.

Usage

interpret_parameters(
  estimates = NULL,
  job_id = NULL,
  compound_class = NULL,
  sources = NULL,
  project_dir = ".",
  fetch = FALSE
)

Arguments

Details

Interpretation is heuristic context, never uncited "established" fact: every literature value must carry source (URL/DOI), unit, and parameterization.

Value

A structured list describing how to compare estimates against literature, plus a citation reminder.

Get or set whether a model is a population model

Description

isPopulation() reports the population / individual mode of an NlmePmlModel. The replacement form isPopulation(model) <- value flips that mode and keeps the column mapping consistent: switching to individual removes the id mapping entry (the individual write path always injects a dummy id), and switching to population re-adds an unmapped id entry that is then auto-mapped against any matching data column name.

Usage

isPopulation(.Object)

## S4 method for signature 'NlmePmlModel'
isPopulation(.Object)

isPopulation(.Object) <- value

## S4 replacement method for signature 'NlmePmlModel'
isPopulation(.Object) <- value

Arguments

Details

Random effects and author-written PML are left untouched; the engine decides how to execute a model whose PML disagrees with the mode.

Value

For the getter, a length-1 logical. For the setter, the updated NlmePmlModel.

See Also

colMapping, textualmodel, pkmodel

Examples

## Not run: 
model <- pkmodel(columnMap = FALSE, data = pkData)
isPopulation(model)
isPopulation(model) <- FALSE

## End(Not run)

Vectorised numeric-token test for covariate values

Description

Returns a logical vector of the same length as x indicating whether each element is a numeric literal. Provides column-class fast paths so that already-numeric, integer, logical, or factor columns avoid the regex call.

Usage

is_cov_numeric_value(x)

Arguments

Value

Logical vector.

Vectorised test for values the NLME engine reads as missing

Description

Mirrors the engine's own tokenisation so R-side validators agree with what the fit will actually see. A covariate cell becomes the internal missing sentinel when it is

• empty or whitespace-only, or

• a bare . – note .5 is a number, so the test is an exact match on . rather than a prefix test, or

• NA in any letter case (NA, na, Na, nA).

A real R NA is included as well: it is written to the data file as the bare token NA, which the engine also reads as missing.

Usage

is_engine_missing_token(x)

Arguments

Details

Undeclared category labels also end up missing, but that needs the covariate's declared labels to detect and is handled by validate_cov_data_coverage(), not here.

Value

Logical vector, same length as x.

Create linear model

Description

Use to create a constant, linear, or quadratic PD model

Usage

linearmodel(
  isPopulation = TRUE,
  type = "Constant",
  data = NULL,
  columnMap = TRUE,
  modelName = "",
  workingDir = "",
  ...
)

Arguments

Value

NlmePmlModel object

Column mapping

Note that quoted and unquoted column names are supported. Please see colMapping.

Examples

model <- linearmodel(type = "Linear", data = pkpdData, ID = "ID", C = "CObs", EObs = "EObs")

# View PML Code
print(model)

Linear model mapping parameters

Description

Linear model mapping parameters

Usage

linearmodel_MappingParameters(ID = NULL, C = NULL, EObs = NULL)

Arguments

Lists covariate effect names in the model

Description

This function lists the names of covariate effects in a provided pharmacokinetic/pharmacodynamic (PK/PD) model.

Usage

listCovariateEffectNames(.Object)

## S4 method for signature 'NlmePmlModel'
listCovariateEffectNames(.Object)

Arguments

Value

A vector of character strings containing the names of the covariate effects in the model.

Examples

model <- pkmodel(
  numCompartments = 2,
  data = pkData,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc",
  workingDir = tempdir()
)
model <- addCovariate(model,
  covariate = "Gender",
  type = "Categorical",
  effect = c("V2", "Cl2"),
  levels = c(0, 1),
  labels = c("Female", "Male")
)
listCovariateEffectNames(model)

List archived covariate search scenarios.

Description

Dispatches on the type of x to discover archived covariate-search run folders and returns one row per scenario, sorted by timestamp descending (latest first). This function discovers only stepwise_* and shotgun_* folders, not transient SCM_* directories.

Usage

listSCMRuns(x)

Arguments

Value

A data frame with one row per scenario. Columns: searchType, SCMFolder (path to the archived run folder; name kept for compatibility), runFolder, Scenario, enableFlags, status, timestamp, runId, overallFile, stepwiseFile. Returns an empty data frame if no runs are found.

Archived run folders

Archived folders are created when shotgunSearch() or stepwiseSearch() is run with archiveResults = TRUE. During the engine run, NLME8 writes scenario outputs under a temporary SCM_<runId>/ directory in the model working directory (runId is a wall-clock timestamp, optionally suffixed with runLabel). After the engine finishes, collectJob() materialises the search result and the package renames that tree into a durable folder named stepwise_<runId> or shotgun_<runId> (on remote hosts the bundle SCM_<runId>.tar.gz is extracted first, then the bundle and any loose SCM_<runId>/ copy are removed). The final folder holds scenario_index.csv, per-scenario subfolders, Overall.csv, optional stepwise logs, and rsnlme_run.rds.

See Also

shotgunSearch, stepwiseSearch, summary(), print(), getSCMResults

List the built-in NlmePmlModel constructors

Description

Discovery tool: returns the catalog of RsNLME model constructors an agent can choose from before building a model, each with its model type (pk/pd/pkpd/ custom), the KB entry that documents it, the help topic, and the required/common column-mapping terms. Prefer a built-in template when one matches the requested model; use textualmodel for custom PML.

Usage

list_builtin_model_constructors()

Details

The three PK/PD constructors (pklinearmodel, pkindirectmodel, pkemaxmodel) additionally carry mode_flags: structural constructor_args (not column-mapping terms) such as the PPP&D staging pair isSequential/isPkFrozen (mutually exclusive - see mutually_exclusive) and each model's PD functional-form choice (linearType/indirectType/checkBaseline/...). validate_fit_spec() rejects a mutually_exclusive conflict or an out-of-choices enum value before a job launches.

Value

A list of constructor records.

Examples

list_builtin_model_constructors()

List registered MCP runs

Description

List registered MCP runs

Usage

list_mcp_runs(project_dir = ".")

Arguments

Value

A list of job records.

List artifacts produced by a job

Description

List artifacts produced by a job

Usage

list_nlme_artifacts(job_id, project_dir = ".")

Arguments

Value

A list with run_dir, artifact_dir, and artifacts (relative paths under artifact_dir, i.e. ⁠<run_dir>/artifacts⁠).

List sequential-LRT sessions for a project

Description

Read-only: scans ⁠<project_dir>/qualification/lrt/⁠ for session directories and returns each session's persisted status snapshot (the same shape advance_sequential_lrt()/get_sequential_lrt_status() return) - no live job polling, so this is safe and cheap to call often. Used by get_project_workflow_status() and the Certara.R host's get_certara_project_status() project-status merge, so both can surface in-progress and completed anchored LRT refinements without re-deriving session state or re-implementing this provider's session format.

Usage

list_sequential_lrt_sessions(project_dir = ".")

Arguments

Value

A list of per-session status snapshots (list() when the ⁠qualification/lrt/⁠ directory does not exist or holds no sessions).

Load model.rda file

Description

Loads a previously saved model from disk.

Usage

loadModel(directory)

Arguments

Details

Note, the names of model, engine, and host objects will be appended with name of model directory when reloading model.rda file to global environment.

Value

No value is returned. Model object is loaded in global environment.

Examples

TempDir <- tempdir()
model <- emaxmodel(
  checkBaseline = TRUE,
  checkFractional = TRUE,
  checkInhibitory = TRUE,
  data = pkpdData,
  ID = "ID",
  C = "CObs",
  EObs = "EObs",
  modelName = "model",
  workingDir = TempDir
)

saveModel(model)

loadModel(TempDir)

Return model variable names

Description

Return a vector of model variable names from model object

Usage

modelVariableNames(model)

Arguments

Value

Character vector of required model variable names

Examples

model <- pkmodel(columnMap = FALSE,
                 workingDir = tempdir())
modelVariableNames(model)

Get observation names

Description

Get observation model variables names.

Usage

observationNames(model)

Arguments

Value

Character vector of observation model variables names.

Examples

model <- pkemaxmodel(columnMap = FALSE)
obsnames <- observationNames(model)

Obtain NLME License

Description

This function attempts to authenticate and obtain an NLME license using the specified installation directory and licensing tool.

Usage

obtain_NLMELicense(
  InstallDir = Sys.getenv("INSTALLDIR"),
  ForceAuth = FALSE,
  ForceLicenseGet = FALSE,
  verbose = getOption("verbose")
)

Arguments

Details

This function checks for the presence of the necessary appsettings.json file as indicated by the CAD_CONFIG_FILE environment variable, runs the licensing tool to authenticate the user, and attempts to obtain an NLME license. It prints detailed messages if the verbose parameter is set to TRUE.

Value

A logical value indicating whether the license was successfully obtained.

Examples

## Not run: 
INSTALLDIR <- Sys.getenv("INSTALLDIR")
if (INSTALLDIR == "") INSTALLDIR <- "C:/Program Files/Certara/NLME_Engine"
result <- obtain_NLMELicense(INSTALLDIR, verbose = TRUE)
if (result) {
  message("License obtained successfully!")
} else {
  message("Failed to obtain license.")
}

## End(Not run)

Open generated PML in Certara Model Designer (web)

Description

Resolves PML text from exactly one of pml, path, or model_rds, encodes it the way Certara Model Designer's web frontend expects (⁠base64url(raw-DEFLATE(UTF-8 PML))⁠), and builds a {md_base}/models/custom?pml=... URL. When md_base is not supplied, the Model Designer environment(s) registered for the caller's current CAD organization are looked up via obtain_NLMELicense()'s auth.json; the organization is never guessed from the issuer host.

Usage

open_model_in_model_designer(
  pml = NULL,
  path = NULL,
  model_rds = NULL,
  md_base = NULL,
  open_browser = TRUE,
  api_version = "v4",
  verbose = TRUE
)

Arguments

Details

Requires the curl package (only when md_base is not supplied) and an existing CAD auth.json (see obtain_NLMELicense()).

Value

A list with status (one of "ok", "not_registered", "needs_user_choice"), sso_authority, md_base, url (non-NULL only when status == "ok"), candidates (registered environment URLs), and pml_chars.

Examples

## Not run: 
open_model_in_model_designer(pml = "test(){\n  C = A1 / V\n}")

## End(Not run)

Embed column definition info into the model

Description

Add/update column definition information for the model object

Usage

parsePMLColMap(.Object, ForceRun = TRUE)

Arguments

Details

Intended to be used by other packages

Value

modified NLMEPmlModel object with column mapping definitions

Create NlmeParallelHost object from json file with host definition

Description

Create NlmeParallelHost object from json file with host definition

Usage

parse_NLMEHosts(nlme_hostPath)

Arguments

Value

the NlmeParallelHost class object is returned.

Examples

## Not run: 
# path nlme_hostPath should be specified
 nlme_hostPath <- tempfile()
 host1 <- paste0('{"profile_name":"Multicore",',
  '"hostname":"127.0.0.1",',
  '"cores_number":4,',
  '"parallel_mode":"MULTICORE"}')
 host2 <- paste0('{"profile_name":"MPI",',
 '"hostname":"127.0.0.1",',
 '"cores_number":8,',
 '"parallel_mode":"LOCAL_MPI"}')

writeLines(paste0("[", host1, ",", host2, "]"), nlme_hostPath)
hosts <- parse_NLMEHosts(nlme_hostPath)

## End(Not run)

Pharmacokinetic dataset containing 16 subjects with single bolus dose

Description

Pharmacokinetic dataset containing 16 subjects with single bolus dose.

Usage

pkData

Format

A data frame with 112 rows and 8 variables:

Subject

Subject ID

Nom_Time

Nominal Time

Act_Time

Actual Time

Amount

Amount of dose

Conc

Observations of drug concentration in blood

Age

Age

BodyWeight

Body weight

Gender

Gender ("male", "female")

Source

Certara University

Pharmacokinetic pediatric dataset containing 80 subjects with single bolus dose.

Description

Pharmacokinetic pediatric dataset containing 80 subjects with single bolus dose. Dataset includes covariates and observations Below Quantification Limit (BQL).

Usage

pkcovbqlData

Format

A data frame with 880 rows and 8 variables:

ID

Subject ID

Time

Nominal Time

Dose

Amount of dose

CObs

Observations of drug concentration in blood

LLOQ

Lower Limit of Quantification

CObsBQL

Variable that indicates whether the observed drug concentration is below the limit of quantification

BW

Body weight

PMA

Postmenstrual age

Source

The data is simulated using a one-compartment model with IV bolus, where the central volume is allometric weight scaled, and the clearance is scaled by a combination of allometric weight scaling and a sigmoidal maturation function driven by PMA. Germovsek E., et al, Pharmacokinetic–Pharmacodynamic Modeling in Pediatric Drug Development, and the Importance of Standardized Scaling of Clearance, Clin Pharmacokinet (2019) 58:39–52.

Create a PK/Emax or PK/Imax model

Description

Use to create a PK/Emax or PK/Imax model

Usage

pkemaxmodel(
  isPopulation = TRUE,
  parameterization = "Clearance",
  absorption = "Intravenous",
  numCompartments = 1,
  isClosedForm = TRUE,
  isTlag = FALSE,
  hasEliminationComp = FALSE,
  isFractionExcreted = FALSE,
  isSaturating = FALSE,
  infusionAllowed = FALSE,
  isDuration = FALSE,
  isSequential = FALSE,
  isPkFrozen = FALSE,
  hasEffectsCompartment = FALSE,
  checkBaseline = FALSE,
  checkFractional = FALSE,
  checkInhibitory = FALSE,
  checkSigmoid = FALSE,
  isEmaxFrozen = FALSE,
  data = NULL,
  columnMap = TRUE,
  modelName = "",
  workingDir = "",
  ...
)

Arguments