Title: Interface for 'pyDarwin' Machine Learning Pharmacometric Model Development

Version: 1.1.1

Description: Utilities that support the usage of 'pyDarwin' (https://certara.github.io/pyDarwin/) for ease of setup and execution of a machine learning based pharmacometric model search with Certara's Non-Linear Mixed Effects (NLME) modeling engine.

Depends: R (≥ 3.6)

License: LGPL-3

URL: https://certara.github.io/R-Darwin/

Encoding: UTF-8

RoxygenNote: 7.3.2

Imports: methods, magrittr, jsonlite

Suggests: testthat (≥ 3.0.0), dplyr, tidyr, tibble, knitr, rmarkdown

Config/testthat/edition: 3

NeedsCompilation: no

Packaged: 2025年02月24日 23:02:58 UTC; jcraig

Author: Michael Tomashevskiy [aut], James Craig [aut, cre], Certara USA, Inc [cph, fnd]

Maintainer: James Craig <james.craig@certara.com>

Repository: CRAN

Date/Publication: 2025年02月25日 17:50:11 UTC

Covariate(
 Name = character(),
 Type = "Continuous",
 StParmName = character(),
 State = "Present",
 Direction = "Forward",
 Center = "None",
 Categories = c(),
 Thetas = c(),
 Omegas = c(),
 PMLStructure = character()
)

Name

Character specifying the name of the covariate.

Type

A character specifying the type of the covariate. Possible values are:

• Continuous A covariate can take values on a continuous scale.

• Categorical A covariate can only take a finite number of values.

• Occasion The associated PK parameter may vary within an individual from one event to the next, called interoccasion variability.

StParmName

A character specifying the corresponding structural parameter name.

State

A character string representing the presence of the covariate on the structural parameters. Possible values are:

• None The covariate does not have an effect on any structural parameter.

• Present The covariate has an effect on the structural parameters (the default).

• Searched The effect of the covariate on structural parameters is searched.

Direction

A character string representing the direction of the Covariate. Options are Forward, Backward, Interpolate. Default is Forward. Interpolate is only applicable to Type == "Continuous".

Center

A character string (None, Mean or Median) or numeric value representing the center of the Covariate. Default is None. Valid only if Type == "Continuous".

Categories

A numeric vector representing the categories (at least two) of the covariate. Applicable only if Type is either Occasion or Categorical. The first category is set to the reference category for categorical covariate.

Thetas

A list of Theta objects representing Thetas covariate effects. Only applicable if Type is either Categorical or Continuous. If Type == "Continuous", one Theta corresponding to current Covariate should be presented. If Type == "Categorical", thetas corresponding to each category (except the reference category) can be specified. If not given, theta(s) will be automatically generated with initial estimate set to 0.0.

Omegas

A list of Omega objects representing the Omegas of the inter-occasion random effects. Applicable only if Type == "Occasion". The number of Omegas should be equal to the number of categories provided. If not given, Omegas will be created automatically with initial estimate set to 1.0.

PMLStructure

PML structure current Covariate instance belongs to.

WT_Covariate <-
 Covariate(Name = "WT",
 Type = "Continuous",
 StParmName = "V",
 State = "Present",
 Direction = "Forward",
 Center = 70,
 Thetas = Theta("dVdWT", 1))
Race_Covariate <-
 Covariate(
 Name = "Race",
 Type = "Categorical",
 StParmName = "V2",
 State = "Searched",
 Direction = "Backward",
 Center = "None",
 Categories = c(1,2,3))

Dosepoint(
 DosepointName = "A1",
 State = "Present",
 tlag = c(),
 bioavail = c(),
 duration = c(),
 rate = c(),
 PMLStructure = character()
)

DosepointName

A character string giving the name of the Dosepoint.

State

A character string representing the state of the Dosepoint. Possible values are:

• None: current Dosepoint is not used.

• Present (the default): current Dosepoint is used as is.

• Searched: current Dosepoint is added as a token to be searched.

tlag

An optional structural parameter giving the time lag for the doses coming into current Dosepoint.

bioavail

An optional structural parameter giving the bioavailability of the doses coming into current Dosepoint.

duration

An optional structural parameter giving the duration of infusion for the doses coming into current Dosepoint.

rate

An optional structural parameter giving the rate of infusion for the doses coming into current Dosepoint.

PMLStructure

A character string that indicates bounded PML structure.

TlagStParm <- StParm("Tlag",
 Type = "LogNormal",
 ThetaStParm = Theta(Name = "tvTlag",
 InitialEstimates = 0.1))
A1 <- Dosepoint(DosepointName = "A1",
 State = "Present",
 tlag = TlagStParm,
 bioavail = StParm("F"))

InitialEstimate(Initial = numeric(), ...)

Initial

Numeric. Initial estimate for the model parameter.

...

Additional initial estimate(s) for the model parameter.

InitialEstimate(1)
InitialEstimate(c(0, 1, Inf), c(-Inf, 2, 10))

Observation(
 ObservationName = "CObs",
 SigmasChosen = Sigmas(Proportional = 0.1),
 BQL = FALSE,
 BQLValue = NA,
 Frozen = FALSE,
 ResetObs = FALSE,
 Covariates = list(),
 PMLStructure = character()
)

ObservationName

A character string giving the name of the Observation.

SigmasChosen

a Sigmas class instance or a list specifying the chosen sigma values for different error models. 0s are treated as no values. Inside Observation class it is transormed and kept as Sigmas class. The list could contain the following error models:

• Additive The additive error sigma value.

• LogAdditive The log-additive error sigma value.

• Proportional The proportional error sigma value.

• AdditiveMultiplicative A numeric vector specifying the additive and multiplicative parts for the additive-multiplicative error model. The vector should have names PropPart and AddPart.

• MixRatio A numeric vector specifying the proportional and additive parts for the mix-ratio error model. The vector should have names PropPart and AddPart.

• Power A numeric vector specifying the standard deviation and power parts for the power error model. The vector should have names StdevPart and PowerPart.

BQL

A logical value indicating whether the dataset contains BQL values and they should be taken into account (M3 method).

BQLValue

An optional numeric positive value of static LLOQ. Applicable only when BQL argument is TRUE. Any observed value less than or equal to that LLOQ value is treated as censored.

Frozen

A logical value indicating if the standard deviation (Stdev) is frozen.

ResetObs

A logical value indicating if the Observation variable should be reset to 0 after observation (doafter={A0=0;}). Applicable for elimination compartment.

Covariates

A list of covariates (Covariate instances) that should be included in the model, but not linked to any of structural parameters. Used with "Emax" PD models ('C' covariate is added automatically when creating a new model, but should be added manually when modifying the model).

PMLStructure

Character specifying the name of PML structure in which the observation should be added. For the naming convention of PMLStructures, see Details section of get_PMLParametersSets() .

A0Obs <-
 Observation(ObservationName = "A0Obs",
 SigmasChosen = list(Additive = 2,
 Power = c(Stdev = 10, Power = 0.5)),
 Frozen = FALSE,
 ResetObs = TRUE,
 PMLStructure = "PK1FOC")
CObs <- Observation("CObs", Frozen = TRUE, PMLStructure = "2Cpt")

ObservationCustom(
 ObservationName = "CObs",
 Type = "observe",
 Statement = "",
 StatementNames = list(),
 Sigma = list(),
 Dobefore = c(),
 Doafter = c(),
 BQL = FALSE,
 BQLValue = NA,
 PMLStructure = character()
)

ObservationName

A character string giving the name of the Observation.

Type

One of the following: observe, multi, LL, event, count, ordinal

Statement

A character string giving the RHS of response statement without Type.

StatementNames

A character vector giving the names of variables used in the Statement.

Sigma

a list specifying the chosen sigma value Should be given only if Type == "observe"

Dobefore

A character string specifying the sequence of operations to be performed before current observation event.

Doafter

A character string specifying the sequence of operations to be performed after current observation event.

BQL

A logical value indicating whether the dataset contains BQL values and they should be taken into account (M3 method).

BQLValue

An optional numeric positive value of static LLOQ. Applicable only when BQL argument is TRUE. Any observed value less than or equal to that LLOQ value is treated as censored.

PMLStructure

Character specifying the name of PML structure in which the observation should be added. For the naming convention of PMLStructures, see Details section of create_ModelPK() .

Omega(
 Name = character(),
 InitialOmega = 1,
 State = "Present",
 Frozen = FALSE,
 StParmName = character(),
 PMLStructure = character()
)

Name

A character string specifying the name of the Omega.

InitialOmega

Numeric specifying the initial value of the Omega. Default value is 1.

State

Character specifying the presence of the Omega. Possible values are:

• None The Omega does not exist in the specified PMLStructures.

• Present The Omega exists in the specified PMLStructures (the default).

• Searched The presence of the Omega is searched.

Frozen

A logical value indicating whether the Omega is frozen or not.

StParmName

A character string specifying the corresponding structural parameter name.

PMLStructure

PML structure current omega belongs to.

nV <- Omega("nV")

Sigmas(
 Additive = 0,
 LogAdditive = 0,
 Proportional = 0.1,
 AdditiveMultiplicative = list(PropPart = 0, AddPart = 0),
 MixRatio = list(PropPart = 0, AddPart = 0),
 Power = list(PowerPart = 0, StdevPart = 0),
 ObservationName = ""
)

Additive

The additive error sigma value.

LogAdditive

The log-additive error sigma value.

Proportional

The proportional error sigma value.

AdditiveMultiplicative

A list specifying the additive and multiplicative parts for the additive-multiplicative error model. The list should have elements PropPart and AddPart. Alternatively the proportional part (PropPart) could be presented as StParm, see StParm() .

MixRatio

A list specifying the proportional and additive parts for the mix-ratio error model. The list should have elements PropPart and AddPart. Alternatively the proportional part (PropPart) could be presented as StParm, see StParm() .

Power

A numeric vector specifying the standard deviation and power parts for the power error model. The vector should have names StdevPart and PowerPart.

ObservationName

A character string giving the name of the Observation.

RSE_CObs <-
 Observation(SigmasChosen =
 Sigmas(MixRatio = list(PropPart = 2,
 AddPart = 0.01),
 Proportional = 0))
models <-
 create_ModelPK(CompartmentsNumber = 2,
 CObs = RSE_CObs)
print(models)

StParm(
 StParmName = character(),
 Type = "LogNormal",
 State = "Present",
 ThetaStParm = list(),
 OmegaStParm = list(),
 Covariates = list(),
 PMLStructure = character()
)

StParmName

Character specifying the name of the structural parameter.

Type

Character specifying the type of the structural parameter. Options are

• LogNormal The PML statement of the structural parameter will look like the following:

stparm(V = tvV * wt^dVdwt * exp(nV + nVx0*(Occasion==0) + nVx1*(Occasion==1)))

• LogNormal1 The PML statement of the structural parameter will look like the following:

stparm(V = (tvV + wt*dVdwt) * exp(nV + nVx0*( Occasion==0) + nVx1*( Occasion==1)))

• LogNormal2 The PML statement of the structural parameter will look like the following:

stparm(V = exp(tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occason==1)))

