Package 'Certara.RsNLME'

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

model <- addADDL(model, ADDL = "addl", II = "ii")

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"
)

# 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")
)

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 <- pkmodel(columnMap = FALSE) %>%
  addDoseCycle(type = "SteadyState", name = "A1", amount = "Amount", II = "II")

Description

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

Usage

addExtraDef(.Object, value)

Arguments

Value

Modified NlmePmlModel object

Examples

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

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

newModel <- addInfusion(model, "A1", FALSE, FALSE, "A1_1")

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 <- addLabel(model, covariate, c(1, 2, 3), c("a", "b", "c"))

Description

Use to add MDV statement to model@userDefinedExtraDefs

Usage

addMDV(.Object, MDV)

Arguments

Value

Modified NlmePmlModel object

Examples

model <- addMDV(model, MDV = "MDV")

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.

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 <- addSecondary(model, "Spc_Param", "log(2)/tvKe")
model <- addSecondary(
  model, "Tmax",
  "CalcTMax(tvA,tvAlpha,tvB,tvBeta,C,Gamma)"
)

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

model <- addSteadyState(model, SS = "ss", II = "ii")

Description

Method to execute an NLME Bootstrap

Usage

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

Arguments

Value

if runInBackground = FALSE, a list is returned with bootstrap results, i.e. "BootOverall", "BootTheta", "BootOmega", "BootOmegaStderr", "BootVarCoVar" comma separated files. Otherwise the BootNlmeJob class object is returned.

See Also

hostParams, engineParams, BootstrapParams

Examples

input_data <- pkData

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

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

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

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.

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)

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))

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

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

# Fit Model
job <- fitmodel(model)

# Copy model and accept all effects from the original model run
vpcModel <- copyModel(model, acceptAllEffects = TRUE, modelName = "vpc_model")

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)
model <- addCovariate(model, covariate = "BW", effect = "V")
model <- addCovariate(model, covariate = "Age", effect = "Cl")

covariateNames(model)

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

createModelInfo(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)

model <- dataMapping(model, pkData)

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)

doses <- doseNames(model)

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)

newModel <- editModel(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)

Description

Use to define extra 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,
  numIntegratePtsAGQ = 1,
  numIterNonParametric = 0,
  allowSyntheticGradient = FALSE,
  numIterMAPNP = 0,
  numRepPCWRES = 0,
  stepSizeLinearize = 0.002,
  numDigitLaplacian = 7,
  numDigitBlup = 13,
  mapAssist = 0,
  iSample = 300,
  iAcceptRatio = 0.1,
  impDist = "Normal",
  tDOF = 4,
  numSampleSIR = 10,
  numBurnIn = 0,
  freezeOmega = FALSE,
  MCPEM = FALSE,
  runAllIterations = FALSE,
  scramble = "Owen",
  stepSizePartialDeriv = 1e-05,
  numTimeStepPartialDeriv = 20
)

Arguments

Details

Both '"DVERK"' and '"DOPRI5"' are non-stiff solvers. '"Higham"' is a matrix exponent based ODE solver which could be useful when overscaling issue should be avoided, i.e. the ratio between observed values and doses is too high or too low. '"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.

Value

List of engine parameters to be used during fitting or simulation

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") |>
addDoseCycle(
  name = "A1",
  amount = 30000,
  II = 24,
  type = "ADDL",
  colName = "ADDL")

extraDoseLines(model)

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") |>
addDoseCycle(
  name = "A1",
  amount = 30000,
  II = 24,
  type = "ADDL",
  colName = "ADDL")

extraDoseNames(model)

Description

Executes an NLME simple estimation

Usage

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

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, only current status of job is returned.

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

See Also

tableParams, hostParams, engineParams

Examples

# Define the host
 host <- hostParams(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")

 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)

Description

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

Usage

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

Arguments

Value

Modified NlmePmlModel object

Examples

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

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

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

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)
getRandomEffectNames(model)

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

