Package 'Certara.RDarwin'

Description

Add Covariate into PML models

Usage

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

Arguments

Details

• If Covariate already exists, it will be substituted with a new instance with given properties. New covariate will have default bound omegas/thetas. The user can change thetas with modify_Theta() and omegas with modify_Omega().

• The current functionality does not support adding or modifying custom covariates that are defined within the PML code of custom model spaces.

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

list_Covariates() modify_Theta() modify_Omega()

Functions used for Covariate specification: Covariate(), create_ModelPD(), create_ModelPK(), remove_Covariate()

Examples

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

Description

Adds a new model space, defined by custom PML code, to an existing collection of model spaces (a PMLModels object).

Usage

add_CustomSpace(Spaces, CustomCode, SpaceName = character())

Arguments

Details

This function serves as a wrapper around create_CustomSpace(). It first calls create_CustomSpace using the provided CustomCode and SpaceName to parse the code and create a representation of the new custom space. The name of this new space is either the provided SpaceName or one automatically generated by create_CustomSpace if SpaceName was omitted or empty (e.g., "l<number>" based on code length).

Value

An updated PMLModels object (a named list) containing all the original spaces plus the newly added custom space.

See Also

create_CustomSpace(), add_Spaces(), create_ModelPK(), create_ModelPD()

Examples

# Start with some built-in models
pk_models <- create_ModelPK(CompartmentsNumber = 1)

# Define custom code
custom_pml <- "test() {
  cfMicro(A1, Cl / V)
  dosepoint(A1)
  C = A1 / V
  error(CEps = 1)
  observe(CObs = C + CEps)
  stparm(V = tvV * exp(nV))
  stparm(Cl = tvCl * exp(nCl))
  fixef(tvV = c(, 1, ))
  fixef(tvCl = c(, 1, ))
  ranef(block(nV, nCl) = c(1, 0.001, 1))
}
"

# Add custom space with an explicit name
all_models <-
  add_CustomSpace(pk_models, custom_pml, SpaceName = "1cptOmegaBlock")
names(all_models)

# Add another custom space with auto-generated name
all_models_2 <- add_CustomSpace(all_models,
  "test() {
  cfMicro(A1, Cl / V)
  dosepoint(A1)
  C = A1 / V
  error(CEps = 1)
  observe(CObs = C + C ^ (0.5) * CEps)
  stparm(V = tvV * exp(nV))
  stparm(Cl = tvCl * exp(nCl))
  fixef(tvV = c(, 1, ))
  fixef(tvCl = c(, 1, ))
  ranef(block(nV, nCl) = c(1, 0.001, 1))
}
")
names(all_models_2) # Will include original names + "l<number>"

Description

Add Dosepoint in PML models

Usage

add_Dosepoint(
  PMLParametersSets,
  DosepointName = "A1",
  State = "Present",
  tlag = c(),
  bioavail = c(),
  duration = c(),
  rate = c(),
  PMLStructures = NULL
)

Arguments

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

list_Dosepoints(), modify_Dosepoint()

Functions used for Dosepoint specification: Dosepoint(), create_ModelPK(), modify_Dosepoint()

Examples

PMLParametersSets <-
  create_ModelPK(CompartmentsNumber = c(1, 2, 3),
                 Absorption = c("First-Order"))

# modify dosepoint
PMLParametersSets <-
  modify_Dosepoint(PMLParametersSets,
                   DosepointName = "Aa",
                   tlag = StParm(StParmName = "Tlag",
                                 State = "Present"),
                   bioavail = StParm(StParmName = "F",
                                     State = "Present"))

# add dosepoint
PMLParametersSets <-
 add_Dosepoint(PMLParametersSets,
               DosepointName = "A1",
               bioavail = Expression("1 - F"),
               duration = Expression("Tlag"))

Description

Merges a list of new model spaces into an existing PMLModels object.

Usage

add_Spaces(Spaces, NewSpaces, NewSpacesNames = character())

Arguments

Details

This function provides a general mechanism for combining collections of model spaces.

Naming and Collision Handling: This behavior differs from add_CustomSpace(), which automatically renames on collision. add_Spaces requires unique, non-colliding names for the merge.

Value

An updated PMLModels object (a named list) containing all the original spaces plus all spaces from NewSpaces. The class "PMLModels" is preserved.

See Also

add_CustomSpace() for adding a single custom space with automatic renaming.

Examples

pk_model1 <-
  create_ModelPK(CompartmentsNumber = 1,
                 Absorption = "Intravenous")
pk_models2 <- create_ModelPK(CompartmentsNumber = c(2, 3),
                             Absorption = "First-Order")

# Combine two PMLModels objects (using names from pk_models2)
combined1 <- add_Spaces(pk_model1, pk_models2)
names(combined1)

# Combine using explicit new names
combined2 <-
  add_Spaces(pk_model1,
             pk_models2,
             NewSpacesNames = c("Model_A", "Model_B"))
names(combined2)

# Add a list containing a single custom space
custom_pml <- "test(){ fixef(p=1) }"
custom_space_list <-
  create_CustomSpace(custom_pml, "MyCustom")
combined3 <-
  add_Spaces(pk_model1, custom_space_list)
names(combined3)

Description

Add Structural parameter into PML models Dosepoints

Usage

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

Arguments

Details

