turboSim {turboEM}

Conduct benchmark studies of EM accelerator

Description

The turboSim function conducts benchmark studies to compare performance of multiple acceleration schemes over a large number of repetitions. The turboSim function outputs objects of class turbosim.

Usage

turboSim(parmat, fixptfn, objfn, method = c("em","squarem","pem","decme","qn"), 
  boundary, pconstr = NULL, project = NULL, parallel = FALSE, method.names, 
  keep.pars = FALSE, ..., control.method = replicate(length(method),list()), 
  control.run = list())

Arguments

parmat

A matrix of starting parameter values, where each row corresponds to a single benchmark study repetition.

fixptfn

A vector function, F that denotes the fixed-point mapping. This function is the most essential input in the package. It should accept a parameter vector as input and should return a parameter vector of same length. This function defines the fixed-point iteration: x_{k+1} = F(x_k). In the case of EM algorithm, F defines a single E and M step.

objfn

This is a scalar function, L, that denotes a “merit” function which attains its local minimum at the fixed-point of F. This function should accept a parameter vector as input and should return a scalar value. In the EM algorithm, the merit function L is the negative log-likelihood. In some problems, a natural merit function may not exist. However, this argument is required for all of the algorithms *except* Squarem (which defaults to Squarem-2 if objfn not provided) and EM.

method

Specifies which algorithm(s) will be applied. Must be a vector containing one or more of c("em", "squarem", "pem", "decme", "qn").

boundary

Argument required for Dynamic ECME (decme) only. Function to define the subspaces over which the line search is conducted.

pconstr

Optional function for defining boundary constraints on parameter values. Function maps a vector of parameter values to TRUE if constraints are satisfied. Note that this argument is only used for the Squarem (squarem), Parabolic EM (pem), and quasi-Newton (qn) algorithms, and it has no effect on the other algorithms.

project

Optional function for defining a projection that maps an out-of-bound parameter value into the constrained parameter space. Requires the pconstr argument to be specified in order for the project to be applied.

parallel

Logical indicating whether the repetitions of the benchmark study will be run in parallel. Note that the parallel implementation is based on the foreach package, which depends on a parallel backend being registered prior to running turboSim(). See *Details* of foreach.

method.names

Vector of unique names that identify the algorithms being compared.

keep.pars

Logical indicating whether the parameter values at termination should be kept. Defaults to FALSE.

control.method

If method = c(method1, method2, ...), then control.method = list(list1, list2, ...) where list1 is the list of control parameters for method1, list2 is the list of control parameters for method2, and so on. If length(method) == 1, then control.method is the list of control parameters for the acceleration scheme. See *Details* of turboem.

control.run

List of control parameters for convergence and stopping the algorithms. See *Details* of turboem.

...

Arguments passed to fixptfn and objfn.

Value

turboSim returns an object of class turbosim.

See Also

turbosim, turboem

Examples

###########################################################################
# Examples provided in the vignette, which can be seen by typing
#  vignette("turboEM")