• LogitNormal The PML statement of the structural parameter will look like the following:

stparm(V = ilogit(tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occasion==1)))

• Normal The PML statement of the structural parameter will look like the following:

stparm(V = tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occasion==1))

State

character string that indicates the presence of the structural parameter. Options are:

• None The structural parameter does not exist in the specified PMLStructures.

• Present The structural parameter exists in the specified PMLStructures (the default).

• Searched The presence of the structural parameter is searched.

ThetaStParm

A Theta class instance inside the structural parameter. If not given, the associated Theta will be automatically created with its name set to "tv" + StParmName.

OmegaStParm

An Omega class instance inside the structural parameter. If not given, the associated Omega will be automatically created with its name set to "n" + StParmName

Covariates

A list of covariates (Covariate instances) that should be included in the structural parameter statement.

PMLStructure

Character specifying the name of PML structure for which current parameter should be attributed. For the naming convention of PMLStructures, see Details section of create_ModelPK() for PK models and create_ModelPD() for PD models.

# Create a Structural parameter instance with default values
V <- StParm(StParmName = "V")
# Create a Structural parameter with Normal type:
V2 <- StParm("V2",
 Type = "Normal",
 ThetaStParm = Theta(Name = "tvV2", InitialEstimates = 0.1))
# Create a Structural parameter instance with covariates:
Cl <- StParm(
 StParmName = "Cl",
 Covariates = Covariate(
 Name = "Period",
 Type = "Occasion",
 State = "Searched",
 Categories = c(1,2),
 Omegas = list(Omega(Name = "nPeriodx1", 2),
 Omega(Name = "nPeriodx2", 3))),
 PMLStructure = "1CFOE")

Table(
 Name = "table01.csv",
 TimesList = numeric(0),
 CovrSet = "",
 WhenDose = "",
 WhenObs = "",
 VariablesList = "",
 KeepSource = FALSE,
 TimeAfterDose = FALSE,
 IRES = FALSE,
 Weight = FALSE,
 IWRES = FALSE,
 Mode = "all",
 ForSimulation = FALSE
)

Name

Character; Name of the generated table.

TimesList

Numeric; Time values for simulation. Applicable for time-based models only. Ignored when keepSource=TRUE.

CovrSet

Character; Vector of covariate names. Simulation point is added when the covariate value is set.

WhenDose

Character or logical; Vector of dosing compartment names. Alternatively if WhenDose == TRUE, triggers are added for all dosepoints for each PMLParametersSet separately; that approach is useful when different models in the set have different dosing compartments. Simulation point is added when the dose value is set.

WhenObs

Character; String of observed variables names. Simulation point is added when the observation value is set.

VariablesList

Character; List of variables from the model for simulation.

KeepSource

Logical; Set to TRUE to keep the number of rows appearing in the table the same as the number of rows in the input dataset.

TimeAfterDose

Set to TRUE to output time after dose.

IRES

Logical; Set to TRUE to output individual residuals. Valid only if WhenObs is specified and ForSimulation==FALSE.

Weight

Logical; Set to TRUE to output the weight of current observation. Valid only if WhenObs is specified and ForSimulation==FALSE.

IWRES

Logical; Set to TRUE to output individual weighted residuals. Valid only if WhenObs is specified and ForSimulation==FALSE.

Mode

Character; The mode of output. Options are all (default), unique, first. Only applicable to non time-based models for the case where only CovrSet is defined or the case where only CovrSet and VariablesList are defined. Since current version supports time-based models only, this argument is not applicable and won't change the output.

ForSimulation

Logical; Set to TRUE if the table should be generated during simulation, otherwise the table will be generated after fitting.

table01 <-
 Table(Name = "table01.csv",
 TimesList = seq(1,3,1),
 CovrSet = "WT",
 WhenDose = "A1",
 WhenObs = "CObs",
 VariablesList = "C",
 KeepSource = FALSE,
 TimeAfterDose = TRUE,
 IRES = TRUE,
 Weight = TRUE,
 IWRES = TRUE,
 ForSimulation = FALSE)

Theta(
 Name = character(),
 InitialEstimates = 1,
 State = "Present",
 Frozen = FALSE,
 StParmName = character(),
 PMLStructure = character()
)

Name

A character string representing the name of the Theta instance.

InitialEstimates

An InitialEstimate() class instance or a numerical value for the initial estimate of the Theta or a numeric vector length three with its elements representing the lower bound, initial estimate.

State

Character specifying the presence of the Theta. Possible values are:

• None The Theta does not exist in the specified PMLStructure.

• Present The Theta exists in the specified PMLStructure (the default)

• Searched The presence of the Theta is searched.

Frozen

A logical value indicating whether the Theta will be estimated or not.

StParmName

A character specifying the corresponding structural parameter name. Used for the Name of current Theta construction if it is not specified as 'tv' + StParmName.

PMLStructure

PML structure current theta belongs to

# Create a new Theta instance with a name 'tvV' and initial value 2 (no bounds)
theta <- Theta(Name = "tvV", InitialEstimates = 2)

add_Covariate(
 PMLParametersSets,
 Name,
 Type = "Continuous",
 StParmNames = NULL,
 State = "Present",
 Direction = "Forward",
 Center = "None",
 Categories = c(),
 PMLStructures = NULL
)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

Name

A character string representing the name of the covariate to be added.

Type

A character specifying the type of the covariate. Possible values are:

• Continuous A covariate can take values on a continuous scale.

• Categorical A covariate can only take a finite number of values.

• Occasion The associated PK parameter may vary within an individual from one event to the next, called interoccasion variability.

StParmNames

Character or character vector specifying names of structural parameters to which covariates should be added. Can be set to NULL or not specified, for such case, covariate will be added to all structural parameters.

State

A character string representing the presence of the covariate on the structural parameters. Possible values are:

• None The covariate does not have an effect on any structural parameter.

• Present The covariate has an effect on the structural parameters (the default).

• Searched The effect of the covariate on structural parameters is searched.

Direction

A character string representing the direction of the Covariate. Options are Forward, Backward, Interpolate. Default is Forward. Interpolate is only applicable to Type == "Continuous".

Center

A character string (None, Mean or Median) or numeric value representing the center of the Covariate. Default is None. Valid only if Type == "Continuous".

Categories

A numeric vector representing the categories (at least two) of the covariate. Applicable only if Type is either Occasion or Categorical. The first category is set to the reference category for categorical covariate.

PMLStructures

Character or character vector specifying names of PML structures to which the covariate will be added. For the naming covention of PMLStructures, see Details section of create_ModelPK() for PK models and create_ModelPD() for PD models.

PMLParametersSets <- create_ModelPK()
PMLParametersSetsWT <-
 add_Covariate(PMLParametersSets,
 Name = "WT",
 Type = "Continuous",
 State = "Present",
 Direction = "Forward",
 Center = 70)
PMLParametersSetsWTCL <-
 add_Covariate(PMLParametersSets = PMLParametersSetsWT,
 Name = "Race",
 Type = "Categorical",
 State = "Searched",
 Direction = "Backward",
 Categories = c(1,2,3),
 StParmNames = "Cl",
 PMLStructure = "PK1IVC")

add_CustomSpace(Spaces, CustomCode)

Spaces

A list of existing spaces.

CustomCode

A character string containing the custom code for the new space.

add_StParm(
 PMLParametersSets,
 StParmName,
 Type = "LogNormal",
 State = "Present",
 ThetaStParm = list(),
 OmegaStParm = list(),
 Covariates = list(),
 PMLStructures = NULL,
 DosepointArgName = character()
)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

StParmName

Character specifying the name of the structural parameter to be added.

Type

Character specifying the type of the structural parameter. Options are

• LogNormal The PML statement of the structural parameter will look like the following:

stparm(V = tvV * wt^dVdwt * exp(nV + nVx0*(Occasion==0) + nVx1*(Occasion==1)))

• LogNormal1 The PML statement of the structural parameter will look like the following:

stparm(V = (tvV + wt*dVdwt) * exp(nV + nVx0*( Occasion==0) + nVx1*( Occasion==1)))

• LogNormal2 The PML statement of the structural parameter will look like the following:

stparm(V = exp(tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occason==1)))

• LogitNormal The PML statement of the structural parameter will look like the following:

stparm(V = ilogit(tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occasion==1)))

• Normal The PML statement of the structural parameter will look like the following:

stparm(V = tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occasion==1))

State

character string that indicates the presence of the structural parameter. Options are:

• None The structural parameter does not exist in the specified PMLStructures.

• Present The structural parameter exists in the specified PMLStructures (the default).

• Searched The presence of the structural parameter is searched.

ThetaStParm

A Theta class instance inside the structural parameter. If not given, the associated Theta will be automatically created with its name set to "tv" + StParmName.

OmegaStParm

An Omega class instance inside the structural parameter. If not given, the associated Omega will be automatically created with its name set to "n" + StParmName

Covariates

A list of covariates (Covariate instances) that should be included in the structural parameter statement.

PMLStructures

Character or character vector specifying names of PML structures to whichthe structural parameter will be added. For the naming convention of PMLStructures, see Details section of get_PMLParametersSets() .

