Run the Pmetrics Simulator

This is largely superseded as it is automatically called by either of the simulation methods: PM_result$sim() or PM_sim$new(). There is rarely a need any longer to call this function directly.

Usage

SIMrun(
  poppar,
  limits = NULL,
  model,
  data,
  split,
  include = NA,
  exclude = NA,
  nsim = 1000,
  predInt = 0,
  covariate,
  usePost = F,
  seed = -17,
  ode = -4,
  obsNoise,
  doseTimeNoise = rep(0, 4),
  doseNoise = rep(0, 4),
  obsTimeNoise = rep(0, 4),
  makecsv,
  outname,
  clean = T,
  quiet = F,
  nocheck = F,
  overwrite = F,
  combine
)

Arguments

poppar

Either an object of class PM_final (see PM_result) or 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, npar. The covariance matrix will be divided by length(weights) and applied to each distribution.

limits

If limits are specified, each simulated parameter set that contains a value outside of the limits will be ignored and another set will be generated. Four options exist for limits. 1) The default NULL indicates that no limits are to be applied to simulated parameters. 2) The second option is to set limits to NA. This will use the parameter limits on the primary parameters that are specified in the model file. 3) The third option is a numeric vector of length 1 or 2, e.g. limits = 3 or limits = c(0.5, 4), which specifies what to multiply the columns of the limits in the model file. If length 1, then the lower limits will be the same as in the model file, and the upper limits will be multiplied by value specified. If length 2, then the lower and upper limits will be multiplied by the specified values. If this option is used, popppar must be a PM_final object. 4) The fourth option for limits is a fully customized matrix of limits for simulated values for each parameter which will overwrite any limits in the model file. If specified, it should be a data.frame or matrix with number of rows equal to the number of random paramters and 2 columns, corresponding to the minimum and maximum values. For example, a final$ab object, or a directly coded matrix, e.g. matrix(c(0, 5, 0, 5, 0.01, 100), nrow = 3,ncol = 2, byrow = T) for 3 parameters with limits of (0, 5), (0, 5) and (0.01, 100), respectively. It is possible to convert a parameter to fixed by omitting the second limit. Means and covariances of the total number of simulated sets will be returned to verify the simulation, but only those sets within the specified limits will be used to generate output(s) and the means and covariances of the retained sets may (and likely will be) different than those specified by poppar.

model

Name of a suitable PM_model object or a model file template in the working directory. The default is "model.txt".

data

Either a PM_data object (R6 Pmetrics), a PMmatrix object previously loaded with PMreadMatrix (legacy Pmetrics) or a character vector with the file name of a Pmetrics data file in the working directory that contains template regimens and observation times. 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. Outputs equal to -99 will be simulated as missing.

split

Boolean operator controlling whether to split an NPAG PM_final object into one distribution per support point, with means equal to the vector of parameter values for that point, and covariance equal to the population covariance divided by the number of support points. Default for NPAG PM_final objects is TRUE, otherwise FALSE.

include