• only special Dosepoint() related structural parameters could be added to built-in models (i.e. created using either create_ModelPD() or create_modelPK(). Due to ambiguity of situation when a structural parameter is added with State == 'None', a warning is given for such cases.

• A structural parameter could be added to the custom model if it not presented in the model yet (as a custom or built-in structural parameter).

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

Dosepoint() list_StParms()

Functions used for StParm specification: StParm(), create_ModelPD(), create_ModelPK(), modify_StParm(), modify_StParmCustom(), remove_StParm()

Examples

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

Description

Create a new Covariate object and validate it

Usage

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

Arguments

Value

A Covariate object

See Also

Functions used for Covariate specification: add_Covariate(), create_ModelPD(), create_ModelPK(), remove_Covariate()

Examples

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

Description

Parses a character string containing custom PML code to create a structured representation within the PMLModels framework. This allows integrating user-defined models with the package's modification and generation tools.

Usage

create_CustomSpace(CustomCode = character(), SpaceName = character())

Arguments

Details

This function acts as a parser for custom PML code. It attempts to identify and extract various PML statements within the provided CustomCode string. Recognized statements include:

• Observations/Responses: observe(), error(), multi(), ordinal(), count(), event(), LL()

• Structural Parameters: stparm()

• Covariates: covariate() (parsed as backward), fcovariate() (parsed as forward), interpolate()

• Dosing: dosepoint(), dosepoint2()

• Parameter Definitions: ranef(), fixef()

• Model Dynamics: deriv(), cfMicro(), cfMacro(), cfMacro1(), transit(), delayInfCpt()

• Other Compartments: urinecpt()

The function cleans the code (removes comments, standardizes spacing) for parsing most statements but uses the original code for stparm and fixef parsing to preserve complex structures.

The extracted components are stored as specific S3 objects (e.g., ObservationCustom, StParmCustom, CovariateCustom, DosepointCustom) within the list element corresponding to the SpaceName. This structured representation allows the custom model to be potentially inspected or manipulated by other package functions, although interacting with built-in models via functions like modify_StParm is generally more robust than modifying custom code components directly.

Value

A list object of class PMLModels. This list contains a single element, named according to the provided or generated SpaceName. The value of this element is an internal list structure (created by the internal CustomSpace function) holding the original code and parsed components.

Examples

# Example custom PML code (simplified)
custom_pml <- "test() {
  cfMicro(A1, Cl / V)
  dosepoint(A1)
  C = A1 / V
  error(CEps = 1)
  observe(CObs = C + CEps)
  stparm(V = tvV * exp(nV))
  stparm(Cl = tvCl * exp(nCl))
  fixef(tvV = c(, 1, ))
  fixef(tvCl = c(, 1, ))
  ranef(diag(nV, nCl) = c(1, 1))
}
"

# Create a custom space with an explicit name
custom_model_set <-
  create_CustomSpace(CustomCode = custom_pml,
                      SpaceName = "My1CptOral")

# Print the structure (will show parsed components within the list element)
# print(custom_model_set)

# List the name of the created space
names(custom_model_set) # Output: "My1CptOral"

# Create a custom space with an automatically generated name
custom_model_set_auto_name <- create_CustomSpace(CustomCode = custom_pml)
names(custom_model_set_auto_name)

Description

This function provides the PML (Pharmacometric Modelling Language) Emax parameter sets based on the specified options. They are available as a list of specific S3 classes.

Usage

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

Arguments

Value

A list of PML models (PMLModels class instance) matching the specified options.

Examples

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

Description

This function provides the PML (Pharmacometric Modelling Language) PD parameter sets based on the specified options. They are available as a list of specific S3 classes.

Usage

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

Arguments

Details

The names of PMLStructure are constructed by the following parts:

• Baseline if presented (abbreviated as 'E0'),

• Fractional if presented (abbreviated as '1+'),

• Inhibitory (abbreviated as 'Imax' if the model is inhibitory and 'Emax' otherwise),

• Sigmoid if presented (abbreviated as 'Gam').

Value

A list of PML models (PMLModels class instance) matching the specified options.

Additional arguments

Additional arguments (ellipsis) will be applied sequentially. They can be used to add or modify Structural parameters (StParm), Covariates, Observations, Dosepoints (for PK models); by the way it is advised to use specific functions for it (see 'See Also' section for the references). Also it is possible to modify Omegas and Thetas, but it is impossible to add them (they are parts of other structures). If PMLStructure argument is not specified, class instances will be modified or added in all PML structures. If PMLStructure argument is specified, class instances in the specified PML structure will be modified/added. Note that only one PML structure could be added to the class instance. If multiple structures should be modified, suggest to use specific functions.

See Also

Functions used for StParm specification: StParm(), add_StParm(), create_ModelPK(), modify_StParm(), modify_StParmCustom(), remove_StParm()

Functions used for Observation specification: Observation(), ObservationCustom(), Sigmas(), create_ModelPK(), modify_Observation(), remove_Observation()

Functions used for Omega specification: Omega(), create_ModelPK(), modify_Omega()

Functions used for Theta specification: InitialEstimate(), Theta(), create_ModelPK(), modify_Theta()

Functions used for Covariate specification: Covariate(), add_Covariate(), create_ModelPK(), remove_Covariate()

Examples

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

Description

This function provides the PML (Pharmacometric Modelling Language) PK parameter sets based on the specified options. They are available as a list of specific S3 classes.

Usage

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

Arguments

Details

The names of PMLStructure are constructed by the following parts:

• Model type ('PK'),

• Compartments number

