Infusion (version 1.1.0)

add_simulation: Create or augment a list of simulated distributions of summary statistics

Description

add_simulation creates or augments a list of simulated distributions of summary statistics, and formats the simulation results appropriately for further use. The user does not have to think about this return format. Instead, s-he only has to think about the very simple return format of the function given as its Simulate argument. Alternatively, if the simulation function cannot be called directly by the R code, simulated distributions can be added easily using the newsimuls argument, again using a simple format (see onedistrib in the Examples). add_reftable is a wrapper for add_simulation, enforcing nRealizations=1.

Usage

add_simulation(simulations=NULL, Simulate, par.grid=NULL, 
               nRealizations = NULL,
               newsimuls = NULL, verbose = interactive())
add_reftable(...)

Arguments

simulations

A list of simulations

Simulate

The name (as a character string) of the function used to generate empirical distributions of summary statistics. The function must have a single vector as argument, matching rows of par.grid, and must return a vector of summary statistics with named vector members.

par.grid

A data frame which each line matches the single vector argument of Simulate

nRealizations

The number of simulated samples of summary statistics, for each empirical distribution (each row of par.grid). If the argument is NULL, the value is obtained by Infusion.getOption. If the argument is not NULL, Infusion.options(nRealizations) is set, but restored, on exit from add_simulation, to its initial value.

newsimuls

If the function used to generate empirical distributions cannot be called by R, then newsimuls can be used to provide these distributions. This argument should be list of matrices, each with a par attribute (see Examples). Rows of each matrix stand for simulation replicates and rows for the different summary statistics. This is the same format as the return value of add_simulation, except that the latter adds further attributes.

verbose

Whether to print some information or not

...

Arguments passed to add_simulation. Any of the above aguments is valid, except nRealizations.

Value

If only one realization is computed for each (vector-valued) parameter, a data.frame is returned. Otherwise, the return value is an objet of class EDFlist, which is a list of matrices-with-attribute. Each matrix contains a simulated distribution of summary statistics for given parameters, and the "par" attribute is a vector of parameters. If Simulate is used, this must give the full parameters required for a call of the simulation function; otherwise it must at least include all variable parameters in this or later simulations to be appended to the simulation list.

Examples

# NOT RUN {
# example of building a list of simulations from scratch:
myrnorm <- function(mu,s2,sample.size) {
  s <- rnorm(n=sample.size,mean=mu,sd=sqrt(s2))
  return(c(mean=mean(s),var=var(s)))
}
set.seed(123)
onedistrib <- t(replicate(100,myrnorm(1,1,10))) # toy example of simulated distribution
attr(onedistrib,"par") <- c(mu=1,sigma=1,sample.size=10) ## important!
add_simulation(NULL, Simulate="myrnorm",
                     newsimuls=list("example"=onedistrib))

## see main documentation page for the package for other typical usage
# }