DosepointArgName

Character specifying the name of the argument in the Dosepoint() instance to add/update the associated structural parameter. Options are bioavail, rate, duration, tlag. Not applicable for custom models

PMLParametersSets <-
 get_PMLParametersSets(CompartmentsNumber = c(1, 2, 3))
# add Rate structural parameter for all PMLModels
PMLParametersSetsVModDuration <-
 add_StParm(PMLParametersSets,
 StParmName = "Duration",
 ThetaStParm = Theta("tvD",
 InitialEstimates = 2),
 OmegaStParm = Omega(Name = "nD",
 State = "Searched"),
 DosepointArgName = "duration")

create_CustomSpace(CustomCode = character())

CustomCode

A character string containing the custom code.

create_ModelEmax(
 Baseline = FALSE,
 Fractional = FALSE,
 Inhibitory = FALSE,
 Sigmoid = FALSE,
 ByVector = FALSE,
 ...
)

Baseline

Logical indicating whether the Emax model contains a baseline response. If it is set to TRUE, the new parameter, E0, for baseline response is added to the model. Default is FALSE.

Fractional

Logical indicating whether the Emax model with baseline response is fractional. Applicable only for the Emax models with baseline response, otherwise a warning is given and current parameter is ignored. Default is FALSE.

Inhibitory

Logical indicating whether the model is inhibitory. If it is set to TRUE, the structural parameters 'EC50' and 'Emax' change to 'IC50' (concentration producing 50% of maximal inhibition) and 'Imax'. Default is FALSE.

Sigmoid

Logical indicating whether the model is sigmoidal. If it is set to TRUE, the Hill coefficient, 'Gam', is added to the model. Default is FALSE.

ByVector

Logical indicating whether each element in vectorized argument should be treated as a separate PML structure (i.e. treated as data.frame vectors), TRUE, or as parameters to obtain a pool (i.e. expanded) of PML structures, FALSE. Default is FALSE (one value for a function call).

...

Additional named arguments, including Structural parameters (StParm), Covariates, Dosepoints (for PK models), Thetas and Omegas. See 'Additional arguments' section.

# Get Emax model set with default options
PDParametersSets <- create_ModelEmax()
# Create Emax model set with all possible combinations
# will give a warning since When 'Baseline == FALSE',
# there could be no model with 'Fractional == TRUE'
PDParametersSets <-
 create_ModelEmax(Baseline = TRUE,
 Fractional = c(FALSE, TRUE),
 Inhibitory = c(FALSE, TRUE),
 Sigmoid = c(FALSE, TRUE),
 ByVector = FALSE)

create_ModelPD(
 Type = "Emax",
 Baseline = FALSE,
 Fractional = FALSE,
 Inhibitory = FALSE,
 Sigmoid = FALSE,
 ByVector = FALSE,
 ...
)

Type

Pharmacodynamic model type. Currently, only Emax is supported.

Baseline

Logical indicating whether the Emax model contains a baseline response. If it is set to TRUE, the new parameter, E0, for baseline response is added to the model. Default is FALSE.

Fractional

Logical indicating whether the Emax model with baseline response is fractional. Applicable only for the Emax models with baseline response, otherwise a warning is given and current parameter is ignored. Default is FALSE.

Inhibitory

Logical indicating whether the model is inhibitory. If it is set to TRUE, the structural parameters 'EC50' and 'Emax' change to 'IC50' (concentration producing 50% of maximal inhibition) and 'Imax'. Default is FALSE.

Sigmoid

Logical indicating whether the model is sigmoidal. If it is set to TRUE, the Hill coefficient, 'Gam', is added to the model. Default is FALSE.

ByVector

Logical indicating whether each element in vectorized argument should be treated as a separate PML structure (i.e. treated as data.frame vectors), TRUE, or as parameters to obtain a pool (i.e. expanded) of PML structures, FALSE. Default is FALSE (one value for a function call).

...

Additional named arguments, including Structural parameters (StParm), Covariates, Dosepoints (for PK models), Thetas and Omegas. See 'Additional arguments' section.

# Get PD model set with default options
PDParametersSets <- create_ModelPD(Type = "Emax")
# Create PD model set with all possible combinations
# will give a warning since When 'Baseline == FALSE',
# there could be no model with 'Fractional == TRUE'
PDParametersSets <-
 create_ModelPD(Type = "Emax",
 Baseline = FALSE,
 Inhibitory = c(FALSE, TRUE),
 Sigmoid = c(FALSE, TRUE),
 ByVector = FALSE)

create_ModelPK(
 CompartmentsNumber = 1,
 Absorption = "Intravenous",
 Parameterization = "Clearance",
 Saturation = FALSE,
 EliminationCpt = FALSE,
 FractionExcreted = FALSE,
 ByVector = FALSE,
 ClosedForm = TRUE,
 ...
)
get_PMLParametersSets(
 CompartmentsNumber = 1,
 Absorption = "Intravenous",
 Parameterization = "Clearance",
 Saturation = FALSE,
 EliminationCpt = FALSE,
 FractionExcreted = FALSE,
 ByVector = FALSE,
 ClosedForm = TRUE,
 ...
)

CompartmentsNumber

The number of compartments in the model. Supported embedded models are 1-, 2-, 3-compartments. Default is 1.

Absorption

The absorption type of the model. Supported types are:

• Intravenous (Default) - Dose is given in the main compartment (A1) directly.

• First-Order - Dose is absorbed to the main compartment (A1) from the absorption compartment (Aa) by first-order kinetic.

• Gamma - Dose is absorbed to A1 by Gamma Distributed delay kinetic.

• ⁠Inverse Gaussian⁠ - Dose is absorbed to A1 by Inverse Gaussian Distributed delay kinetic.

• Weibull - Dose is absorbed to A1 by Weibull Distributed delay kinetic.

Parameterization

The parameterization type. Possible options are Clearance - Clearance parameters: Cl, Cl2 to be used and Micro - Micro parameters: Ke, K12, K21 to be used. Default is Clearance.

Saturation

Logical indicating whether saturation should be considered. Default is FALSE.

EliminationCpt

Logical indicating whether elimination compartment should be included. Default is FALSE.

FractionExcreted

Logical indicating whether fraction excreted structural parameter should be included in urinecpt statement: urinecpt(A0 = Cl * C, fe=Fe). Valid only if EliminationCpt == TRUE. Default is FALSE.

ByVector

Logical indicating whether each element in vectorized argument should be treated as a separate PML structure (i.e. treated as data.frame vectors), TRUE, or as parameters to obtain a pool (i.e. expanded) of PML structures, FALSE. Default is FALSE (one value for a function call).

ClosedForm

Logical indicating whether closed forms (cfMicro) should be used when possible. Note that closed forms are not available for the models with elimination compartment, models with saturation or absorption types other than Intravenous or First-Order. The models with interpolated covariates must use ClosedForm == FALSE. Default is TRUE (one value for a function call).

...

Additional named arguments, including Structural parameters (StParm), Covariates, Dosepoints (for PK models), Thetas and Omegas. See 'Additional arguments' section.

# Get PK model set with default options
PMLParametersSets <- create_ModelPK()
#' # Get PK Model search with custom options:
# will create 2 PML Parameters Sets with 2 and 3 compartments,
# with Absorption First-Order and Gamma accordingly:
ModelPKSearch <-
 create_ModelPK(CompartmentsNumber = c(2, 3),
 Parameterization = "Micro",
 Absorption = c("First-Order", "Gamma"),
 ByVector = TRUE,
 ClosedForm = TRUE)
# Next example will create a set of 4 PMLParametersSets:
# a combination of models with 2 and 3 compartments and First-Order and Gamma Absorption
PMLParametersSets <-
 create_ModelPK(CompartmentsNumber = c(2, 3),
 Absorption = c("First-Order", "Gamma"),
 ByVector = FALSE,
 ClosedForm = FALSE)
# Create 2 PML Parameters Sets with elimination compartment and fraction excreted
# and add zero order absorption to the main dosepoint of the PML Structure
# with infusion
PMLParametersSets <-
 create_ModelPK(CompartmentsNumber = 1,
 Absorption = c("Intravenous", "Gamma"),
 EliminationCpt = TRUE,
 FractionExcreted = TRUE,
 duration = StParm(StParmName = "Duration",
 OmegaStParm = Omega(State = "None")),
 PMLStructure = "PK1IVCEF")
# Create 4 PML Parameters Sets, then modify `Cl` structural parameter for all sets,
# with 2 initial estimates sets to be searched,
# add `tlag` as a structural parameter `Tlag` to 1 compartment First-Order PML parameters set,
# change `tvKa` Theta initial estimate,
# change `nV` Omega initial estimate,
# change `CObs` Observation sigmas,
# add structural parameter `Rate` for 1 compartment Weibull Parameters set,
# add `Weight` covariate for all structural parameters to be searched.
PMLParametersSets <-
 create_ModelPK(
 CompartmentsNumber = 1,
 Absorption = c("First-Order", "Weibull"),
 ByVector = FALSE,
 Cl = StParm(
 StParmName = "Cl",
 Type = "LogNormal2",
 ThetaStParm =
 Theta(Name = "tvCl",
 InitialEstimates =
 InitialEstimate(c(-Inf, 0.2, Inf),
 c(0, 3, 10)))
 ),
 tlag = StParm(
 StParmName = "Tlag",
 State = "Searched",
 PMLStructure = "PK1FOC",
 Covariates = list(
 Age = Covariate(
 Name = "Age",
 Type = "Categorical",
 State = "Searched",
 Direction = "Backward",
 Center = "None",
 Categories = c(1, 2, 3)
 )
 )
 ),
 tvKa = Theta(Name = "tvKa", InitialEstimates = 10),
 nV = Omega(Name = "nV", InitialOmega = 0.1),
 CObs = Observation(
 ObservationName = "CObs",
 SigmasChosen = list(
 AdditiveMultiplicative = c(PropPart = 0.1, AddPart = 2),
 Proportional = 1
 )
 ),
 A1 = Dosepoint(
 DosepointName = "A1",
 rate = StParm(StParmName = "Rate"),
 PMLStructure = "PK1WC"
 ),
 Weight = Covariate(
 Name = "Weight",
 State = "Searched",
 Center = "Median"
 )
 )

