MODEL-class: 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 MODEL
simulation(
  model,
  n = 1,
  theta = model@theta0,
  summStat = TRUE,
  parallel = FALSE,
  parallelArgs = NULL,
  seed = NULL
)
# S4 method for ANY,MODEL
summStat(x, model)

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.

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.

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

Run this code

# 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")
# \dontshow{
benchmark(serial  = simulation(m1, n = 50, theta = c(0.6, 0.2)),
          vectorised  = simulation(m2, n = 50, theta = c(0.6, 0.2)))
# }
if (FALSE) {
benchmark(serial  = simulation(m1, n = 1000, theta = c(0.6, 0.2)),
          vectorised  = simulation(m2, n = 1000, theta = c(0.6, 0.2)))
}

Run the code above in your browser using DataLab