system_set_option {ubiquity}

Setting Analysis Options

Description

Different options associated performing analyses (e.g running simulations, performing parameter estimation, logging, etc.) can be set with this function

Usage

system_set_option(cfg, group, option, value)

Arguments

cfg

ubiquity system object

group

options are grouped together by the underlying activity being performed: "estimation", "general", "logging", "simulation", "solver", "stochastic", or "titration"

option

for each group there are a set of options

value

corresponding value for the option

Details

group="estimation"

The default estimation in R is performed using either the optim or optimx libraries. This is selected by setting the optimizer option:

cfg = system_set_option(cfg, 
                       group  = "estimation",
                       option = "optimizer",
                       value  = "optim")

The optimization routine then specified using the method. By default this option is set to Nelder-Mead.

cfg = system_set_option(cfg, 
                       group  = "estimation",
                       option = "method",
                       value  = "Nelder-Mead")

And different attributes are then selected using the control.

cfg = system_set_option(cfg, 
                       group  = "estimation",
                       option = "control",
                       value  = list(trace  = TRUE,
                                     maxit  = 500,
                                     REPORT = 10))

For the different methods and control options, see the documentation for the optim and optimx libraries.

To perform a global optimization you can install either the particle swarm (pso) genetic algorithm (GA) libraries. To use the particle swarm set the optimizer and method:

cfg = system_set_option(cfg, 
                       group  = "estimation",
                       option = "optimizer",
                       value  = "pso")

cfg = system_set_option(cfg, 
                       group  = "estimation",
                       option = "method",
                       value  = "psoptim")

The control option is a list described pso documentation.

To use the genetic algorithm set the optimizer and method:

cfg = system_set_option(cfg, 
                       group  = "estimation",
                       option = "optimizer",
                       value  = "ga")

cfg = system_set_option(cfg, 
                       group  = "estimation",
                       option = "method",
                       value  = "ga")

The control option is a list and the list elements are the named options in the GA documentation. Use the following as an example:

cfg = system_set_option(cfg, 
                       group  = "estimation",
                       option = "control",
                       value  = list(maxiter  = 10000,
                                    optimArgs = list(
                                      method  = "Nelder-Mead",
                                      maxiter = 1000)))

To alter initial guesses see: system_set_guess

When performing parameter estimation, the internal function system_od_general is used. This is the function that simulates your system at the conditions defined for the different cohorts. This is pretty flexible but if you want to go beyond this you can set the observation_function option:

cfg = system_set_option(cfg, 
                       group  = "estimation",
                       option = "observation_function",
                       value  = "my_od")

That will instruct the optimziation routines to use the user defined function my_od. You will need to construct that function to have the same input/output format as system_od_general.

group=general

• "output_directory" = String where analysis outputs will be placed. Generally you wont want to change this, but it can be useful in Shiny apps where you need to have each shiny user generate output in that users directory : file.path(".", "output")

group=logging

By default ubiquity prints different information to the console and logs this information to a log file. The following options can be used to control this behavior:

• "enabled" = Boolean variable to control logging: TRUE

• "file" = String containing the name of the log file: file.path("transient", "ubiquity_log.txt")

• "timestamp" = Boolean switch to control appending a time stamp to log entries: TRUE

• "ts_str" = String format of timestamp: "

• "debug" = Boolean switch to control debugging (see below): FALSE

• "verbose" = Boolean switch to control printing to the console FALSE

To enable debugging of different functions (like when performing esitmation), set the debug option to TRUE. Important function calls will be trapped and information will be logged and reported to the console.

cfg = system_set_option(cfg, 
                       group  = "estimation",
                       option = "debug",
                       value  = FALSE)

group="simulation"

• "include_important_output_times" - Automatically add bolus, infusion rate switching times, etc: "yes"(default), "no".

• "integrate_with" - Specify if the ODE solver should use the Rscript ("r-file") or compiled C ("c-file"), if the build process can compile and load the C version it will be the default otherwise it will switch over to the R script.

• "output_times" - Vector of times to evaulate the simulation (default seq(0,100,1)).

• "solver" - Selects the ODE solver: "lsoda" (default), "lsode", "vode", etc.; see the documentation for deSolve for an exhaustive list.

• "sample_bolus_delta" - Spacing used when sampling around bolus events (default 1e-6).

• "sample_forcing_delta" - Spacing used when sampling around forcing functions (infusion rates, covariates, etc) (default 1e-3).

group=solver

Depending on the solver, different options can be set. The documentation for deSolve lists the different solvers. For a full list of options, see the documentation for the specific solver (e.g. ?lsoda). Some common options to consider are:

• "atol" - Relative error tolerance

• "rtol" - Absolute error tolerance

• "hmin" - Minimum integration step size

• "hmax" - Maximum integration step size

To select the vode solver and set the maximum step size to 0.01, the following would be used:

cfg=system_set_option(cfg,
                     group  = "simulation",
                     option = "solver", 
                     value  = "vode")

cfg=system_set_option(cfg,
                     group  = "solver",
                     option = "hmax", 
                     value  = 0.01)

group="stochastic"

When running stochastic simulations (inter-individual variability applied to system parameters) it can be useful to specify the following:

• "ci" - Confidence interval (default 95)

• "nsub" - Number of subjects (default 100)

• "seed" - Seed for the random numebr generator (default 8675309)

• "ponly" - Only generate the subject parameters but do not run the simulations (default FALSE)

• "ssp" - A list of the calculated static secondary parameters to include (default all parameters defined by <As>)

• "outputs" - A list of the predicted outputs to include (default all outputs defined by <O>)

• "states" - A list of the predicted states to include(default all states)

• "sub_file" - Name of data set loaded with (system_load_data) containing subject level parameters and coviariates

• "sub_file_sample" - Controls how subjects are sampled from the dataset

If you wanted to generate 1000 subjects but only wanted the parameters, you would use the following:

cfg = system_set_option(cfg,
                       group  = "stochastic", 
                       option = "nsub ",
                       value  = 1000)

cfg = system_set_option(cfg,
                       group  = "stochastic", 
                       option = "ponly",
                       value  = TRUE )

If you wanted to exclude both states and secondary parameters, while only including the output Cp_nM, you would do the following:

cfg = system_set_option (cfg, 
                        group  = "stochastic",
                        option = "ssp",
                        value  = list())

cfg = system_set_option (cfg, 
                        group  = "stochastic",
                        option = "states",
                        value  = list())

cfg = system_set_option (cfg, 
                        group  = "stochastic",
                        option = "outputs",
                        value  = c("Cp_nM")) 

To pull subject information from a data file instead of generating the subject parameters from IIV information the sub_file option can be used. The value here SUBFILE_NAME is the name given to a dataset loaded with (system_load_data):

cfg=system_set_option(cfg, 
                     group  = "stochastic",
                     option = "sub_file",
                     value  = "SUBFILE_NAME")

Sampling from the dataset can be controlled using the sub_file_sample option:

cfg=system_set_option(cfg, 
                     group  = "stochastic",
                     option = "sub_file_sample",
                     value  = "with replacement")

Sampling can be done sequentially ("sequential"), with replacement ("with replacement"), or without replacement ("without replacement")

group="titration"

"titrate" - By default titration is disable (set to FALSE). If you are going to use titration, enable it here by setting this option to TRUE. This will force #' simulate_subjects to use run_simulation_titrate internally when running simulations.

Value

Ubiquity system object with the option set