create_pyDarwinOptions(
 author = "",
 project_name = NULL,
 algorithm = c("GA", "EX", "GP", "RF", "GBRT", "PSO"),
 GA = pyDarwinOptionsGA(),
 PSO = pyDarwinOptionsPSO(),
 random_seed = 11,
 num_parallel = 4,
 num_generations = 6,
 population_size = 4,
 num_opt_chains = 4,
 exhaustive_batch_size = 100,
 crash_value = 99999999,
 penalty = pyDarwinOptionsPenalty(),
 downhill_period = 2,
 num_niches = 2,
 niche_radius = 2,
 local_2_bit_search = TRUE,
 final_downhill_search = TRUE,
 search_omega_blocks = FALSE,
 search_omega_bands = FALSE,
 individual_omega_search = TRUE,
 search_omega_sub_matrix = FALSE,
 max_omega_sub_matrix = 4,
 model_run_timeout = 1200,
 model_run_priority_class = c("below_normal", "normal"),
 postprocess = pyDarwinOptionsPostprocess(),
 keep_key_models = TRUE,
 use_saved_models = FALSE,
 saved_models_file = "{working_dir}/models0.json",
 saved_models_readonly = FALSE,
 remove_run_dir = FALSE,
 remove_temp_dir = TRUE,
 use_system_options = TRUE,
 model_cache = "darwin.MemoryModelCache",
 model_run_man = c("darwin.LocalRunManager", "darwin.GridRunManager"),
 engine_adapter = c("nlme", "nonmem"),
 working_dir = NULL,
 data_dir = NULL,
 output_dir = "{working_dir}/output",
 temp_dir = NULL,
 nlme_dir = "C:/Program Files/Certara/NLME_Engine",
 gcc_dir = "C:/Program Files/Certara/mingw64",
 nmfe_path = NULL,
 rscript_path = file.path(R.home("bin"), "Rscript"),
 nlme_license = NULL,
 generic_grid_adapter = pyDarwinOptionsGridAdapter(),
 ...
)

author

Character string: The name of the author.

project_name

Character string (optional): The name of the project. If not specified, pyDarwin will set its value to the name of the parent folder of the options file.

algorithm

Character string: One of EX, GA, GP, RF, GBRT, PSO. See section Details below for more information.

GA

List: Options specific to the Genetic Algorithm (GA). See pyDarwinOptionsGA() .

PSO

List: Options specific to the Particle Swarm Optimization (PSO). See pyDarwinOptionsPSO() .

random_seed

Positive integer: Seed for random number generation.

num_parallel

Positive integer: Number of models to execute in parallel, i.e., how many threads to create to handle model runs.

num_generations

Positive integer: Number of iterations or generations of the search algorithm to run. Not used/required for EX.

population_size

Positive integer: Number of models to create in every generation. Not used/required for EX.

num_opt_chains

Positive integer: Number of parallel processes to perform the "ask" step (to increase performance). Required only for GP, RF, and GBRT.

exhaustive_batch_size

Positive integer: Batch size for the EX (Exhaustive Search) algorithm.

crash_value

Positive real: Value of fitness or reward assigned when model output is not generated. Should be set larger than any anticipated completed model fitness.

penalty

List: Options specific to the penalty calculation. See pyDarwinOptionsPenalty() .

downhill_period

Integer: How often to run the downhill step. If < 1, no periodic downhill search will be performed.

num_niches

Integer: Used for GA and downhill. A penalty is assigned for each model based on the number of similar models within a niche radius. This penalty is applied only to the selection process (not to the fitness of the model). The purpose is to ensure maintaining a degree of diversity in the population (integer). num_niches is also used to select the number of models that are entered into the downhill step for all algorithms, except EX.

niche_radius

Positive real: The radius of the niches. The niche radius is used to define how similar pairs of models are. This is used to select models for the Local search, as requested, and to calculate the sharing penalty for Genetic Algorithm.

local_2_bit_search

Logical: Whether to perform the two-bit local search. The two-bit local search substantially increases the robustness of the search. All downhill local searches are done starting from num_niches models.

final_downhill_search

Logical: Whether to perform a local search (1-bit and 2-bit) at the end of the global search.

search_omega_blocks

Logical: whether to perform search for block omegas. Used only when engine_adapter == 'nlme'.

search_omega_bands

Logical: whether to perform search for band omegas. Used only when engine_adapter == 'nonmem'.

individual_omega_search

Logical: If set, every search block will be handled individually: each block will have a separate gene and max omega search length (either calculated or set explicitly in the options). If set to FALSE, all search blocks will have the same pattern of block omegas. Default is TRUE.

search_omega_sub_matrix

Logical: set to true to search omega submatrix. Default is FALSE.

max_omega_sub_matrix

Integer: Maximum size of sub matrix to use in search. Default is 4.

model_run_timeout

Positive real: Time (seconds) after which the execution will be terminated, and the crash value assigned.

model_run_priority_class

Character string (Windows only): Priority class for child processes that build and run models, as well as run the R postprocess script. Options are below_normal and normal. below_normal is recommended to maintain user interface responsiveness.

postprocess

List: Options specific to postprocessing. See pyDarwinOptionsPostprocess()

keep_key_models

Logical: Key model is the best model in population (generation). Such models may be a subject of interest when the search is analyzed, so they should be saved separately with all their output. Default is TRUE

use_saved_models

Logical: Whether to restore saved Model Cache from file. Default is FALSE.

saved_models_file

Character string: The file from which to restore Model Cache. Will only have an effect if use_saved_models is set to true. By default, the cache is saved in {working_dir}/models.json and cleared every time the search is started. To use saved runs, rename models.json or copy it to a different location.

saved_models_readonly

Logical: Do not overwrite the saved_models_file content. Default is FALSE.

remove_run_dir

Logical: If TRUE, will delete the entire model run directory, otherwise - only unnecessary files inside it. Default is FALSE.

remove_temp_dir

Logical: Whether to delete the entire temp_dir after the search is finished or stopped. Doesn't have any effect when the search is run on a grid. Default is TRUE.

use_system_options

Logical: Whether to override options with environment-specific values. Default is TRUE.

model_cache

Character string: ModelCache subclass to be used. Currently, there are only darwin.MemoryModelCache and darwin.AsyncMemoryModelCache. You can create your own and use it (e.g., a cache that stores model runs in a database). The name is quite arbitrary and doesn't have any convention/constraints.

model_run_man

Character string: ModelRunManager subclass to be used. Currently, there are only darwin.LocalRunManager and darwin.GridRunManager.

engine_adapter

Character string: ModelEngineAdapter subclass to be used. Currently only nlme (default) and nonmem are available.

working_dir

Character string: The project's working directory, where all the necessary files and folders are created. By default, it is set to ⁠<pyDarwin home>/{project_stem}⁠, where {project_stem} is a file system friendly representation of the project name in a way that it will be easy to manage as a folder name where all non-letters and non-digits are replaced with underscores.

data_dir

Character string: Directory where datasets are located. Must be available for individual model runs. Default in pyDarwin if not given: {project_dir}.

output_dir

Character string: Directory where pyDarwin output will be placed. Default is {working_dir}/output.

temp_dir

Character string: Parent directory for all model runs' run directories, i.e., where all folders for every iteration are located. Default in pyDarwin if not given: {working_dir}/temp.

nlme_dir

Character string: Directory where the NLME Engine is installed/unzipped. Default: ⁠C:/Program Files/Certara/NLME_Engine⁠. Used only when engine_adapter == 'nlme'.

gcc_dir

Character string: Directory where the Mingw-w64 compiler (gcc) is installed. Default: ⁠C:/Program Files/Certara/mingw64⁠ for Windows and gcc version found by ⁠which gcc⁠ on Linux. Used only when engine_adapter == 'nlme'.

nmfe_path

Character string: Directory where NONMEM is installed. Used only when engine_adapter == 'nonmem'.

rscript_path

Character string: Path to the Rscript executable. By default, it is obtained with R.home("bin").

nlme_license

Character string (optional): Path to the license file. If not provided, pyDarwin will set its value to PhoenixLicenseFile (only for current Python session).

generic_grid_adapter

List: Options specific to the grids. See pyDarwinOptionsGridAdapter()

...

Additional parameters: Other arguments not explicitly defined in the function's signature are allowed and will be stored in the options list. See pyDarwin documentation.

# Create pyDarwin options with default values
pyDarwinOptions <- create_pyDarwinOptions()
# Create pyDarwin options with custom author and algorithm
pyDarwinOptions <-
 create_pyDarwinOptions(author = "John Doe",
 algorithm = "PSO")

get_ModelTermsToMap(PMLParametersSets)

PMLParametersSets

An object of class "PMLModels" containing PML model parameters.

# Load your PMLModels object
PMLParametersSets <-
 create_ModelPK(
 Absorption = c("First-Order", "Weibull"),
 CObs = Observation(
 ObservationName = "CObs",
 BQL = TRUE),
 A1 = Dosepoint(
 DosepointName = "A1",
 rate = StParm(StParmName = "Rate")),
 Weight = Covariate(
 Name = "Weight",
 Center = "Median")
)
# Get the model terms to map
terms_to_map <- get_ModelTermsToMap(PMLParametersSets)
print(terms_to_map$Required)
print(terms_to_map$Optional)

list_Covariates(PMLParametersSets, IncludeAll = FALSE, IncludeCustom = TRUE)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

IncludeAll

Logical. Should the names of covariates with None state or covariates inside structural parameters with None state be included or not.

IncludeCustom

Logical. Should the names of covariate, fcovariate and interpolate statements (from the PML code of custom spaces) be included or not. Default is TRUE.

PMLParametersSets <- get_PMLParametersSets()
PMLParametersSets <- add_Covariate(PMLParametersSets,
 Name = "WT")
list_Covariates(PMLParametersSets)

list_Dosepoints(PMLParametersSets, IncludeAll = FALSE, IncludeCustom = TRUE)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