• Abbreviated absorption type:

  • 'IV' for Intravenous,

  • 'FO' for First-Order,

  • 'G' for Gamma,

  • 'W' for Weibull,

  • 'IG' for Inverse Gaussian,

• Abbreviated parameterization ('C' for Clearance and 'M' for Micro),

• Abbreviated saturation if presented ('S'),

• Abbreviated elimination if presented ('E'),

• Abbreviated fraction excreted if presented ('F').

Value

A list of PML models (PMLModels class instance) matching the specified options.

Additional arguments

Additional arguments (ellipsis) will be applied sequentially. They can be used to add or modify Structural parameters (StParm), Covariates, Observations, Dosepoints (for PK models); by the way it is advised to use specific functions for it (see 'See Also' section for the references). Also it is possible to modify Omegas and Thetas, but it is impossible to add them (they are parts of other structures). If PMLStructure argument is not specified, class instances will be modified or added in all PML structures. If PMLStructure argument is specified, class instances in the specified PML structure will be modified/added. Note that only one PML structure could be added to the class instance. If multiple structures should be modified, suggest to use specific functions.

See Also

Functions used for Dosepoint specification: Dosepoint(), add_Dosepoint(), modify_Dosepoint()

Functions used for StParm specification: StParm(), add_StParm(), create_ModelPD(), modify_StParm(), modify_StParmCustom(), remove_StParm()

Functions used for Observation specification: Observation(), ObservationCustom(), Sigmas(), create_ModelPD(), modify_Observation(), remove_Observation()

Functions used for Omega specification: Omega(), create_ModelPD(), modify_Omega()

Functions used for Theta specification: InitialEstimate(), Theta(), create_ModelPD(), modify_Theta()

Functions used for Covariate specification: Covariate(), add_Covariate(), create_ModelPD(), remove_Covariate()

Examples

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

Description

Generates a list of parameters to be used in a pyDarwin run.

Usage

create_pyDarwinOptions(
  author = "",
  project_name = NULL,
  algorithm = c("GA", "EX", "MOGA", "MOGA3", "GP", "RF", "GBRT", "PSO"),
  GA = pyDarwinOptionsGA(),
  MOGA = pyDarwinOptionsMOGA(),
  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(),
  effect_limit = -1,
  downhill_period = 2,
  num_niches = 2,
  niche_radius = 2,
  local_2_bit_search = TRUE,
  final_downhill_search = TRUE,
  local_grid_search = FALSE,
  max_local_grid_search_bits = 5,
  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,
  keep_best_models = TRUE,
  rerun_key_models = FALSE,
  rerun_front_models = TRUE,
  use_saved_models = FALSE,
  saved_models_file = "{working_dir}/models0.json",
  saved_models_readonly = FALSE,
  remove_run_dir = FALSE,
  remove_temp_dir = FALSE,
  keep_files = c("dmp.txt", "posthoc.csv"),
  keep_extensions = NULL,
  use_system_options = TRUE,
  model_cache = "darwin.MemoryModelCache",
  model_run_man = c("darwin.LocalRunManager", "darwin.GridRunManager"),
  engine_adapter = c("nlme", "nonmem"),
  skip_running = FALSE,
  working_dir = NULL,
  data_dir = NULL,
  output_dir = "{working_dir}/output",
  temp_dir = NULL,
  key_models_dir = "{working_dir}/key_models",
  non_dominated_models_dir = "{working_dir}/non_dominated_models",
  nlme_dir = "C:/Program Files/Certara/NLME_Engine",
  gcc_dir = "C:/Program Files/Certara/mingw64",
  nmfe_path = NULL,
  rscript_path = file.path(normalizePath(R.home("bin")), "Rscript"),
  generic_grid_adapter = pyDarwinOptionsGridAdapter(),
  remote_run = FALSE,
  ...
)

Arguments

Details

The algorithm parameter specifies the search algorithm. The algorithm “MOGA” and “MOGA3” are used for multi-objective optimization: "MOGA" uses NSGA-II (see the documentation at https://pymoo.org/algorithms/moo/nsga2.html?highlight=nsga%20ii), and "MOGA3" uses NSGA-III (see the documentation at https://pymoo.org/algorithms/moo/nsga3.html?highlight=nsga%20ii). For MOGA3, the objectives and constraints must be defined and returned by postprocessing scripts (post_run_r_code or post_run_python_code) in a specific format:

• R scripts should return a list of two vectors: the first vector is for the objectives and the second one is for the constraints. If no constraints, the second vector should be empty.

• Python scripts should return a tuple of two lists: the first list is for the objectives and the second one is for the constraints). If no constraints, the second list should be empty.

Other algorithms include "EX" (Exhaustive), "GA" (Genetic Algorithm), "GP" (Gaussian Process), "RF" (Random Forest), "GBRT" (Gradient Boosted Random Tree), and "PSO" (Particle Swarm Optimization).

Please see pyDarwin documentation for complete details on all options.

Value

A list of pyDarwin options.

Examples

# Basic options with GA
ga_opts <- create_pyDarwinOptions(author = "Jane Doe", algorithm = "GA")

# Options for MOGA (NSGA-II)
# pyDarwin internally uses 2 objectives; postprocessing for objectives is not used by pyDarwin.
moga_opts_nsga2 <- create_pyDarwinOptions(
  author = "J. Doe",
  project_name = "MOGA_Test_NSGA2",
  algorithm = "MOGA", # NSGA-II
  MOGA = pyDarwinOptionsMOGA(), # Default MOGA options are suitable
  population_size = 50,
  num_generations = 100,
  engine_adapter = "nonmem",
  nmfe_path = "/opt/NONMEM/nm75/run/nmfe75"
)

