turbosim: 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 turbosim
print(x, ...)
# S3 method for turbosim
summary(object, which.methods = seq_along(object$method), 
method.names = object$method.names[which.methods], eps = 0.1, sol = NULL, ...)
# S3 method for 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 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 turbosim
pairs(x, which.methods=seq_along(x$method), 
method.names = x$method.names[which.methods], 
whichfail = (x$fail | !x$conv)[,which.methods], ...)

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.

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 \(j\)th algorithm at the \(i\)th benchmark study repetition failed (produced an error).
convergence: Matrix whose (\(i\),\(j\))-element is a logical (TRUE/FALSE) for whether the \(j\)th algorithm at the \(i\)th 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 \(j\)th algorithm at the \(i\)th benchmark study repetition.
runtime: Matrix whose (\(i\),\(j\))-element is the running time of the \(j\)th algorithm at the \(i\)th benchmark study repetition.
itr: Matrix whose (\(i\),\(j\))-element is the number of completed iterations of the \(j\)th algorithm at the \(i\)th benchmark study repetition.
fpeval: Matrix whose (\(i\),\(j\))-element is the number of fixed-point function evaluations of the \(j\)th algorithm at the \(i\)th benchmark study repetition.
objfeval: Matrix whose (\(i\),\(j\))-element is the number of objective function evaluations of the \(j\)th algorithm at the \(i\)th benchmark study repetition.
errors: Matrix whose (\(i\),\(j\))-element contains the error message produced by the \(j\)th algorithm at the \(i\)th 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").

Examples

Run this code


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