IncludeAll

Logical. Should the names of dosepoints with None state be included or not. Default is FALSE.

IncludeCustom

Logical. Should the names of custom dosepoint and dosepoint2 statements (from the PML code of custom spaces) be included or not. Default is TRUE.

PMLParametersSets <-
 get_PMLParametersSets(
 Absorption = c("First-Order", "Gamma"))
list_Dosepoints(PMLParametersSets)

list_Observations(
 PMLParametersSets,
 IncludeCustom = TRUE,
 ObservationsOnly = TRUE
)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

IncludeCustom

Logical. Should the names of responses (observe, multi, ordinal, count, event and LL) from the PML code of custom spaces be included or not. Default is TRUE.

ObservationsOnly

Logical. If TRUE (default), only the names of observe responses are included in the PML code generated for custom spaces. Non-observed response names (such as multi, ordinal, count, event, and LL) are not included. Ignored if IncludeCustom == FALSE.

PMLParametersSets <-
 create_ModelPK(
 Absorption = c("First-Order", "Gamma"),
 EliminationCpt = c(TRUE, FALSE))
list_Observations(PMLParametersSets)

list_Omegas(PMLParametersSets, IncludeAll = FALSE, IncludeCustom = TRUE)

PMLParametersSets

PMLModels class instance or an element (one PML structure) of this class or StParm class.

IncludeAll

Logical. Whether should the omega names to be inlcuded from structural parameters, covariates or omegas with a State == 'None'.

IncludeCustom

Logical. Should the names of custom ranef statements (from the PML code of custom spaces) be included or not. Default is TRUE.

PMLParametersSets <- create_ModelPK()
list_Omegas(PMLParametersSets)

list_StParms(PMLParametersSets, IncludeAll = FALSE, IncludeCustom = TRUE)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

IncludeAll

Logical. Should the names of structural parameters with None state be included or not. Default is FALSE.

IncludeCustom

Logical. Should the names of custom stparm statements (from the PML code of custom spaces) be included or not. Default is TRUE.

PMLParametersSets <- get_PMLParametersSets()
list_StParms(PMLParametersSets)

list_Thetas(PMLParametersSets, IncludeAll = FALSE, IncludeCustom = TRUE)

PMLParametersSets

PMLModels class instance or an element (one PML structure) of this class or StParm class.

IncludeAll

Logical. Whether should the Theta names to be inlcuded from structural parameters, covariates or thetas with a State == 'None'.

IncludeCustom

Logical. Should the names of custom theta statements (from the PML code of custom spaces) be included or not. Default is TRUE.

PMLParametersSets <- create_ModelPD()
list_Thetas(PMLParametersSets)

modify_Dosepoint(
 PMLParametersSets,
 DosepointName,
 tlag,
 bioavail,
 duration,
 rate,
 PMLStructures = NULL
)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

DosepointName

A character string giving the name of the Dosepoint.

tlag

An optional structural parameter giving the time lag for the doses coming into current Dosepoint.

bioavail

An optional structural parameter giving the bioavailability of the doses coming into current Dosepoint.

duration

An optional structural parameter giving the duration of infusion for the doses coming into current Dosepoint.

rate

An optional structural parameter giving the rate of infusion for the doses coming into current Dosepoint.

PMLStructures

Character or character vector specifying names of PML structures in which the dosepoint statement will be modified. For the naming convention of PMLStructures, see Details section of get_PMLParametersSets() .

PMLParametersSets <-
 get_PMLParametersSets(CompartmentsNumber = c(1, 2, 3))
# update structural paramter type
PMLParametersSetsVMod <-
 modify_Dosepoint(PMLParametersSets,
 DosepointName = "A1",
 tlag = StParm(StParmName = "Tlag",
 State = "Searched"))

modify_Observation(
 PMLParametersSets,
 ObservationName,
 SigmasChosen,
 BQL,
 BQLValue,
 Frozen,
 ResetObs,
 Covariates,
 PMLStructures = NULL
)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

ObservationName

A character string giving the name of the Observation.

SigmasChosen

a Sigmas class instance or a list specifying the chosen sigma values for different error models. 0s are treated as no values. Inside Observation class it is transormed and kept as Sigmas class. The list could contain the following error models:

• Additive The additive error sigma value.

• LogAdditive The log-additive error sigma value.

• Proportional The proportional error sigma value.

• AdditiveMultiplicative A numeric vector specifying the additive and multiplicative parts for the additive-multiplicative error model. The vector should have names PropPart and AddPart.

• MixRatio A numeric vector specifying the proportional and additive parts for the mix-ratio error model. The vector should have names PropPart and AddPart.

• Power A numeric vector specifying the standard deviation and power parts for the power error model. The vector should have names StdevPart and PowerPart.

BQL

A logical value indicating whether the dataset contains BQL values and they should be taken into account (M3 method).

BQLValue

An optional numeric positive value of static LLOQ. Applicable only when BQL argument is TRUE. Any observed value less than or equal to that LLOQ value is treated as censored.

Frozen

A logical value indicating if the standard deviation (Stdev) is frozen.

ResetObs

A logical value indicating if the Observation variable should be reset to 0 after observation (doafter={A0=0;}). Applicable for elimination compartment.

Covariates

A list of covariates (Covariate instances) that should be included in the model, but not linked to any of structural parameters. Used with "Emax" PD models ('C' covariate is added automatically when creating a new model, but should be added manually when modifying the model).

PMLStructures

Character or character vector specifying names of PML structures in which the observation will be modified. For the naming convention of PMLStructures, see Details section of create_ModelPK() for PK models and create_ModelPD() for PD models.

PMLParametersSets <-
 create_ModelPK(CompartmentsNumber = c(1, 2, 3))
# update structural paramter type
PMLParametersSetsVMod <-
 modify_Observation(
 PMLParametersSets,
 ObservationName = "CObs",
 SigmasChosen = Sigmas(Proportional = 0,
 AdditiveMultiplicative =
 list(PropPart = 0.1, AddPart = 10)))
print(PMLParametersSetsVMod)

modify_Omega(
 PMLParametersSets,
 Name,
 InitialOmega,
 State,
 Frozen,
 PMLStructures = NULL
)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

Name

A character string specifying the name of the Omega.

InitialOmega

Numeric specifying the initial value of the Omega. Default value is 1.

State

Character specifying the presence of the Omega. Possible values are:

• None The Omega does not exist in the specified PMLStructures.

• Present The Omega exists in the specified PMLStructures (the default).

• Searched The presence of the Omega is searched.

Frozen

A logical value indicating whether the Omega is frozen or not.

PMLStructures

Character or character vector specifying names of PML structures in which the Omega will be modified. For the naming convention of PMLStructures, see Details section of create_ModelPK() for PK models and create_ModelPD() for PD models.

PMLParametersSets12 <- create_ModelPK(CompartmentsNumber = c(1, 2))
# Modify an Omega parameter named "nV" with new Initial Estimate and
# Frozen flag
PMLParametersSets12Mod1 <-
 modify_Omega(PMLParametersSets12,
 Name = "nV",
 InitialOmega = 0.3,
 State = "Present",
 Frozen = TRUE,
 PMLStructures = "PK1IVC")
print(PMLParametersSets12Mod1)

modify_StParm(
 PMLParametersSets,
 StParmName,
 Type = "LogNormal",
 State = "Present",
 ThetaStParm,
 OmegaStParm,
 Covariates,
 PMLStructures = NULL
)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

StParmName

Character specifying the name of the structural parameter to be modified.

Type

Character specifying the type of the structural parameter. Options are

• LogNormal The PML statement of the structural parameter will look like the following:

stparm(V = tvV * wt^dVdwt * exp(nV + nVx0*(Occasion==0) + nVx1*(Occasion==1)))

• LogNormal1 The PML statement of the structural parameter will look like the following:

stparm(V = (tvV + wt*dVdwt) * exp(nV + nVx0*( Occasion==0) + nVx1*( Occasion==1)))

• LogNormal2 The PML statement of the structural parameter will look like the following:

stparm(V = exp(tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occason==1)))

• LogitNormal The PML statement of the structural parameter will look like the following:

stparm(V = ilogit(tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occasion==1)))

• Normal The PML statement of the structural parameter will look like the following:

stparm(V = tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occasion==1))

State

character string that indicates the presence of the structural parameter. Options are:

• None The structural parameter does not exist in the specified PMLStructures.

• Present The structural parameter exists in the specified PMLStructures (the default).

• Searched The presence of the structural parameter is searched.

ThetaStParm

A Theta class instance inside the structural parameter. If not given, the associated Theta will be automatically created with its name set to "tv" + StParmName.

OmegaStParm

An Omega class instance inside the structural parameter. If not given, the associated Omega will be automatically created with its name set to "n" + StParmName

Covariates

A list of covariates (Covariate instances) that should be included in the structural parameter statement.

PMLStructures

Character or character vector specifying names of PML structures to whichthe structural parameter will be added. For the naming convention of PMLStructures, see Details section of get_PMLParametersSets() .

PMLParametersSets <-
 get_PMLParametersSets(CompartmentsNumber = c(1, 2, 3))
# update structural parameter type
PMLParametersSetsVMod <-
 modify_StParm(PMLParametersSets,
 StParmName = "V",
 Type = "LogitNormal")

modify_StParmCustom(
 PMLParametersSets,
 StParmName,
 Type,
 State,
 ThetaStParm,
 OmegaStParm,
 Covariates,
 PMLStructures = NULL
)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

StParmName

Character specifying the name of the structural parameter to be added.

Type

Character specifying the type of the structural parameter. Options are

• LogNormal The PML statement of the structural parameter will look like the following:

stparm(V = tvV * wt^dVdwt * exp(nV + nVx0*(Occasion==0) + nVx1*(Occasion==1)))

• LogNormal1 The PML statement of the structural parameter will look like the following:

stparm(V = (tvV + wt*dVdwt) * exp(nV + nVx0*( Occasion==0) + nVx1*( Occasion==1)))

• LogNormal2 The PML statement of the structural parameter will look like the following:

stparm(V = exp(tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occason==1)))

