Optimal Sample Times — PM

Contains optimal sampling times for a given model and dosage regimen.

Details

This object contains the methods to create and results from optimal sampling algorithms. Currently the only option multiple-model optimization. This algorithm calculates the requested number of sample times where the concentration time profiles are the most separated, thereby minimizing the risk of choosing the incorrect Bayesian posterior for an individual. Future updates will add D-optimal sampling times.

References

Bayard, David S. & and Neely, Michael. (2017). Experiment Design for Nonparametric Models Based on Minimizing Bayes Risk: Application to Voriconazole. Journal of Pharmacokinetics and Pharmacodynamics, 44(2): 95–111. https://doi.org/10.1007/s10928-016-9498-5.

Author

Michael Neely

Public fields

sampleTime: The optimal sample times, based on requested type argument to $new creation method.
bayesRisk: Only present for MM-optimal sampling. The Bayesian risk of mis-classifying a subject based on the sample times. This is more useful for comparisons between sampling strategies, with minimization the goal.
simdata: A PM_sim object with the simulated profiles
mmInt: A list with the mmInt values, NULL if mmInt argument to $new is missing.

Methods

`PM_opt$new()`

Determine optimal sample times which are the most informative about the model parameters.

Usage

PM_opt$new(
  poppar,
  model,
  data,
  nsamp = 1,
  weight = list(none = 1),
  predInt = 0.5,
  mmInt,
  algorithm = "mm",
  outeq = 1,
  ...
)

Arguments

poppar

There are several choices for the population parameters.

A PM_sim object, in which case the simulated data will be used to calculate optimal sampling times. Here model and data are not required, as they will be extracted from the PM_sim object.
A PM_result loaded with PM_load, in which case the $final field will be used, e.g. run1 <- PM_load(1) and poppar = run1.
A PM_final object, typically as a field in a PM_result, e.g., poppar = run1$final.
A data frame of support points in rows, where the columns contain the parameter values for each support point. The first row has the parameter names. Compatible model and data objects must be specified to simulate the output profiles from each support point.
A list containing three items in this order, but of any name: vector of weights, vector of mean parameter values, and a covariance matrix. If only one distribution is to be specified the weights vector should be of length 1 and contain a 1. If multiple distributions are to be sampled, the weights vector should be of length equal to the number of distributions and its values should sum to 1, e.g. c(0.25,0.05,0.7). The means matrix may be a vector for a single distribution, or a matrix with length(weights) rows and number of columns equal to the number of parameters. Compatible model and data objects must be specified to simulate the output profiles from the support points generated by sampling from the specified distributions.

model

A PM_model object, required or optional depending on the poppar argument.

When poppar is a PM_sim object, model is ignored.
When poppar is a PM_result object, model is optional. If missing, the model from the $model field of the PM_result will be used. If specified, model must be compatible with the primary support point parameter names and values in poppar.
When poppar is a PM_final object, model is mandatory and must be compatible with the primary support point parameter names and values in poppar.
When poppar is a data frame of support points, model is mandatory and must be compatible with the parameter names and values in the data frame.
When poppar is a list of weights, means, and covariance, model is mandatory and must be compatible with the parameter names and values.

data

A PM_data object, required or optional depending on the poppar argument.

When poppar is a PM_sim object, data is ignored.
When poppar is a PM_result object, data is optional. If missing, the data from the $data field of the PM_result will be used. If specified, data must be compatible with the model that is either in the PM_result or as specified by model.
When poppar is a PM_final object, data is mandatory and must be compatible with the model that is specified by model.
When poppar is a data frame of support points, data is mandatory and must be compatible with the model that is specified by model.
When poppar is a list of weights, means, and covariance, data is mandatory and must be compatible with the model that is specified by model.

For any choice of data, the value for outputs can be coded as any number(s) other than -99. The number(s) will be replaced in the simulator output with the simulated values. Good practice is to use -1 for out values to be simulated.

nsamp

The number of MM-optimal sample times to compute; default is 1, but can be any number. Values >4 will take an exponentially longer time.

weight

List whose names indicate the type of weighting, and values indicate the relative weight. Values should sum to 1. Names can be any of the following:

none The default. MMopt times will be chosen to maximally discriminate all responses at all times.
AUC MMopt times will be chosen to maximally discriminate AUC, regardless of the shape of the response profile.
max MMopt times will be chosen to maximally discriminate maximum, regardless of the shape of the response profile.
min MMopt times will be chosen to maximally discriminate minimum, regardless of the shape of the response profile.

Any combination of AUC, max, and min can be chosen. If "none" is specified, other weight types will be ignored and the relative value will be set to 1. For example,list(auc = 0.5,max = 0.5) or list(auc = 0.2, min = 0.8). The default is list(none = 1).

predInt

The interval in fractional hours for simulated predicted outputs at times other than those specified in the template data. The default is 0.5, which means there will be simulated outputs every 30 minutes from time 0 up to the maximal time in the template file. You may also specify predInt as a vector of 3 values, e.g. c(1,4,1), similar to the R command seq, where the first value is the start time, the second is the stop time, and the third is the step value. Outputs for times specified in the template file will also be simulated. To simulate outputs only at the output times in the template data (i.e. EVID=0 events), use predInt = 0. Note that the maximum number of predictions total is 594, so the interval must be sufficiently large to accommodate this for a given number of output equations and total time to simulate over. If predInt is set so that this cap is exceeded, predictions will be truncated.

mmInt

Specify the time intervals from which MMopt times can be selected. These should only include simulated times specified by predInt.

algorithm

Optimal sampling algorithm. Currently not modifiable and the only option is "mm".

outeq

Output equation to optimize

...

Other parameters to pass to PM_sim$new(). Most are not necessary, but usePost = TRUE can be used to calculate individual MMopt times. In this case, the number of posterior distributions contained in poppar$final$postPoints needs to match the number of subjects in data. You can also pass include and exclude to limit the subjects used in data. This will work whether usePost is TRUE or FALSE. Note that the following arguments to PM_sim$new cannot be modified.

nsim is zero
outname is "MMsim"
combine is TRUE

clean

Boolean parameter to specify whether temporary files made in the course of the simulation run should be deleted. Defaults to TRUE. This is primarily used for debugging.

Details

Currently, the only option is the multiple-model optimization algorithm.

`PM_opt$plot()`

Plot method

Usage

PM_opt$plot(...)

Arguments

...: Arguments passed to plot.PM_opt

Details

See plot.PM_opt.

`PM_opt$print()`

Print method

Usage

PM_opt$print()

Returns

Prints the optimal sampling times and Bayes Risk.

`PM_opt$clone()`

The objects of this class are cloneable with this method.

Usage

PM_opt$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.