# Options for MOGA3 (NSGA-III with 3 objectives, 1 constraint via R postprocessing)
moga_opts_nsga3_custom <- pyDarwinOptionsMOGA(
  objectives = 3,
  names = c("AIC", "NumEffects", "RunTime"), # Example custom names
  constraints = 1,
  partitions = 10 # Custom partitions
)
main_opts_nsga3 <- create_pyDarwinOptions(
  author = "J. Doe",
  project_name = "MOGA_Test_NSGA3",
  algorithm = "MOGA3", # NSGA-III
  MOGA = moga_opts_nsga3_custom,
  population_size = 60, # NSGA-III population size might need adjustment
  num_generations = 100,
  postprocess = pyDarwinOptionsPostprocess( # Required for MOGA3
    use_r = TRUE,
    post_run_r_code = "{project_dir}/moga3_postprocess.R"
  ),
  engine_adapter = "nonmem",
  nmfe_path = "/opt/NONMEM/nm75/run/nmfe75"
)

Description

Create a new Dosepoint object and validate it

Usage

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

Arguments

Value

A new Dosepoint object.

See Also

list_Dosepoints(), add_Dosepoint(), modify_Dosepoint(), StParm(), Expression()

Functions used for Dosepoint specification: add_Dosepoint(), create_ModelPK(), modify_Dosepoint()

Examples

# Using StParm objects
TlagStParm <- StParm("Tlag",
                     Type = "LogNormal",
                     ThetaStParm = Theta(Name = "tvTlag", InitialEstimates = 0.1))
FStParm <- StParm("F", ThetaStParm = Theta(Name = "tvF")) # Assuming Theta exists

dp1 <- Dosepoint(DosepointName = "GutInput",
                 State = "Present",
                 tlag = TlagStParm,
                 bioavail = FStParm)

# Using Expression objects
dp2 <- Dosepoint(DosepointName = "Infusion",
                 rate = Expression("RateVal",
                                   ContainedStParms =
                                     list(StParm("RateVal",
                                                 ThetaStParm = Theta("tvRateVal")))))

# Using a character string (will be converted to Expression internally)
dp3 <- Dosepoint(DosepointName = "Bolus",
                 bioavail = "SystemicF") # Converted to Expression("SystemicF")

Description

Represents a PML expression that can include text and structural parameters (StParm). This is used for arguments like tlag, bioavail, duration, or rate in Dosepoint.

Usage

Expression(
  ExpressionText = character(),
  ContainedStParms = list(),
  State = "Present"
)

Arguments

Value

A new object of class Expression, which is a list containing the provided arguments (ExpressionText, ContainedStParms, State).

See Also

Dosepoint(), StParm()

Examples

PMLParametersSets <-
get_PMLParametersSets(CompartmentsNumber = c(1, 2, 3),
                      Absorption = c("First-Order"))
# add dosepoint
PMLParametersSets <-
  add_Dosepoint(PMLParametersSets,
                DosepointName = "A1",
                bioavail = Expression("1 - Fa"),
                duration = Expression("Tlag",
                ContainedStParms = list(StParm("Tlag"))))

Description

This function retrieves the model terms that can be mapped from a set of PML models.

Usage

get_ModelTermsToMap(PMLParametersSets)

Arguments

Value

A list with two elements: "Required" and "Optional," representing the model terms that can be mapped.

See Also

create_ModelPK() create_ModelPD() create_CustomSpace()

Examples

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

Description

This function creates an object of class InitialEstimate that contains initial parameter estimates for a model Theta(). The estimates can be passed to the function as a single numeric value or as a vector of length three containing lower bound, estimate, and upper bound. If multiple sets of estimates are required, they can be passed as additional arguments, each separated by commas.

Usage

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

Arguments

Value

An object of class InitialEstimate.

See Also

Functions used for Theta specification: Theta(), create_ModelPD(), create_ModelPK(), modify_Theta()

Examples

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

Description

This function lists the names of covariates in a given set of PMLParametersSets.

Usage

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

Arguments

Value

A character vector containing the names of covariates.

See Also

add_Covariate() remove_Covariate() Covariate()

Examples

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

Description

This function lists the names of dosepoints in a given set of PMLParametersSets.

Usage

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

Arguments

Value

A character vector containing the names of dosepoints

See Also

modify_Dosepoint()

Examples

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

Description

This function lists the names of Observations in a given PMLModels class instance.

Usage

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

Arguments

Value

A character vector containing the names of Observations

See Also

Observation() modify_Observation() remove_Observation()

Examples

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

Description

This function lists the unique names of Omega parameters in a given set.

Usage

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

Arguments

Value

A character vector containing the unique names of Omega parameters.

See Also

Omega() modify_Omega()

Examples

PMLParametersSets <- create_ModelPK()
list_Omegas(PMLParametersSets)

Description

This function lists the names of structural parameters in a given set of PMLParametersSets.

Usage

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

Arguments

Value

A character vector containing the names of structural parameters.

See Also

add_StParm() modify_StParm()

Examples

PMLParametersSets <- get_PMLParametersSets()
list_StParms(PMLParametersSets)

Description

This function lists the unique names of Theta parameters in a given set.

Usage

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

Arguments

Value

A character vector containing the unique names of Theta parameters.

See Also

Theta() modify_Theta()