• LogitNormal The PML statement of the structural parameter will look like the following:

stparm(V = ilogit(tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occasion==1)))

• Normal The PML statement of the structural parameter will look like the following:

stparm(V = tvV + wt*dVdwt + nV + nVx0*(Occasion==0) + nVx1*(Occasion==1))

State

character string that indicates the presence of the structural parameter. Options are:

• None The structural parameter does not exist in the specified PMLStructures.

• Present The structural parameter exists in the specified PMLStructures (the default).

• Searched The presence of the structural parameter is searched.

ThetaStParm

A Theta class instance inside the structural parameter. If not given, the associated Theta will be automatically created with its name set to "tv" + StParmName.

OmegaStParm

An Omega class instance inside the structural parameter. If not given, the associated Omega will be automatically created with its name set to "n" + StParmName

Covariates

A list of covariates (Covariate instances) that should be included in the structural parameter statement.

PMLStructures

Character or character vector specifying names of PML structures to whichthe structural parameter will be added. For the naming convention of PMLStructures, see Details section of get_PMLParametersSets() .

# Modify the custom structural parameter 'Cl':
OneCpt_CustomCode <-
 paste0(
 "\nderiv(A1 = - Cl * C)",
 "\ndosepoint(A1)",
 "\ndosepoint2(A1, tlag = 12)",
 "\nC = A1 / V",
 "\nerror(CEps = 0.01)",
 "\nobserve(CObs = C + CEps * sqrt(1 + C^2 * (CMultStdev/sigma())^2), bql = 0.01)",
 "\nstparm(V = tvV * exp(nV))",
 "\nstparm(Cl = tvCl * exp(nCl))",
 "\nstparm(CMultStdev = tvCMultStdev)",
 "\nfixef(tvV = c(, 5, ))",
 "\nfixef(tvCl = c(, 1, ))",
 "\nfixef(tvCMultStdev = c(, 0.1, ))",
 "\nranef(diag(nV) = c(1))",
 "\nranef(diag(nCl) = c(1))\n"
 )
OneCpt_CustomCode <-
 modify_StParmCustom(
 create_CustomSpace(OneCpt_CustomCode),
 StParmName = "Cl",
 Type = "Normal")

modify_Theta(
 PMLParametersSets,
 Name,
 InitialEstimates,
 Frozen,
 PMLStructures = NULL
)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

Name

Character specifying the name of the Theta to be modified.

InitialEstimates

An InitialEstimate() class instance or a numerical value for the initial estimate of the Theta or a numeric vector length three with its elements representing the lower bound, initial estimate.

Frozen

A logical value indicating whether the Theta will be estimated or not.

PMLStructures

Character or character vector specifying names of PML structures in which the Theta parameter will be modified. For the naming convention of PMLStructures, see Details section of create_ModelPK() for PK models and create_ModelPD() for PD models..

PMLParametersSets <- create_ModelPK(CompartmentsNumber = c(1, 2))
# Modify a Theta parameter named "tvV" with new Initial Estimates and
# Frozen flag
PMLParametersSetsMod1 <-
 modify_Theta(PMLParametersSets,
 Name = "tvV",
 Frozen = TRUE,
 InitialEstimates = 0.3)
print(PMLParametersSetsMod1)
PMLParametersSetsMod2 <-
 add_StParm(PMLParametersSets = PMLParametersSetsMod1,
 StParmName = "Duration",
 State = "Searched",
 PMLStructures = "PK2IVC",
 DosepointArgName = "duration")
PMLParametersSetsMod3 <-
 modify_Theta(PMLParametersSets = PMLParametersSetsMod2,
 Name = "tvDuration",
 InitialEstimates = c(2, 4, Inf))
print(PMLParametersSetsMod3)

## S3 method for class 'CustomSpace'
output(x, ...)

x

A CustomSpace object.

...

Additional arguments (not used).

pyDarwinOptionsGA(
 elitist_num = 2,
 crossover_rate = 0.95,
 mutation_rate = 0.95,
 sharing_alpha = 0.1,
 selection = "tournament",
 selection_size = 2,
 crossover_operator = "cxOnePoint",
 mutate = "flipBit",
 attribute_mutation_probability = 0.1,
 niche_penalty = 20
)

elitist_num

A positive integer specifying the number of best models from any generation to carry over, unchanged, to the next generation. Functions like the Hall of Fame in DEAP. Default: 2

crossover_rate

A real value (between 0.0 and 1.0) specifying the fraction of mating pairs that will undergo crossover. Default: 0.95

mutation_rate

A real value (between 0.0 and 1.0) specifying the probability that at least one bit in the genome will be "flipped", 0 to 1, or 1 to 0. Default: 0.95

sharing_alpha

A real value specifying the parameter of the niche penalty calculation. Default: 0.1

selection

A string specifying the selection algorithm for the GA. Currently, only "tournament" is available. Default: "tournament"

selection_size

A positive integer specifying the number of "parents" to enter in the selection. 2 is highly recommended, experience with other values is very limited. Default: 2

crossover_operator

A string specifying the algorithm for crossover. Only "cxOnePoint" (single-point crossover) is available. Default: "cxOnePoint"

mutate

A string specifying the algorithm for mutation. Currently, only "flipBit" is available. Default: "flipBit"

attribute_mutation_probability

A real value specifying the probability of any bit being mutated (real value between 0.0 and 1.0). Default: 0.1

niche_penalty

A positive real value used for the calculation of the crowding penalty. The niche penalty is calculated by first finding the "distance matrix", the pair-wise Mikowski distance from the present model to all other models. The "crowding" quantity is then calculated as the sum of: (distance/niche_radius)^sharing_alpha for all other models in the generation for which the Mikowski distance is less than the niche radius. Finally, the penalty is calculated as: exp((crowding-1)*niche_penalty)-1. The objective of using a niche penalty is to maintain diversity of models, to avoid premature convergence of the search by penalizing when models are too similar to other models in the current generation. Default: 20

# Create GA options with default values
options <- pyDarwinOptionsGA()
# Create GA options with custom values
options <-
 pyDarwinOptionsGA(elitist_num = 4,
 crossover_rate = 0.9,
 mutation_rate = 0.8,
 sharing_alpha = 0.2)

pyDarwinOptionsGridAdapter(
 python_path = "~/darwin/venv/bin/python",
 submit_search_command = paste("qsub -b y -cwd -o {project_stem}_out.txt",
 "-e {project_stem}_err.txt -N '{project_name}'"),
 submit_command = paste("qsub -b y -o {results_dir}/{run_name}.out",
 "-e {results_dir}/{run_name}.err -N {job_name}"),
 submit_job_id_re = "Your job (\\w+) \\(\".+?\"\\) has been submitted",
 poll_command = "qstat -s z",
 poll_job_id_re = "^\\s+(\\w+)",
 poll_interval = 10,
 delete_command = "qdel {project_stem}-*"
)

python_path

Required. Path to Python interpreter, preferably to the instance of the interpreter located in the virtual environment where pyDarwin is deployed. The path must be available to all grid nodes that run jobs.

submit_search_command

Required. A command that submits a search job to the grid queue. This command is used for the entire search.

submit_command

Required. A command that submits individual runs to the grid queue. The actual command submitted to the queue is constructed by pyDarwin. It should not include ⁠<python_path> -m darwin.run_model⁠.

submit_job_id_re

Required. A regular expression pattern to extract the job ID after submission. The job ID must be captured with the first capturing group.

poll_command

Required. A command that retrieves finished jobs from the grid controller. If the controller/setup allows to specify ids/patterns in polling commands, do it. Otherwise, all finished jobs should be polled using commands ⁠qstat -s z⁠.

poll_job_id_re

Required. A regular expression pattern to find a job ID in every line of the poll_command output. Similar to submit_job_id_re.

poll_interval

Optional. How often to poll jobs (in seconds). Default is 10 seconds.

delete_command

Optional. A command that deletes all unfinished jobs related to the search when you stop it. It may delete all of them by ID (e.g., ⁠qdel {job_ids}⁠) or by mask (e.g., ⁠qdel {project_stem}-*⁠)..

grid_options <- pyDarwinOptionsGridAdapter(
 python_path = "~/darwin/venv/bin/python",
 submit_search_command =
 "qsub -b y -cwd -o {project_stem}_out.txt -e {project_stem}_err.txt -N '{project_name}'",
 submit_command =
 "qsub -b y -o {results_dir}/{run_name}.out -e {results_dir}/{run_name}.err -N {job_name}",
 submit_job_id_re = "Your job (\\w+) \\(\".+?\"\\) has been submitted",
 poll_command = "qstat -s z",
 poll_job_id_re = "^\\s+(\\w+)",
 poll_interval = 10,
 delete_command = "qdel {project_stem}-*"
)

pyDarwinOptionsPSO(
 inertia = 0.4,
 cognitive = 0.5,
 social = 0.5,
 neighbor_num = 20,
 p_norm = 2,
 break_on_no_change = 5
)

inertia

A real value specifying the particle coordination movement as it relates to the previous velocity (commonly denoted as w). Default: 0.4

cognitive

A real value specifying the particle coordination movement as it relates to its own best known position (commonly denoted as c1). Default: 0.5

social

A real value specifying the particle coordination movement as it relates to the current best known position across all particles (commonly denoted as c2). Default: 0.5

neighbor_num

A positive integer specifying the number of neighbors that any particle interacts with to determine the social component of the velocity of the next step. A smaller number of neighbors results in a more thorough search (as the neighborhoods tend to move more independently, allowing the swarm to cover a larger section of the total search space) but will converge more slowly. Default: 20

p_norm

A positive integer specifying the Minkowski p-norm to use. A value of 1 is the sum-of-absolute values (or L1 distance) while 2 is the Euclidean (or L2) distance. Default: 2

break_on_no_change

A positive integer specifying the number of iterations used to determine whether the optimization has converged. Default: 5

# Create PSO options with default values
options <- pyDarwinOptionsPSO()
# Create PSO options with custom values
options <- pyDarwinOptionsPSO(inertia = 0.2,
 cognitive = 0.8,
 social = 0.7,
 neighbor_num = 10)