getThetas(pkpdmodel)

Description

Initialize for NlmeParallelHost

Usage

hostParams(
  sharedDirectory,
  installationDirectory = Sys.getenv("INSTALLDIR"),
  hostName = Sys.info()[["nodename"]],
  machineName = "127.0.0.1",
  hostType = Sys.info()[["sysname"]],
  numCores = 4,
  parallelMethod = "LOCAL_MPI",
  userName = "",
  privateKeyFile = NULL,
  userPassword = "",
  scriptPath = "",
  rLocation = "",
  isLocal = TRUE
)

Arguments

Value

NlmeParallelHost class instance

Examples

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

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"
  )

# 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)

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)

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

listCovariateEffectNames(model)

Description

Return a vector of model variable names from model object

Usage

modelVariableNames(model)

Arguments

Value

Character vector of required model variable names

Examples

modelVariableNames(model)

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

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

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

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

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.

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

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

Value

NlmePmlModel object

Column mapping

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

Examples

model <- pkemaxmodel(
  parameterization = "Macro",
  data = pkpdData,
  Time = "Time",
  ID = "ID",
  A1 = "Dose",
  C1Obs = "CObs",
  EObs = "EObs"
)

# View the model as well as its associated column mappings
print(model)

Description

Use to create a PK/Indirect response model.

Usage

