turbosimMethods: Methods for objects of class "turbosim"

In turboEM: A Suite of Convergence Acceleration Schemes for EM, MM and Other Fixed-Point Algorithms

Methods for objects of class "turbosim"

Description

The turbosim class represents results from benchmark studies of algorithms to acceleration parameter estimation in fixed-point mapping problems.

Usage

## S3 method for class 'turbosim'
print(x, ...)
## S3 method for class 'turbosim'
summary(object, which.methods = seq_along(object$method), 
method.names = object$method.names[which.methods], eps = 0.1, sol = NULL, ...)
## S3 method for class 'turbosim'
boxplot(x, which.methods = seq_along(x$method), 
method.names = x$method.names[which.methods], 
whichfail = (x$fail | !x$conv)[,which.methods], xunit="sec", log=FALSE, ...)
## S3 method for class 'turbosim'
dataprof(x, which.methods = seq_along(x$method), 
method.names = x$method.names[which.methods], 
whichfail = (x$fail | !x$conv)[,which.methods], col, lty, nout = 50, xlim, ...)
## S3 method for class 'turbosim'
pairs(x, which.methods=seq_along(x$method), 
method.names = x$method.names[which.methods], 
whichfail = (x$fail | !x$conv)[,which.methods], ...)

Arguments

object	An object of class turbosim, the structure of which is described in *Details*.
x	An object of class turbosim, the structure of which is described in *Details*.
which.methods	A vector identifying for which subset of algorithms results are desired.
method.names	A vector of unique identifiers for the algorithms for which results are being provided.
eps	Used to define a tolerance between the objective function value attained by a particular acceleration scheme and the best achievable objective function value (either across schemes or as defined by the user). See *Details*.
sol	Optional argument defining the best achievable objective function value for a given fixed-point mapping problem. Defaults to NULL. See *Details*.
xunit	Units for running time to be used in the boxplots. Argument takes the value "sec" or "min."
log	Logical indicating whether the log of the running time will be plotted. Defaults to FALSE.
whichfail	A matrix of logical values where the (i,j)-entry indicates whether algorithm j of simulation iteration i failed (however the user wishes to define a failure for visualization purposes). If argument is not provided by user, then by default a failure is defined to be the event where the algorithm produces an error *or* does not converge.
col	Optional argument: A vector where each component defines the color for the line corresponding to each algorithm being compared.
lty	Optional argument: A vector where each component defines the line-type for the line corresponding to each algorithm being compared.
nout	Number of values at which the empirical distribution function is estimated. Should be less than the number of simulation iterations.
xlim	Optional argument: Defines the x-axis limits for the data profile. Defaults to the full range of the running times over all algorithms being plotted.
...	Additional arguments.

Details

An object of class turbosim is typically the product of the function turboSim. It is a list containing at least the following components:

method.names

Vector of unique identifiers for the algorithms being compared

fail

Matrix whose (i,j)-element is a logical (TRUE/FALSE) for whether the jth algorithm at the ith benchmark study repetition failed (produced an error).

convergence

Matrix whose (i,j)-element is a logical (TRUE/FALSE) for whether the jth algorithm at the ith benchmark study repetition satisfied the convergence criterion before termination.

value.objfn

Matrix whose (i,j)-element is the value of the objective function of the jth algorithm at the ith benchmark study repetition.

runtime

Matrix whose (i,j)-element is the running time of the jth algorithm at the ith benchmark study repetition.

itr

Matrix whose (i,j)-element is the number of completed iterations of the jth algorithm at the ith benchmark study repetition.

fpeval

Matrix whose (i,j)-element is the number of fixed-point function evaluations of the jth algorithm at the ith benchmark study repetition.

objfeval

Matrix whose (i,j)-element is the number of objective function evaluations of the jth algorithm at the ith benchmark study repetition.

errors

Matrix whose (i,j)-element contains the error message produced by the jth algorithm at the ith benchmark study repetition (if there was an error).

This list usually will also contain the components fixptfn, objfn, method, pconstr, project, control.method, and control.run, which were provided as arguments for turboSim.

The summary function shows a table of the number of failures across acceleration schemes. There are three types of failures. The first occurs when the algorithm produces an error message. The second is if the algorithm does not converge before the alternative stopping rule is achieved (e.g. the maximum number of iterations or maximum pre-specified runtime is reached). The third is if the algorithm claims convergence but the value of the objective function is "far" from the best achievable value. To assess this third type of failure, we determine whether the objective function value achieved by the algorithm is close (within eps) to the smallest value achieved across all algorithms at that simulation iteration. Alternatively, if the user knows a priori the true objective function value, he/she may specify the argument sol, in which case, the third type of failure occurs when the objective function value achieved by the algorithm is within eps of sol.

Further details for each of the methods are provided in the vignette, which can be seen by typing vignette("turboEM").

Value

summary	Summarizes the number of failures by type across simulation iterations for each acceleration scheme.
boxplot	Shows box plots of algorithm running times for each acceleration scheme.
dataprof	Plots the data profile, or the estimated distribution function of the time until convergence for each acceleration scheme.
pairs	Scatterplot matrix showing pairwise comparison of the running times for each pair of acceleration schemes.

See Also

turboem, turbo

Examples

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

turboEM documentation built on April 14, 2025, 1:09 a.m.