`lifecycle::badge("superseded")`

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.

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

## 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$run(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$run.
# 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
SIMrun(poppar, "temp1.csv",
nsim = 15, model = "model.txt", include = 1:4,
obsNoise = c(0.02, 0.1, 0, 0)
)
# extract results of simulation
simout <- SIMparse("simout.txt")
}
```