pyDarwinOptionsPenalty(
 theta = 10,
 omega = 10,
 sigma = 10,
 convergence = 100,
 covariance = 100,
 correlation = 100,
 condition_number = 100,
 non_influential_tokens = 1e-05
)

theta

numeric: Penalty added to fitness/reward for each estimated THETA. A value of 3.84 corresponds to a hypothesis test with 1 df and p < 0.05 (for nested models), and a value of 2 for 1 df corresponds to the Akaike information criterion. Default: 10

omega

numeric: Penalty added to fitness/reward for each estimated OMEGA element. Default: 10

sigma

numeric: Penalty added to fitness/reward for each estimated SIGMA element. Default: 10

convergence

numeric: Penalty added to fitness/reward for failing to converge. Default: 100

covariance

numeric: Penalty added to fitness/reward for failing the covariance step (real number). If a successful covariance step is important, this can be set to a large value (e.g., 100), otherwise, set to 0. Default: 100

correlation

numeric: Penalty added to fitness/reward if any off-diagonal element of the correlation matrix of estimates has an absolute value > 0.95 (real number). This penalty will be added if the covariance step fails or is not requested. Default: 100

condition_number

numeric: Penalty added if the covariance step fails or is not requested, e.g., PRINT=E is not included in $COV. Additionally, if the covariance is successful and the condition number of the covariance matrix is > 1000, then this penalty is added to the fitness/reward. Default: 100

non_influential_tokens

numeric: Penalty added to fitness/reward if any tokens do not influence the control file (relevant for nested tokens). Should be very small (e.g., 0.0001), as the purpose is only for the model with non-influential tokens to be slightly worse than the same model without the non-influential token(s) to break a tie. Default: 0.00001

# Create penalty options with default values
penalty_options <- pyDarwinOptionsPenalty()
# Create penalty options with custom values
penalty_options_custom <-
 pyDarwinOptionsPenalty(theta = 3.84,
 omega = 8,
 sigma = 6,
 convergence = 50,
 covariance = 80,
 correlation = 60,
 condition_number = 70,
 non_influential_tokens = 0.0001)

pyDarwinOptionsPostprocess(
 use_r = FALSE,
 post_run_r_code = "{project_dir}/simplefunc.R",
 r_timeout = 30,
 use_python = FALSE,
 post_run_python_code = "{project_dir}/simplefunc.py"
)

use_r

Logical: Whether to use R for postprocessing. If set to TRUE, R will be used to execute the post-processing script specified in post_run_r_code. Default: FALSE.

post_run_r_code

Character: The file path to the R script that contains post-processing code. This script will be executed after the pyDarwin optimization process finishes. It can perform additional analysis or manipulations on the generated results.

r_timeout

Numeric: The time limit (in seconds) for the execution of the post-processing R script. If the R script takes longer to execute than this timeout value, it will be terminated. Default: 30

use_python

Logical: Whether to use Python for postprocessing. If set to TRUE, Python will be used to execute the post-processing script specified in post_run_python_code. Default: FALSE

post_run_python_code

Character: The file path to the Python script that contains post-processing code. This script will be executed after the pyDarwin optimization process finishes. It can perform additional analysis or manipulations on the generated results. Default: {project_dir}/simplefunc.py

# Create postprocess options with default values
postprocess_options <- pyDarwinOptionsPostprocess()
# Create postprocess options with custom values
postprocess_options_custom <-
 pyDarwinOptionsPostprocess(use_r = TRUE,
 post_run_r_code = "{project_dir}/postprocess.R",
 r_timeout = 60,
 use_python = TRUE,
 post_run_python_code = "{project_dir}/postprocess.py")

remove_Covariate(
 PMLParametersSets,
 Name,
 StParmNames = NULL,
 PMLStructures = NULL
)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

Name

Character specifying the name of the covariate to be removed.

StParmNames

Character or character vector specifying names of structural parameters from which the covariate will be removed. Can be set to NULL or not specified, for such case the covariate will be removed from all structural parameters.

PMLStructures

Character or character vector specifying names of PML structures from which the covariate will be removed. For the naming convention of PMLStructures, see Details section of see details section of get_PMLParametersSets() .

PMLParametersSets <- get_PMLParametersSets()
PMLParametersSetsWT <-
 add_Covariate(PMLParametersSets,
 Name = "WT",
 Type = "Continuous",
 State = "Present",
 Direction = "Forward",
 Center = 70)
PMLParametersSetsVonly <-
 remove_Covariate(PMLParametersSets = PMLParametersSetsWT,
 Name = "WT",
 StParmNames = "Cl")

remove_Observation(PMLParametersSets, ObservationName, PMLStructures = NULL)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

ObservationName

A character string giving the name of the Observation.

PMLStructures

Character or character vector specifying names of PML structures from which the observation will be removed. For the naming convention of PMLStructures, see Details section of create_ModelPK() for PK models and create_ModelPD() for PD models.

PMLParametersSets <-
 create_ModelPK(
 CompartmentsNumber = c(2, 3),
 Parameterization = "Micro",
 Absorption = c("First-Order", "Gamma"),
 ByVector = TRUE,
 ClosedForm = TRUE,
 EliminationCpt = TRUE)
remove_Observation(PMLParametersSets,
 ObservationName = "A0Obs",
 PMLStructures = "PK3GME")

remove_StParm(PMLParametersSets, StParmName, PMLStructures = NULL)

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

StParmName

character specifying the name for the structural parameter to be removed.

PMLStructures

Character or character vector specifying names of PML structures from which the structural parameter will be removed. For the naming convention of PMLStructures, see Details section of get_PMLParametersSets() .

PMLParametersSets <- get_PMLParametersSets(CompartmentsNumber = c(1, 2))
PMLParametersSetsDuration <-
 add_StParm(PMLParametersSets,
 StParmName = "Duration",
 State = "Searched",
 DosepointArgName = "duration")
PMLParametersSetsDuration1CptOnly <-
 remove_StParm(PMLParametersSetsDuration,
 StParmName = "Duration",
 PMLStructures = "PK2IVC")

run_pyDarwin(
 InterpreterPath,
 Flags = c("-u", "-m"),
 DirectoryPath = ".",
 TemplatePath = "template.txt",
 TokensPath = "tokens.json",
 OptionsPath = "options.json",
 Wait = TRUE
)

InterpreterPath

Path to the Python interpreter executable.

Flags

Flags to pass to the Python interpreter. Refer to Python documentation for details. Note that -m is essential (runs library module as a script and terminates option list).

DirectoryPath

Optional path to the directory containing template file, tokens file and options file. If that argument is given, it overrides the paths of TemplatePath, TokensPath, OptionsPath with warning. Default is current working directory.

TemplatePath

Path to the template file.

TokensPath

Path to the tokens JSON file.

OptionsPath

Path to the options JSON file.

Wait

Logical. If TRUE, the function waits for the search process to complete and returns the results. If FALSE, the process is launched and exits immediately.

## Not run: 
result <- run_pyDarwin(
 InterpreterPath = "~/darwin/venv/bin/python",
 DirectoryPath = "~/project_folder",
 TemplatePath = "template.txt",
 TokensPath = "tokens.json",
 OptionsPath = "options.json"
)
## End(Not run)

specify_EngineParams(
 sort = FALSE,
 ODE = c("MatrixExponent", "DVERK", "DOPRI5", "AutoDetect", "Stiff"),
 rtolODE = 1e-06,
 atolODE = 1e-06,
 maxStepsODE = 50000L,
 numIterations = 1000L,
 method = c("FOCE-ELS", "QRPEM", "Laplacian", "Naive-Pooled", "FOCE-LB", "IT2S-EM",
 "FO"),
 stdErr = c("Sandwich", "Auto-Detect", "Hessian", "Fisher-Score", "None"),
 isCentralDiffStdErr = TRUE,
 stepSizeStdErr = 0.01,
 numIntegratePtsAGQ = 1L,
 numIterNonParametric = 0L,
 allowSyntheticGradient = FALSE,
 numIterMAPNP = 0L,
 numRepPCWRES = 0L,
 stepSizeLinearize = 0.002,
 numDigitLaplacian = 7L,
 numDigitBlup = 13L,
 mapAssist = 0L,
 iSample = 300L,
 iAcceptRatio = 0.1,
 impDist = c("Normal", "DoubleExponential", "Direct", "T", "Mixture-2", "Mixture-3"),
 tDOF = 4L,
 numSampleSIR = 10L,
 numBurnIn = 0L,
 freezeOmega = FALSE,
 MCPEM = FALSE,
 runAllIterations = FALSE,
 scramble = c("Owen", "Tezuka-Faur", "None")
)

sort

Logical; Specifying whether or not to sort the input data by subject and time values. Default is TRUE.

ODE

Character; Specifying the solver used to numerically solve Ordinary Differential Equations (ODEs). Options are

• MatrixExponent (the default),

• DVERK,

• DOPRI5,

• AutoDetect,

• Stiff.

Note: both DVERK and DOPRI5 are non-stiff solvers. NLME will automatically switches to DVERK if ODEs are nonlinear.

rtolODE

Numeric; Specifying relative tolerance for the ODE solver. Not applicable when ODE == MatrixExponent.

atolODE

Numeric; Specifying absolute tolerance for the ODE solver.

maxStepsODE

Numeric; Specifying maximum number of allowable steps or function evaluations for the ODE solver.

numIterations

Numeric; Specifying maximum number of iterations for estimation.

method

Character; Specifying engine method for estimation. Options are:

• FOCE-ELS (the default),

• QRPEM,

• Laplacian,

• Naive-Pooled,

• FOCE-LB,

• IT2S-EM,

• FO.

Note: if model involves any discontinuous observed variable (e.g., count data) or BQL data, NLME will switch from default method FOCE-ELS to Laplacian.

stdErr

Character; Specifying method for standard error computations. Options are:

• Auto-Detect (the default),

• Sandwich,

• Hessian,

• Fisher-Score,

• None.

Here None means that standard error calculations are not performed. Since when method = QRPEM only Fisher-Score standard error type is available in NLME, any selected option except None will reset to stdErr = "Fisher-Score".