Examples

PMLParametersSets <- create_ModelPD()
list_Thetas(PMLParametersSets)

Description

Modify Dosepoint in PML models

Usage

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

Arguments

Details

This function can only be used to modify the structural parameters in the built-in models (i.e., created using either create_ModelEmax() or create_ModelPK()).

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

list_Dosepoints(), add_Dosepoint()

Functions used for Dosepoint specification: Dosepoint(), add_Dosepoint(), create_ModelPK()

Examples

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

Description

Modify Observation class in PML models

Usage

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

Arguments

Details

This function can only be used to modify the structural parameters in the built-in models (i.e., created using either create_ModelEmax() or create_ModelPK()).

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

list_Observations()

Functions used for Observation specification: Observation(), ObservationCustom(), Sigmas(), create_ModelPD(), create_ModelPK(), remove_Observation()

Examples

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)

Description

This function allows to modify Omega parameters in a list of PML models (PMLModels class instance created by get_PMLParametersSets()).

Usage

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

Arguments

Details

• If the specified Omega does not exist in the PML models, a warning will be issued, and no modifications will be made.

• The current functionality does not support modifying custom omegas (ranefs) that are defined within the PML code of custom model spaces.

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

list_Omegas()

Functions used for Omega specification: Omega(), create_ModelPD(), create_ModelPK()

Examples

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)

Description

Modify structural parameter in PML models set

Usage

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

Arguments

Details

This function can only be used to modify the structural parameters in the built-in models (i.e., created using either create_ModelEmax() or create_ModelPK()) or in the custom models if they are added with add_StParm().

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

Dosepoint() list_StParms()

Functions used for StParm specification: StParm(), add_StParm(), create_ModelPD(), create_ModelPK(), modify_StParmCustom(), remove_StParm()

Examples

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

Description

Modify custom structural parameter in PML spaces

Usage

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

Arguments

Details

This function can be applied to the custom models. It allows modification of custom structural parameters defined in the PML code of these spaces.

When modifying a custom structural parameter, the corresponding Stparm statement is removed from the PML code, and the updated parameter is added back as a StParm class using the provided arguments. Similarly, associated fixef and ranef statements related to the custom structural parameter are removed.

Please note that this function is specifically designed for modifying custom structural parameters. For non-custom parameters, use modify_StParm().

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

Dosepoint() list_StParms() modify_StParm()

Functions used for StParm specification: StParm(), add_StParm(), create_ModelPD(), create_ModelPK(), modify_StParm(), remove_StParm()

Examples

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

Description

This function allows to modify Theta parameter in a list of PML models (PMLModels class instance created by create_ModelPK() or create_ModelPD).

Usage

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

Arguments

Details

• If the specified Theta does not exist in the PML models, a warning will be issued, and no modifications will be made. Thetas associated with structural parameters in the proportional part of MixRatio and Additive+Proportional error models can also be modified.

• The current functionality does not support modifying custom thetas (fixefs) that are defined within the PML code of custom model spaces.

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

InitialEstimate()

Functions used for Theta specification: InitialEstimate(), Theta(), create_ModelPD(), create_ModelPK()

Examples

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)

Description

This function creates a new instance of Observation object and validates it.

Usage

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

Arguments

Value

A new Observation object

See Also

Functions used for Observation specification: ObservationCustom(), Sigmas(), create_ModelPD(), create_ModelPK(), modify_Observation(), remove_Observation()

Examples

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

Description

This function creates a new instance of custom Observation object and validates it. All PML responses are supported (observe, multi, LL, event, count, ordinal)

Usage

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

Arguments

Value

A new Observation object

See Also

Functions used for Observation specification: Observation(), Sigmas(), create_ModelPD(), create_ModelPK(), modify_Observation(), remove_Observation()

Description

This function creates an Omega instance with the given parameters and validates it.

Usage

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

Arguments

Value

An Omega instance.

See Also

list_Omegas()

Functions used for Omega specification: create_ModelPD(), create_ModelPK(), modify_Omega()

Examples

nV <- Omega("nV")

Description

This function serves as a command-line argument parser that calls an internal function (output_NLMETemplateInternal) to generate NLME (Non-Linear Mixed Effects) model templates. It takes a series of "key=value" pairs, processes a detailed JSON model specification, and outputs a model template file and a corresponding tokens file, which can be used for model fitting.

Usage

output_NLMETemplate(args)

Arguments

Value

This function does not return a value to the R environment. It is executed for its side effect of writing two files:

1. A model template file to the location specified by template_path.

2. A tokens JSON file to the location specified by tokens_path.

See Also

The core logic is handled by the internal function output_NLMETemplateInternal. The final file writing is performed by write_ModelTemplateTokens.

Examples

## Not run: 
# Example of the arguments that would be passed to the function.
# In a real scenario, these might come from a command-line call.

arguments <- c(
  "model_setup=./model_definition.json",
  "template_path=./template.txt",
  "tokens_path=./tokens.json",
  "data_path=./pk_data.csv",
  "author=Jane Doe",
  "description=2-compartment PK model with first-order absorption and linear elimination"
)

# Execute the function with the defined arguments
output_NLMETemplate(args = arguments)


## End(Not run)

Description

This function generates the PML code representation of a custom space.

Usage

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

Arguments

Value

A character string containing the PML code.

Description

This function allows you to set various options specific to the Genetic Algorithm (GA) in pyDarwin.

Usage

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
)

Arguments

Value