pkindirectmodel(
  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,
  indirectType = "LimitedStimulation",
  isBuildup = TRUE,
  isExponent = FALSE,
  indirectFrozen = 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 <- pkindirectmodel(
  parameterization = "Micro",
  data = pkpdData,
  ID = "ID",
  Time = "Time",
  A1 = "Dose",
  CObs = "CObs",
  EObs = "EObs"
)

# View PML Code
print(model)

Description

Use to create a PK/PD model with PD described by either constant, linear, or quadratic model

Usage

pklinearmodel(
  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,
  linearType = "Constant",
  isLinearFrozen = 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 <- pklinearmodel(
  parameterization = "Clearance",
  linearType = "Constant",
  data = pkpdData,
  ID = "ID",
  Time = "Time",
  A1 = "Dose",
  CObs = "CObs",
  EObs = "EObs"
)

# View the model as well as its associated column mappings
print(model)

Description

Use to create a PK model

Usage

pkmodel(
  isPopulation = TRUE,
  parameterization = "Clearance",
  absorption = "Intravenous",
  numCompartments = 1,
  isClosedForm = TRUE,
  isTlag = FALSE,
  hasEliminationComp = FALSE,
  isFractionExcreted = FALSE,
  isSaturating = FALSE,
  infusionAllowed = FALSE,
  isDuration = FALSE,
  isStdevFrozen = 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 <- pkmodel(
  parameterization = "Clearance",
  numCompartments = 2,
  data = pkData,
  ID = "Subject",
  Time = "Act_Time",
  A1 = "Amount",
  CObs = "Conc"
)

# View the model as well as its associated column mappings
print(model)

Description

Pharmacokinetic/Pharmacodynamic dataset containing 200 subjects with single bolus dose.

Usage

pkpdData

Format

A data frame with 2600 rows and 5 variables:

ID

Subject ID

Time

Nominal Time

Dose

Amount of dose

CObs

Observations of drug concentration in blood

EObs

Observations of drug effect

Source

The data is simulated using a PKPD model with PK described by a one-compartment model with IV bolus and PD described by an indirect response model with the loss inhibited.

Description

Prints model information, including PML and column mappings.

Usage

## S3 method for class 'NlmePmlModel'
print(x, ...)

Arguments

Value

NULL

Examples

model <- pkmodel(columnMap = FALSE, data = pkData)
print(model)

Description

Use to set or update the covariance matrix of random effects in a model object.

Usage

randomEffect(
  .Object,
  effect,
  value = NULL,
  isDiagonal = TRUE,
  isFrozen = FALSE,
  ...
)

Arguments

Value

Modified NlmePmlModel object

Examples

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

model <- model |>
  randomEffect(effect = c("nV", "nCl", "nCl2"), value = rep(0.1, 3))

Description

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

Usage

remove_NLMELicense(InstallDir = Sys.getenv("INSTALLDIR"))

Arguments

Details

The function checks for the presence of the necessary 'appsettings.json' file in the specified directory or the CAD config file specified by the 'CAD_CONFIG_FILE' environment variable, runs the licensing tool to log out the user, and attempts to remove the NLME license.

Value

A logical value indicating whether the license information was successfully removed.

Examples

result <- remove_NLMELicense("/path/to/install/dir")
  if (result) {
    message("License removed successfully!")
  } else {
    message("Failed to remove license.")
  }

Description

Remove one or more covariates from structural parameters in a model object.

Usage

removeCovariate(.Object, covariate = NULL, paramName = NULL)

Arguments

Value

Modified NlmePmlModel object

Examples

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

# 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")
)

# Remove all covariates from model
model <- removeCovariate(model)

Description

Use to return character vector of residual effect names in model object

Usage

residualEffectNames(model)

Arguments

Value

Character vector of residual effect names

Examples

model <- pkemaxmodel(columnMap = FALSE)
residualEffectNames(model)

Description

Use to change or update residual error model for model object

Usage

residualError(
  .Object,
  predName = "C",
  errorType = NULL,
  SD = NULL,
  isFrozen = FALSE,
  isBQL = FALSE,
  staticLLOQ = NULL,
  EObsBQL = NULL,
  CObsBQL = NULL,
  C1ObsBQL = NULL,
  A0ObsBQL = NULL,
  exponent = NULL
)

Arguments

Value

Modified NlmePmlModel object

Examples

model <- pkindirectmodel(indirectType = "LimitedInhibition", isBuildup = FALSE,
 data = pkpdData, ID = "ID", Time = "Time", A1 = "Dose", CObs = "CObs", EObs = "EObs")

residualEffectNames(model)

# Change error type to "Multiplicative" and value of SD to 0.1 for "E"
model <- residualError(model, predName = "E", errorType = "Multiplicative", SD = 0.1)

# Change error type to "Power", value of SD to 0.15, and set exponent = 2 for "C"
model <- residualError(model, predName = "C", errorType = "Power", SD = 0.15, exponent = 2)

Description

Returns character vector of secondary parameter names for model object.

Usage

secondaryParameterNames(model)

Arguments

Value

Character vector of secondary parameter names defined in model

Examples

model <- pkemaxmodel(columnMap = FALSE)
secondaryparms <- secondaryParameterNames(model)

Description

Executes an NLME shotgun covariate search

Usage

shotgunSearch(
  model,
  hostPlatform = NULL,
  params,
  covariateModel,
  runInBackground = FALSE,
  ...
)

Arguments

Value

if runInBackground = FALSE, a data frame is returned with shotgun (all combinations given the covariate model) search results, i.e. "Overall" comma separated file. Otherwise the ShotgunNlmeJob class object is returned.

See Also

hostParams, engineParams

Examples

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

# 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"))

# Define the host
host <- hostParams(parallelMethod = "None",
                   hostName = "local",
                   numCores = 1)

# Define the engine parameters
params <- engineParams(model)

# Define covariate model
cp <- covariateModel(model)

# Perform shotgun search
OverallDF <-  shotgunSearch(model = model,
                            hostPlatform = host,
                            params = params,
                            covariateModel = cp,
                            runInBackground = FALSE)

Description

Executes an NLME simulation

Usage

simmodel(
  model,
  simParams,
  params,
  hostPlatform = NULL,
  runInBackground = FALSE,
  ...
)

Arguments

Value

returns job properties if runInBackground is TRUE; if runInBackground is FALSE and the function is called in interactive mode, the resulted simulated tables wil be loaded and presented as a list; if runInBackground is FALSE and the function is called in non-interactive mode, the list returned will have just the full paths of the tables generated.

Examples

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

simParams <- NlmeSimulationParams(
  numReplicates = 2,
  simulationTables = SimTableObs
)
# Define the model
model <- pkmodel(
  numComp = 2,
  absorption = "Extravascular",
  ID = "Subject",
  Time = "Act_Time",
  CObs = "Conc",
  Aa = "Amount",
  data = pkData,
  modelName = "PkModel"
)
results <- simmodel(model, simParams)
# with seed given additionally:
results <- simmodel(model, simParams, seed = 3527)

Description

Executes an NLME simple estimation with sort keys and given scenarios

Usage

sortfit(
  model,
  hostPlatform = NULL,
  params,
  sortColumns,
  scenarios = list(),
  simpleTables,
  runInBackground = FALSE,
  filesToReturn = "*",
  ...
)

Arguments

Details

All the results in tabular format have scenario column and sorts columns appended. The resulted logs (nlme7engine.log, err1.txt, dmp.txt, out.txt) are appended with a row delimiter where the name of the Scenario and sort values are specified.

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, only current status of job is returned.

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

See Also

hostParams, engineParams, SortColumns, NlmeScenario, tableParams

Examples

input_data <- pkData

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

model <-
  addCovariate(model,
               covariate = "BodyWeight",
               direction = "Backward",
               center = "Mean",
               effect = c("V", "Cl"))

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

# specify scenarios
CovariateEffectNames <- listCovariateEffectNames(model)
combinations <-
  combn(c("", CovariateEffectNames),
        length(CovariateEffectNames),
        simplify = FALSE)

scenarioNames <-
  lapply(combinations,
         function(x) {paste(x, collapse = " ")})

scenarios <-
  lapply(scenarioNames,
         function(x, CovariateEffectNames) {
           CovariateCombinations <- unlist(strsplit(x, " ", fixed = TRUE))
           scenarioIndex <-
             paste(which(CovariateEffectNames %in% CovariateCombinations,
                         arr.ind = TRUE),
                         collapse = ", ")
           NlmeScenario(trimws(x), scenarioIndex)
         },
         CovariateEffectNames)

res <-
  sortfit(model,
          hostPlatform = multicoreHost,
          params = engineParams(model),
          sortColumns = SortColumns("Gender"),
          scenarios = scenarios)

Description

Executes an NLME stepwise covariate search

Usage

stepwiseSearch(
  model,
  hostPlatform = NULL,
  params,
  covariateModel,
  stepwiseParams,
  runInBackground = FALSE,
  ...
)

Arguments

Value

if runInBackground = FALSE, a data frame is returned with stepwise search results, i.e. "Overall" comma separated file. Otherwise the StepwiseNlmeJob class object is returned.

See Also

hostParams, engineParams

Examples

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

# 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"))

# Define the host
defaultHost <- hostParams(parallelMethod = "None",
                   hostName = "local",
                   numCores = 1)

# Define the engine parameters
params <- engineParams(model)

# Define covariate model
cp <- covariateModel(model)

# Define the stepwise parameters
sp <- StepwiseParams(0.01, 0.001, "-2LL")

# Perform stepwise search
OverallDF <-  stepwiseSearch(model = model,
                      hostPlatform = defaultHost,
                      params = params,
                      covariateModel = cp,
                      stepwiseParams = sp,
                      runInBackground = FALSE)

Description

Use to specify the relationship of the structural parameter with corresponding fixed effect, random effect, and covariate.

Usage

structuralParameter(
  .Object,
  paramName,
  fixedEffName = NULL,
  randomEffName = NULL,
  style = "LogNormal",
  hasRandomEffect = NULL
)

Arguments

Value

Modified NlmePmlModel object

Examples

model <- pkindirectmodel(
  indirectType = "LimitedInhibition",
  isBuildup = FALSE,
  data = pkpdData,
  ID = "ID",
  Time = "Time",
  A1 = "Dose",
  CObs = "CObs",
  EObs = "EObs"
)

# Change style of structural parameter "Imax" to "LogitNormal"
# and rename fixed effect to "tvlogitImax"
model <- structuralParameter(model,
  paramName = "Imax",
  style = "LogitNormal", fixedEffName = "tvlogitImax"
)

# Remove random effect for structural parameter "IC50"
model <- structuralParameter(model,
  paramName = "IC50",
  hasRandomEffect = FALSE
)

Description

Returns character vector of structural parameter names for model object.

Usage

structuralParameterNames(model, omitEmpties = TRUE)

Arguments

Value

Character vector of structural parameter names defined in model

Examples

model <- pkemaxmodel(columnMap = FALSE)
stparms <- structuralParameterNames(model)

Description

Wrapper around NlmeTableDef/NlmeSimTableDef-classes initializers.

Usage

tableParams(
  name = "",
  timesList = numeric(0),
  covrSet = "",
  whenDose = "",
  whenObs = "",
  variablesList = "",
  keepSource = FALSE,
  timeAfterDose = FALSE,
  IRES = FALSE,
  Weight = FALSE,
  IWRES = FALSE,
  mode = "all",
  forSimulation = FALSE
)

Arguments

Value

NlmeTableDef object if forSimulation is FALSE, NlmeSimTableDef object otherwise.

Examples

Table1 <- tableParams(
  name = "Table1.csv",
  timesList = seq(0, 24, 2),
  whenObs = c("CObs"),
  variablesList = "C",
  IRES = TRUE,
  IWRES = TRUE,
  Weight = TRUE)

SimTable1 <- tableParams(
  name = "SimTable1.csv",
  variablesList = "CL, V",
  keepSource = TRUE,
  forSimulation = TRUE)

Description

Use to create an empty model object and optionally supply location of .mdl file to initialize model with PML statements.

Usage

textualmodel(modelName = "", workingDir = "", data, mdl = NULL)

Arguments

Value

NlmePmlModel object

Examples

model <- textualmodel(data = pkData)

Description

Perform visual predictive check for NLME models

Usage

vpcmodel(
  model,
  vpcParams,
  params,
  hostPlatform = NULL,
  runInBackground = FALSE,
  ...
)

Arguments

Value

if runInBackground is TRUE, it returns job properties. Otherwise,

• If the function is called in an interactive mode, the resulting simulated tables and summary statistics tables will be loaded and presented as a list;

• If the function is called in a non-interactive mode, it returns the full paths of the tables generated

Examples

job <- fitmodel(model)

# View estimation results
print(job)

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

# 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)
# the same as:
finalVPCJob <- vpcmodel(model = finalModelVPC, outputPRED = TRUE)

# Observed dataset predcheck0.csv
dt_ObsData <- finalVPCJob$predcheck0

# Simulation output dataset predout.csv
dt_SimData <- finalVPCJob$predout

# Add PRED from REPLICATE = 0 of simulation output dataset to observed input dataset
dt_ObsData$PRED <- dt_SimData[REPLICATE == 0]$PRED

# tidyvpc package VPC example:
# library(tidyvpc)
library(magrittr)
# Create a regular VPC plot with binning method set to be "jenks"
binned_VPC <- observed(dt_ObsData, x = IVAR, yobs = DV) %>%
  simulated(dt_SimData, ysim = DV) %>%
  binning(bin = "jenks") %>%
  vpcstats()

plot_binned_VPC <- plot(binned_VPC)

# Create a pcVPC plot with binning method set to be "jenks"
binned_pcVPC <- observed(dt_ObsData, x = IVAR, yobs = DV) %>%
  simulated(dt_SimData, ysim = DV) %>%
  binning(bin = "jenks") %>%
  predcorrect(pred = PRED) %>%
  vpcstats()

plot_binned_pcVPC <- plot(binned_pcVPC)