isCentralDiffStdErr

Logical; Default TRUE uses central difference for stdErr calculations. Set to FALSE for forward difference method.

stepSizeStdErr

Numeric; Specifying the step size used for stdErr calculations.

numIntegratePtsAGQ

Numeric; Specifying the number of integration points for adaptive Gaussian quadrature (AGQ) algorithm. Only applicable to models with method set to either FOCE-ELS or Laplacian.

numIterNonParametric

Numeric; Specifying the number of iterations to perform non-parametric estimation. Only applicable when method is not set to Naive-Pooled (otherwise ignored).

allowSyntheticGradient

Logical, Set to TRUE to use synthetic gradient during the estimation process. Only applicable to population models when method is not set to Naive-Pooled (otherwise ignored).

numIterMAPNP

Numeric; Specifying the number of iterations to perform Maximum A Posterior (MAP) initial Naive Pooling (NP) run before estimation. Only applicable to population models when method is not set to Naive-Pooled (otherwise ignored).

numRepPCWRES

Numeric; Specifying the number of replicates to generate the PCWRES after the simple estimation. Only applicable to population models when method is not set to Naive-Pooled (otherwise ignored).

stepSizeLinearize

Numeric; Specifying the step size used for numerical differentiation when linearizing the model function during the estimation process.

numDigitLaplacian

Numeric; Specifying the number of significant decimal digits for the Laplacian/ELS algorithm to use to reach convergence.

numDigitBlup

Numeric; Specifying the number of significant decimal digits for the individual estimation to use to reach convergence.

mapAssist

Numeric; Specifying the period used to perform MAP assistance (mapAssist = 0 means that MAP assistance is not performed). Only applicable when method == "QRPEM".

iSample

Numeric; Specifying the number of samples. Only applicable when method == "QRPEM".

iAcceptRatio

Numeric; Specifying the acceptance ratio. Only applicable when method == "QRPEM".

impDist

Character; Specifying the distribution used for important sampling, and options are

• Normal (the default),

• DoubleExponential,

• Direct,

• T,

• Mixture-2,

• Mixture-3.

Only applicable to the model with method = "QRPEM".

tDOF

Numeric; Specifying the degree of freedom (allowed value is between 3 and 30) for T distribution. Only applicable when method =="QRPEM" and impDist == "T".

numSampleSIR

Numeric; Specifying the number of samples per subject used in the Sampling Importance Re-Sampling (SIR) algorithm to determine the number of SIR samples taken from the empirical discrete distribution that approximates the target conditional distribution. Only applicable to population models with method = "QRPEM".

numBurnIn

Numeric; Specifying the number of burn-in iterations to perform at startup to adjust certain internal parameters. Only applicable to population models with method = "QRPEM".

freezeOmega

Logical; Set to TRUE to freeze Omega but not Theta for the number of iterations specified in the numBurnIn. Only applicable to population models with method = "QRPEM".

MCPEM

Logical; Set to TRUE to use Monte-Carlo sampling instead of Quasi-Random. Only applicable to population models with method = "QRPEM".

runAllIterations

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

scramble

Character; Specifying the quasi-random scrambling method to use, and options are

• Owen (the default),

• Tezuka-Faur,

• None.

Only applicable to population models with method = "QRPEM".

# default
EstArgs <- specify_EngineParams()
# QRPEM method
EstArgs <-
 specify_EngineParams(
 sort = TRUE,
 ODE = "DVERK",
 rtolODE = 1e-5,
 atolODE = 1e-5,
 maxStepsODE = 6000,
 numIterations = 100,
 method = "QRPEM",
 numIterMAPNP = 3,
 stdErr = "Fisher-Score",
 isCentralDiffStdErr = FALSE,
 iSample = 350,
 impDist = "Mixture-2",
 scramble = "Tezuka-Faur")

specify_SimParams(
 numReplicates = 100L,
 seed = 1234L,
 sort = FALSE,
 ODE = c("MatrixExponent", "DVERK", "DOPRI5", "AutoDetect", "Stiff"),
 rtolODE = 1e-06,
 atolODE = 1e-06,
 maxStepsODE = 50000L
)

numReplicates

Integer; Number of replicates to simulate the model

seed

Integer; Random number generator seed

sort

Logical; Specifying whether or not to sort the input data by subject and time values. Default is TRUE.

ODE

Character; Specifying the solver used to numerically solve Ordinary Differential Equations (ODEs). Options are

• MatrixExponent (the default),

• DVERK,

• DOPRI5,

• AutoDetect,

• Stiff.

Note: both DVERK and DOPRI5 are non-stiff solvers. NLME will automatically switches to DVERK if ODEs are nonlinear.

rtolODE

Numeric; Specifying relative tolerance for the ODE solver. Not applicable when ODE == MatrixExponent.

atolODE

Numeric; Specifying absolute tolerance for the ODE solver.

maxStepsODE

Numeric; Specifying maximum number of allowable steps or function evaluations for the ODE solver.

SimArgs1 <- specify_SimParams()
SimArgs2 <-
 specify_SimParams(
 numReplicates = 100,
 seed = 1,
 ODE = "DVERK")

stop_pyDarwin(
 InterpreterPath,
 Flags = c("-u", "-m"),
 ForceStop = FALSE,
 DirectoryPath = "."
)

InterpreterPath

Path to the Python interpreter executable.

Flags

Flags to pass to the Python interpreter. Refer to Python documentation for details. Note that -m is essential (runs library module as a script and terminates option list).

ForceStop

Logical. If TRUE, -f flag is added to force stop search immediately.- Default is FALSE.

DirectoryPath

the DirectoryPath argument of run_pyDarwin() or the parent folder of options file passed to that function. Default is current working directory.

## Not run: 
stop_pyDarwin(
 InterpreterPath = "~/darwin/venv/bin/python",
 DirectoryPath = "~/project_folder")
## End(Not run)

write_ModelTemplateTokens(
 TemplateFilePath = "template.txt",
 TokensFilePath = "tokens.json",
 Description = "",
 Author = "",
 DataFilePath,
 DataMapping = NULL,
 ColDef = "",
 PMLParametersSets,
 EstArgs = specify_EngineParams(),
 SimArgs = "",
 Tables = list(),
 AppendixRows = "",
 OmegaSearchBlocks = list()
)

TemplateFilePath

TemplateFilePath NLME template file path to be written (usually txt).

TokensFilePath

json file path to be written (usually json).

Description

A problem name to be outputted in Description section.

Author

The author information for the model to be outputted in Author section.

DataFilePath

A data file path used by NLME.

DataMapping

A named vector ModelTerm = DataTerm for the used data file.

ColDef

A character string specifying additional column definitions in NLME column definition format. See https://onlinehelp.certara.com/phoenix/8.4/index.html#t=Phoenix_UserDocs%2FPML%2FColumn_mappings.htm

PMLParametersSets

A list of PML parameters sets (PMLModels class instance).

EstArgs

Estimation arguments for the model template. Please use specify_EngineParams to specify the arguments passed to NLME.

SimArgs

Simulation arguments for the model template. Please use specify_SimParams to specify the arguments passed to NLME.

Tables

A list of Table class instances specifying properties of the tables to be generated after fitting or during simulation.

AppendixRows

Additional rows to include in the model template appendix in NLME column definition format. See https://onlinehelp.certara.com/phoenix/8.4/index.html#t=Phoenix_UserDocs%2FPML%2FColumn_mappings.htm

OmegaSearchBlocks

A list of character vectors representing omega names to try to build block omegas.

# Write model template and tokens files
PMLParametersSets <- create_ModelPK(CompartmentsNumber = c(1,2))
# write test data frame
TempFolder <- tempdir()
TemplateFilePath <- file.path(TempFolder, "template.txt")
TokensFilePath <- file.path(TempFolder, "tokens.json")
DataFilePath <- file.path(TempFolder, "Data.csv")
write.csv(data.frame(id = 'id',
 time = 'time',
 AMT = 'AMT',
 Conc = 'Conc',
 age = 'age',
 Weight = 'Weight',
 CObsBQL = 'CObsBQL'),
 DataFilePath)
write_ModelTemplateTokens(TemplateFilePath = TemplateFilePath,
 TokensFilePath = TokensFilePath,
 Description = "1-2Cpts try",
 Author = "Certara",
 DataFilePath = DataFilePath,
 DataMapping = c(ID = "id",
 time = "time",
 CObs = "Conc",
 AMT = "AMT",
 "age"),
 ColDef = "",
 PMLParametersSets = PMLParametersSets,
 EstArgs = specify_EngineParams(method = "QRPEM"),
 SimArgs = specify_SimParams(numReplicates = 1000L),
 Tables = list(Table(Name = "simtable1.csv",
 KeepSource = TRUE,
 VariablesList = "C",
 ForSimulation = TRUE)),
 OmegaSearchBlocks = list(c("nCl", "nV"), c("nCl2", "nV2")))

write_pyDarwinOptions(
 pyDarwinOptions = create_pyDarwinOptions(),
 file = "options.json",
 pretty = TRUE,
 digits = NA,
 auto_unbox = TRUE
)

pyDarwinOptions

A list containing the pyDarwin options to be written to the JSON file. Default is the result of calling create_pyDarwinOptions() with default arguments.

file

Character: The path to the JSON file where the options will be written. Default is a file named "options.json" in the current working directory.

pretty

adds indentation whitespace to JSON output. Can be TRUE/FALSE or a number specifying the number of spaces to indent. See prettify()

digits

max number of decimal digits to print for numeric values. Use I() to specify significant digits. Use NA for max precision.

auto_unbox

automatically unbox() all atomic vectors of length 1. It is usually safer to avoid this and instead use the unbox() function to unbox individual elements. An exception is that objects of class AsIs (i.e. wrapped in I() ) are not automatically unboxed. This is a way to mark single values as length-1 arrays.

# Write pyDarwin options to a JSON file
Options <-
 create_pyDarwinOptions(author = "John Doe",
 algorithm = "GA",
 population_size = 10)
write_pyDarwinOptions(Options,
 file = file.path(tempdir(), "options.json"))