An object of class "pyDarwinOptionsGA" containing the specified GA options.

Examples

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

Description

This function creates a list of grid adapter options for pyDarwin, which are used to configure the interaction between pyDarwin and grid computing environments.

Usage

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

Arguments

Value

A list containing the configured grid adapter options.

Examples

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

Description

Generates a list of specific options for the MOGA (Multi-Objective Genetic Algorithm) or MOGA3 (NSGA-III) algorithms in pyDarwin. This list is intended to be passed as the MOGA argument to the create_pyDarwinOptions() function when algorithm is set to "MOGA" or "MOGA3".

Usage

pyDarwinOptionsMOGA(
  objectives = 3,
  names = NULL,
  constraints = 0,
  partitions = 12,
  crossover = "single",
  crossover_rate = 0.95,
  mutation_rate = 0.95,
  attribute_mutation_probability = 0.1
)

Arguments

Details

This function defines parameters for the MOGA settings block in pyDarwin. The relevance of certain parameters (objectives, names, constraints, partitions) depends on whether the algorithm in create_pyDarwinOptions() is set to "MOGA" (for NSGA-II) or "MOGA3" (for NSGA-III).

• If algorithm = "MOGA" (NSGA-II): pyDarwin internally uses 2 objectives (OFV and NEP). The objectives, names, constraints, and partitions parameters from this MOGA options block are ignored by pyDarwin. Postprocessing scripts are not used by pyDarwin to define objectives.

• If algorithm = "MOGA3" (NSGA-III): The objectives, names, constraints, and partitions parameters from this MOGA options block are utilized by pyDarwin. User-supplied postprocessing scripts (R or Python) are required to calculate and return the values for the objectives and constraints. (R: list of two vectors; Python: tuple of two lists).

Common parameters like crossover, crossover_rate, mutation_rate, and attribute_mutation_probability apply to both "MOGA" and "MOGA3" variants.

Value

A list containing MOGA-specific options.

Examples

# MOGA options, defaults are generally suitable for algorithm = "MOGA3"
# if postprocessing handles 3 objectives.
moga_block_for_moga3 <- pyDarwinOptionsMOGA(
  objectives = 3,
  names = c("Objective1", "Objective2", "Objective3"),
  constraints = 1,
  partitions = 10
)

# MOGA options where specific settings are for NSGA-II (algorithm = "MOGA")
# Note: objectives, names, constraints, partitions would be ignored by pyDarwin.
moga_block_for_moga <- pyDarwinOptionsMOGA(
  crossover = "two_point",
  crossover_rate = 0.92
)

Description

Generates a list of penalty parameters to be used in pyDarwin create_pyDarwinOptions function.

Usage

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

Arguments

Value

A list of penalty options in pyDarwin optimization process.

Examples

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

Description

Generates a list of postprocessing options to be used in pyDarwin optimization process.

Usage

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

Arguments

Value

A list of postprocessing options in pyDarwin optimization process.

Examples

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

Description

This function allows you to set various options specific to the Particle Swarm Optimization (PSO) in pyDarwin.

Usage

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

Arguments

Value

An object containing the specified options for the Particle Swarm Optimization (PSO) algorithm.

Examples

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

Description

This function reconnects to a pyDarwin job previously launched in the background on a remote host. It monitors the job until completion (if a PID is available), then downloads and processes the results.

Usage

reconnect_pyDarwinJob(
  LocalDirectoryPath = ".",
  LocalJobInfoFilePath = NULL,
  OriginalOptionsPath = NULL,
  Password = NULL,
  KeyPath = NULL,
  MonitoringInterval = 30,
  verbose = getOption("verbose", default = FALSE)
)

Arguments

Details

This function requires a job information JSON file (typically created by RunPyDarwinRemote when Wait = FALSE) to obtain details like the remote host, user, remote project directory, and optionally the remote process ID (PID).

The ProjectName is crucial. It's primarily derived from the project_name field in the original options file (located via OriginalOptionsPath or within LocalDirectoryPath). If not present in the options file, a fallback derivation uses the parent directory name of the options file. This ProjectName is then used to find the job info file (as ⁠{ProjectName}_remote_job_info.json⁠ in LocalDirectoryPath) if LocalJobInfoFilePath is not directly provided. If the job info file itself contains a ProjectName, that value may take precedence. Downloaded results are organized locally using this determined ProjectName.

If RemoteJobPID is available in the job info file, the function will actively monitor the process. If the PID is not available, it will skip active monitoring and proceed directly to attempt downloading any available results.

Value

A list containing parsed results similar to RunPyDarwinRemote(Wait = TRUE) (i.e., results data.frame, FinalResultFile, FinalControlFile, DownloadedResultsDir, DownloadedItems), or the content of the downloaded messages.txt as a character vector if primary result files are not found or parsed successfully. If essential information (like job info or options file) is missing, the function will stop.

See Also

run_pyDarwin(), run_pyDarwinRemote()

Examples

## Not run: 
# Assuming 'my_project_job_info.json' and 'options.json' exist in '~/darwin_runs/my_project_run'
# and 'my_project_job_info.json' was created by a previous RunPyDarwinRemote(Wait=FALSE) call.

# Example 1: Specifying only the local directory path
# ProjectName will be derived from options.json within that path.
# Job info file will be sought as {ProjectName}_remote_job_info.json.
try({
  reconnect_pyDarwinJob(
    LocalDirectoryPath = "~/darwin_runs/my_project_run"
  )
})

