R: S4 class "MODEL"

MODEL-class {BSL}

R Documentation

S4 class “MODEL”

Description

The S4 class contains the simulation and summary statistics function and other necessary arguments for a model to run in the main bsl function.

newModel is the constructor function for a MODEL object.

simulation runs a number of simulations and computes the correponding summary statistics with the provided model.

summStat computes the summary statistics with the given data and model object. The summary statistics function and relevant arguments are obtained from the model.

Usage

newModel(
  fnSim,
  fnSimVec,
  fnSum,
  fnLogPrior,
  simArgs,
  sumArgs,
  theta0,
  thetaNames,
  test = TRUE,
  verbose = TRUE
)

## S4 method for signature 'MODEL'
simulation(
  model,
  n = 1,
  theta = model@theta0,
  summStat = TRUE,
  parallel = FALSE,
  parallelArgs = NULL,
  seed = NULL
)

## S4 method for signature 'ANY,MODEL'
summStat(x, model)

Arguments

`fnSim`	A function that simulates data for a given parameter value. The first argument should be the parameters. Other necessary arguments (optional) can be specified with `simArgs`.
`fnSimVec`	A vectorised function that simulates a number of datasets simultaneously for a given parameter value. The first two arguments should be the number of simulations to run and parameters, respectively. Other necessary arguments (optional) can be specified with `simArgs`. The output must be a list of each simulation result or a matrix with each row corresponding to a simulation.
`fnSum`	A function for computing summary statistics of data. The first argument should be the observed or simulated dataset. Other necessary arguments (optional) can be specified with `sumArgs`.
`fnLogPrior`	A function that computes the log of prior density for a parameter. If this is missing, the prior by default is an improper flat prior over the real line for each parameter. The function must have a single input: a vector of parameter values.
`simArgs`	A list of additional arguments to pass into the simulation function. Only use when the input `fnSim` requires additional arguments.
`sumArgs`	A list of additional arguments to pass into the summary statistics function. Only use when the input `fnSum` requires additional arguments.
`theta0`	Initial guess of the parameter value.
`thetaNames`	A string vector of parameter names, which must have the same length as the parameter vector.
`test`	Logical, whether a short simulation test will be ran upon initialisation.
`verbose`	Logical, whether to print verbose messages when initialising a “MODEL” object.
`model`	A “MODEL” class object.
`n`	The number of simulations to run.
`theta`	The parameter value.
`summStat`	Logical indicator whether the correpsonding summary statistics should be returned or not. The default is `TRUE`.
`parallel`	A logical value indicating whether parallel computing should be used for simulation and summary statistic evaluation. The default is `FALSE`. When model simulation is fast, it may be preferable to perform serial or vectorised computations to avoid significant communication overhead between workers. Parallel computation can only be used if not using a vectorised simulation function, see `MODEL` for options of vectorised simulation function.
`parallelArgs`	A list of additional arguments to pass into the `foreach` function. Only used when parallel computing is enabled, default is `NULL`.
`seed`	A seed number to pass to the `set.seed` function. The default is `NULL`, when no seed number is specified. Please note `parallel` also affects the result even with the same seed.
`x`	The data to pass to the summary statistics function.

Value

A list of simulation results using the given parameter. x contains the raw simulated datasets. ssx contains the summary statistics.

A vector of the summary statistics.

Slots

fnSim: A function that simulates data for a given parameter value. The first argument should be the parameters. Other necessary arguments (optional) can be specified with simArgs.
fnSimVec: A vectorised function that simulates a number of datasets simultaneously for a given parameter value. If this is not NULL, vectorised simulation function will be used instead of fnSim. The first two arguments should be the number of simulations to run and parameters, respectively. Other necessary arguments (optional) can be specified with simArgs. The output must be a list of each simulation result.
fnSum: A function for computing summary statistics of data. The first argument should be the observed or simulated dataset. Other necessary arguments (optional) can be specified with sumArgs. The users should code this function carefully so the output have fixed length and never contain any Inf value.
fnLogPrior: A function that computes the log of prior density for a parameter. The default is NULL, which uses an improper flat prior over the real line for each parameter. The function must have a single input: a vector of parameter values.
simArgs: A list of additional arguments to pass into the simulation function. Only use when the input fnSim or fnSimVec requires additional arguments. The default is NULL.
sumArgs: A list of additional arguments to pass into the summary statistics function. Only use when the input fnSum requires additional arguments. The default is NULL.
theta0: Initial guess of the parameter value, which is used as the starting value for MCMC.
thetaNames: Expression, parameter names.
ns: The number of summary statistics of a single observation. Note this will be generated automatically, thus is not required for initialisation.
test: Logical, whether a short simulation test will be ran upon initialisation.
verbose: Logical, whether to print verbose messages when initialising a “MODEL” object.

Examples

# set up the model for the ma2 example
data(ma2)
m <- newModel(fnSim = ma2_sim, fnSum = ma2_sum, simArgs = ma2$sim_args,
                  theta0 = ma2$start, fnLogPrior = ma2_prior, verbose = FALSE)
validObject(m)

# benchmark the serial and vectorised simulation function (require the rbenchmark package)
m1 <- newModel(fnSim = ma2_sim, fnSum = ma2_sum, simArgs = ma2$sim_args,
            theta0 = ma2$start, fnLogPrior = ma2_prior)
m2 <- newModel(fnSimVec = ma2_sim_vec, fnSum = ma2_sum, simArgs = ma2$sim_args,
            theta0 = ma2$start, fnLogPrior = ma2_prior)
require("rbenchmark")

## Not run: 
benchmark(serial  = simulation(m1, n = 1000, theta = c(0.6, 0.2)),
          vectorised  = simulation(m2, n = 1000, theta = c(0.6, 0.2)))

## End(Not run)

[Package BSL version 3.2.5 Index]