A vector of subject IDs in the matrixfile1 to iterate through, with each subject serving as the source of an independent simulation. Default is NA` and all subjects in the data file will be used.

exclude

A vector of subject IDs to exclude in the simulation, e.g. exclude = c(4, 6:14, 16:20). Default is NA and all subjects in the data file will be used, i.e. none excluded.

nsim

The number of simulated profiles to create, per subject. Default is 1000. Entering 0 will result in one profile being simulated from each point in the non-parametric prior (for NPAG final objects only).

predInt

The interval in fractional hours for simulated predicted outputs at times other than those specified in the template data. The default is 0, which means there will be simulated outputs only at times specified in the data file (see below). Values greater than 0 result in simulated outputs at the specified value, e.g. every 15 minutes for predInt = 0.25 from time 0 up to the maximal time in the template file, per subject if nsub > 1. You may also specify predInt as a vector of 3 values, e.g. predInt = 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. Finally, you can have multiple such intervals by specifying predInt as a list of such vectors, e.g. predInt = list(c(0, 24, 1), c(72, 96, 1)). 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, which is the default. Note that the maximum number of predictions is 594, so the prediction interval must be sufficiently long 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.

covariate

If you are using the results of an NPAG or IT2B run to simulate, i.e. a PM_final object as poppar, then you can also simulate with covariates. This argument is a list with the following names.

cov The name of a PM_result or PM_cov object Pmetrics will use this covariate object to calculate the correlation matrix between all covariates and Bayesian posterior parameter values.
mean A named list that allows you to specify a different mean for one or more of the covariates. Each named item in the list is the name of a covariate in your data that is to have a different mean. If this argument is missing then the mean covariate values in the population will be used for simulation. The same applies to any covariates that are not named in this list. Example: run1 <- PM_load(1); covariate = list(cov = run1, mean = list(wt = 50)).
sd This functions just as the mean list argument does - allowing you to specify different standard deviations for covariates in the simulation. If it, or any covariate in the sd list is missing, then the standard deviations of the covariates in the population are used. Example: covariate = list(cov = run1$cov, sd = list(wt = 10)).
limits This is a bit different than the limits for population parameters above. Here, limits is similar to mean and sd for covariates in that it is a named list with the minimum and maximum allowable simulated values for each covariate. If it is missing altogether, then no limits will apply. If it is specified, then named covariates will have the indicated limits, and covariates not in the list will have limits that are the same as in the original population. If you want some to be limited and some to be unlimited, then specify the unlimited ones as items in this list with very large ranges. Example: covariate = list(cov = run1, limits = list( wt = c(10, 70))).
fix A character vector (not a list) of covariates to fix and not simulate. In this case values in the template data file will be used and not simulated. Example: fix = c("wt", "age"). Whether you use the means and standard deviations in the population or specify your own, the covariance matrix in poppar will be augmented by the covariate covariances for any non-fixed covariates. The parameter plus covariate means and this augmented covariance matrix will be used for simulations. In effect, all non-fixed covariates are moved into the #Primary block of the model file to become parameters that are simulated. In fact, a copy of your model file is made with a "c" prepended to the model name (e.g. "model.txt" -> "c_model.txt").

usePost

Boolean argument. Only applicable when poppar is an NPAG PM_final object. If so, and usePost is TRUE, the posterior for each subject (modified by include or exclude) in poppar will be used to simulate rather than the population prior. The number of subjects in the template data file must be the same. Normally one uses the same data file as used to make the model final parameter distribution in poppar, but if different templates are desired, the number must be equivalent to the number of included subjects from whom the posteriors are obtained.

seed

The seed for the random number generator. For nsub > 1, should be a vector of length equal to nsub. Shorter vectors will be recycled as necessary. Default is -17.

ode

Ordinary Differential Equation solver log tolerance or stiffness. Default is -4, i.e. 0.0001. Higher values will result in faster runs, but simulated concentrations may not be as accurate.

obsNoise

The noise added to each simulated concentration for each output equation, where the noise is randomly drawn from a normal distribution with mean 0 and SD = C0 + C1\*conc + C2\*conc^2 + C3\*conc^3. Default values are 0 for all coefficients (i.e.) no noise. If present will override any other values in the data file or model file. Specify as a vector of length 4 times the number of output equations, e.g. c(0.1,0.1,0,0) for one output and c(0.1,0.1,0,0,0.01,0.2,-0.001,0) for two output equations. If specified as NA, values in the data file will be used (similar to limits, above). If they are missing, values in the model file will be used.

doseTimeNoise

A vector of length four to specify dose time error polynomial coefficients. The default is 0 for all coefficients.

doseNoise

A vector of length four to specify dose amount error polynomial coefficients. The default is 0 for all coefficients.

obsTimeNoise

A vector of length four to specify observation timing error polynomial coefficients. The default is 0 for all coefficients.

makecsv

A character vector for the name of the single .csv file to be made for all simulated "subjects". If missing, no files will be made. If a makecsv filename is supplied, ID numbers will be of the form nsub.nsim, e.g. 1.001 through 1.1 for the first subject, 2.001 through 2.1 for the second subject, etc. if 1000 simulations are made from each subject.

outname

The name for the output file(s) without an extension. Numbers 1 to nsub will be appended to the files. If missing, will default to "simout".

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.

quiet

Boolean operator controlling whether a model summary report is given. Default is FALSE.

nocheck

Suppress the automatic checking of the data file with PMcheck. Default is FALSE.

overwrite

Cleans up any old output files without asking before creating new output. Default is FALSE.

combine

Pass through to SIMparse. Ignored for SIMrun.

Value

No value is returned, but simulated file(s) will be in the working directory.

Details

The Monte Carlo simulator in Pmetrics generates randomly sampled sets of parameters from the #PRIMARY block of a model according to a prior distribution and calculates outputs based upon a template data file. It is a powerful tool for parametric or semi-parametric sampling. There are three ways to execute the simulator.

PM_result$sim
PM_sim$run
SIMrun

The first two are the preferred methods in R6 Pmetrics. They return fully parsed simulator output as PM_sim objects in R. The third method is for legacy Pmetrics or when a user-specified prior is necessary, i.e. not from a prior NPAG or IT2B run. In this case, the output of the simulation is one or more files on your hard drive, which must be read into R using SIMparse. SIMparse is not necessary with the first two methods, as R includes a call to that function at the end of the simulation.

Via the first two methods of calling SIMrun, NPAG or IT2B final objects can easily be used as the prior distributions for sampling. Via the third method, prior distributions may be manually specified. Prior distributions may be unimodal-multivariate (parametric sampling), or multimodal-multivariate (semi-parametric sampling). For priors from NPAG, this can be accomplished with the split argument.

It is also possible to simulate with covariates if they are included as part of the model. By specifying a covariate list argument, Pmetrics will first calculate the correlation matrix between the covariates and the Bayesian posterior parameter values for each subject in the population model. Using either the mean and standard deviation of each covariate in the population, or a user-specified mean and/or standard deviation, Pmetrics will then calculate an augmented covariance matrix to be used in simulations. Pmetrics will make a copy of the model file with all covariates moved into the primary block as parameters to be simulated.

Noise can be applied to the simulated observations. Noise may also be applied to the observation times, to the dose times, or to the dose amounts.

Limits on the simulated parameter sets can also be specified using the limits on primary parameters in the model file or by specifying them manually as an argument. Limits can also be applied to simulated covariates.

It is permissible to fix a parameter for simulation that was a random parameter in the model prior by changing the range in the model file to a single value for that parameter.

The same model and data structures are used for the simulator as for any other Pmetrics functions. In this case, the data object will serve as the template for the information regarding dosing, covariate values, and observations. Template data may have more than one subject in them, in which case the simulator will use each subject specified by the include argument (default is all subjects) to generate nsim parameter sets and corresponding observations.

Simulator output is directed to text files, one for each template subject, which is read back into R by SIMparse. As mentioned above, this occurs automatically for the first two methods of calling SIMrun. Output may also be directed to a new Pmetrics .csv data file using the makecsv argument.

Author

Michael Neely

Examples

if (FALSE) {
# Load results of NPAG run
run1 <- PM_load(1)

# Two methods to simulate
# The first uses the population prior, data, and model in run1, with "..."
# as additional parameters passed to SIMrun, e.g. limits, nsim, etc.

sim1 <- run1$sim(...)

# The second uses the population prior and model in run1, and a new template
# data file in the working directory

sim2 <- PM_sim$new(poppar = run1, data = newfile.csv, ...)

# These methods are entirely interchangeable. The first can accept a different
# data template. The difference is that poppar must be explicitly
# declared when using PM_sim$new. This makes it the method to use when poppar 
# is derived from th literature.

# An example of a manual prior
# make 1 lognormal distribution for each parameter
weights <- 1
mean <- log(c(0.7, 0.05, 100))
cov <- matrix(rep(0, length(mean)**2), ncol = length(mean))
diag(cov) <- (c(0.15, 0.15, 0.15) * mean)**2
# make the prior for the simulation
poppar <- list(weights, mean, cov)

# run simulation, assuming temp1.csv and model.txt are in working directory

sim1 <- PM_sim$new(poppar, "temp1.csv",
  nsim = 15, model = "model.txt", include = 1:4, limits = NA,
  obsNoise = c(0.02, 0.1, 0, 0)
)
}