# Example 2: Specifying paths explicitly
try({
  reconnect_pyDarwinJob(
    LocalDirectoryPath = "~/darwin_runs/my_project_run", # Still used for downloads
    LocalJobInfoFilePath = "~/darwin_runs/my_project_run/my_project_remote_job_info.json",
    OriginalOptionsPath = "~/darwin_runs/my_project_run/options.json",
    KeyPath = "~/.ssh/id_rsa_remote_server"
  )
})

## End(Not run)

Description

Remove Covariate from PML models

Usage

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

Arguments

Details

The current functionality does not support removing custom covariates that are defined within the PML code of custom model spaces.

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

list_Covariates()

Functions used for Covariate specification: Covariate(), add_Covariate(), create_ModelPD(), create_ModelPK()

Examples

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

Description

Remove Observation from PML models

Usage

remove_Observation(PMLParametersSets, ObservationName, PMLStructures = NULL)

Arguments

Details

The current functionality does not support modifying custom observations that are defined within the PML code of custom model spaces.

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

list_Observations()

Functions used for Observation specification: Observation(), ObservationCustom(), Sigmas(), create_ModelPD(), create_ModelPK(), modify_Observation()

Examples

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

Description

Remove structural parameter from PML models

Usage

remove_StParm(PMLParametersSets, StParmName, PMLStructures = NULL)

Arguments

Details

Please make sure that structural parameter to be removed is not essential for the model. Usually the user does not need to remove any structural parameter. The only case is related to structural parameters in Dosepoint().

Value

An updated list of PML models (PMLModels class instance) matching the specified options.

See Also

Dosepoint() list_StParms()

Functions used for StParm specification: StParm(), add_StParm(), create_ModelPD(), create_ModelPK(), modify_StParm(), modify_StParmCustom()

Examples

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

Description

This function executes a pyDarwin model search by calling the specified Python interpreter and the darwin.run_search module.

Usage

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

Arguments

Value

• If Wait = TRUE: A list containing the search results read from the output_dir (specified in options.json). This typically includes:

  • results: A data frame (results.csv).

  • FinalResultFile: Character vector containing lines from the final model's result file (e.g., .lst, .txt).

  • FinalControlFile: Character vector containing lines from the final model's control file (e.g., .mod, .mmdl).

  If result files are not found, warnings are issued. If no results are found but messages.txt exists, its content might be returned with a warning. If the Python call fails (non-zero exit code), the function stops with an error.

• If Wait = FALSE: A character string giving the full path to the main pyDarwin log file (messages.txt) within the working_dir.

Background Execution (Wait = FALSE)

When Wait is set to FALSE, the pyDarwin process is launched in the background, and the R function returns immediately. This allows R to continue processing while pyDarwin runs.

• Output Redirection: Standard output (stdout) and standard error (stderr) from the Python process are redirected to files named stdout.log and stderr.log respectively, within the working_dir. These files are crucial for diagnosing issues if the background process fails or behaves unexpectedly.

• Primary Log: The main pyDarwin log file (messages.txt, located in the working_dir) remains the primary source for detailed run information, but the stdout.log and stderr.log capture console output and errors directly.

See Also

run_pyDarwinRemote(), reconnect_pyDarwinJob()

Examples

## Not run: 
# Example: Running pyDarwin and waiting for results
# Assuming python is in the PATH and input files are in 'my_project'

results <- run_pyDarwin(
  InterpreterPath = "python",
  DirectoryPath = "my_project",
  Wait = TRUE
)
print(results$results)

# Example: Launching pyDarwin in the background

log_file_path <- run_pyDarwin(
  InterpreterPath = "python",
  DirectoryPath = "my_project",
  Wait = FALSE
)

## End(Not run)

Description

Establishes an SSH connection, prepares and uploads project files, executes pyDarwin in the background, and can optionally monitor the job and download results upon completion.

Usage

run_pyDarwinRemote(
  Host,
  User,
  Password = "",
  KeyPath = Sys.getenv("SSH_PRIVATE_KEY_PATH"),
  SshFlags = character(0),
  LocalTemplatePath,
  LocalTokensPath,
  LocalOptionsPath,
  LocalDirectoryPath = ".",
  RemoteBaseDir = "~/.rdarwin/",
  RemoteInterpreterPath = NULL,
  UseLocalLicense = FALSE,
  Wait = TRUE,
  Flags = c("-u", "-m"),
  MonitoringInterval = 30
)

Arguments

Details

This function automates the entire remote execution workflow. It creates a unique project directory on the remote host to ensure run isolation.

Value

The return value depends on the Wait parameter:

The function throws an error if a critical step fails.

See Also

create_pyDarwinOptions(), reconnect_pyDarwinJob()

Examples

## Not run: 
# Example of launching a remote job and waiting for the results
remote_results <- run_pyDarwinRemote(
  Host = "cluster.mycompany.com",
  User = "myuser",
  KeyPath = "~/.ssh/id_rsa_cluster",
  LocalDirectoryPath = "path/to/my/CovariateSearchProject"
)

# Example of launching a job in the background
job_info <- run_pyDarwinRemote(
  Host = "cluster.mycompany.com",
  User = "myuser",
  KeyPath = "~/.ssh/id_rsa_cluster",
  LocalDirectoryPath = "path/to/my/CovariateSearchProject",
  Wait = FALSE
)

# You can later use job_info to reconnect to the job
# final_results <- reconnect_pyDarwinJob(JobInfo = job_info)

## End(Not run)

Description

This function creates a new instance of different error models object to be applied. 0s are treated as no values.

Usage

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

Arguments

Value

A Sigmas class instance.

See Also

Functions used for Observation specification: Observation(), ObservationCustom(), create_ModelPD(), create_ModelPK(), modify_Observation(), remove_Observation()

Examples

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

Description

Defines optional engine parameters to control the estimation or simulation process in Phoenix NLME. This function generates a single character string containing space-separated name=value pairs for non-default settings. Parameters are included in the output string according to the order in the function signature.

Usage

specify_EngineParams(
  sort = FALSE,
  ODE = c("MatrixExponent", "DVERK", "DOPRI5", "AutoDetect", "Stiff", "LSODE"),
  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", "Hessian", "Fisher-Score", "Auto-Detect", "None"),
  isCentralDiffStdErr = TRUE,
  stepSizeStdErr = 0.01,
  logTransform = NULL,
  numIntegratePtsAGQ = 1L,
  numIterNonParametric = 0L,
  fastOptimization = FALSE,
  numIterMAPNP = 0L,
  numRepPCWRES = 0L,
  stepSizeLinearize = 0.002,
  numDigitLaplacian = 7L,
  numDigitBlup = 13L,
  gradTolOuter = 2e-04,
  stepTolOuter = 1e-04,
  gradTolInner = 1.71e-05,
  stepTolInner = 7.07e-08,
  refDeltaLagl = 0.001,
  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"),
  emTolType = 0L,
  emConvLen = 10L,
  emConvCritVal = 5,
  stepSizePartialDeriv = 1e-05,
  numTimeStepPartialDeriv = 20L
)

Arguments

Details

This function allows customization of the NLME engine settings. Parameters are validated based on type, range, and applicability (detailed in parameter descriptions). Only parameters explicitly set to a value different from their default for the specified context (e.g., method-specific defaults for stdErr) are included in the output string. Values are returned as character strings.

Important Note on Defaults: Uses fixed defaults as specified in the argument list for comparison unless otherwise noted (e.g., stdErr). The actual default applied by NLME might differ based on model context (population vs individual, presence of reset info, discontinuities, BQL data).

Parameter Applicability & Warnings: The function checks for common cases where provided parameters might be ignored by the NLME engine based on the selected method or other settings. Warnings are issued in such cases. It assumes population context unless method="Naive-Pooled".

Value

A single character string containing space-separated name=value pairs, ordered according to the function signature. Includes parameters if specified with non-default values (using method-specific defaults for stdErr).

See Also

write_ModelTemplateTokens(), specify_SimParams()

Examples

# Default settings
EstArgs_def <- specify_EngineParams()
print(EstArgs_def)

# Setting sort = TRUE
EstArgs_sort_true <- specify_EngineParams(sort = TRUE)
print(EstArgs_sort_true)

# QRPEM method with several custom settings
EstArgs_qrpem_str <-
  specify_EngineParams(
    sort = TRUE, # Explicitly non-default
    ODE = "DVERK",
    rtolODE = 1e-5,
    numIterations = 500,
    method = "QRPEM",
    isCentralDiffStdErr = FALSE,
    numIterMAPNP = 3,
    iSample = 350,
    impDist = "Mixture-2",
    scramble = "Tezuka-Faur",
    numBurnIn = 10,
    freezeOmega = TRUE
  )
print(EstArgs_qrpem_str)

Description

Use to define engine parameters for model simulation. Generates a single character string containing space-separated name=value pairs.

Usage

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

Arguments

Details

This function allows customization of the NLME engine settings specific to simulation runs. Parameters are validated based on type and range.

The parameters numReplicates, seed, and sort are always included in the output string. Other parameters (ODE, rtolODE, atolODE, maxStepsODE) are included only if their specified value differs from the function's default value and they are applicable (ODE tolerances are ignored if ODE="MatrixExponent").

Values are returned as character strings. The order of parameters in the output string matches the order in the function definition.

Value

A single character string containing space-separated name=value pairs, ordered according to the function signature. Includes numReplicates, seed, sort always, and other parameters if specified with non-default, applicable values.

See Also

write_ModelTemplateTokens(), specify_EngineParams(), Table()

Examples

# Default settings (includes numReplicates, seed, sort)
SimArgs1 <- specify_SimParams()
print(SimArgs1)

# Custom settings
SimArgs2 <-
  specify_SimParams(
    numReplicates = 50,
    seed = 9876,
    sort = TRUE, # Non-default
    ODE = "DVERK", # Non-default
    rtolODE = 1e-5 # Non-default and applicable
  )
print(SimArgs2)

# Custom settings where ODE tolerances are ignored
SimArgs3 <-
  specify_SimParams(
    numReplicates = 20,
    ODE = "MatrixExponent", # Default, but tolerances are now inapplicable
    rtolODE = 1e-4 # Non-default, but ignored
   )
print(SimArgs3)

Description

This function stops a pyDarwin model search.

Usage

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

Arguments

Value

Returned code of system2() call.

Examples

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

## End(Not run)

Description

Attempts to gracefully stop a running pyDarwin job on a remote host by creating a 'stop.darwin' file in the remote project directory.

Usage

stop_pyDarwinRemote(
  LocalDirectoryPath,
  LocalJobInfoFilePath = NULL,
  OriginalOptionsPath = NULL,
  Password = NULL,
  KeyPath = NULL,
  verbose = getOption("verbose", default = FALSE)
)

Arguments