Tools for Simulation Studies in Parallel with R

Description

Tools for setting up, conducting, and evaluating larger-scale simulation studies, including parallel computations, in R.

Details

The DESCRIPTION file:

Index of help topics:

dev.off.pdf             Cropping and Font Embedding PDF Device
doCallWE                Innermost Computation: Error Catching Version
                        of do.call()
doCheck                 Checking a User's doOne
doLapply                Functions for Iterating Over All Subjobs
expr2latex              Translate 'plotmath' expressions to LaTeX
getEl                   Tools For Working with Variable Specification
                        Lists
LEseeds                 Advancing .Random.seed for "L'Ecuyer-CMRG"
mayplot                 Matrix-like Plot for Arrays up to Rank 5
simsalapar-package      Tools for Simulation Studies in Parallel with R
subjob                  Subjob - Compute one Row of the Virtual Grid
toLatex.ftable          Convert Flat Contingency Table (ftable) and
                        VarLists to LaTeX Table
tryCatch.W.E            Catching and Storing Warnings and Errors
                        Simultaneously
ul                      Tools For Converting To and From Arrays, Lists,
                        and Array of Lists
varlist                 Variable Specification List - Generation and
                        Class
wrapLaTable             Wrapper for a floating LaTeX Table

Setting up a simulation

varlist()

creates a variable specification list.

dimnames2varlist()

creates a variable specification list from given dimension names.

getEl()

extracts elements from a variable list.

mkGrid()

function for creating a grid of all variables of type “grid”; see mkGrid().

mkNms()

builds a list of names from a variable list; see mkNms().

get.n.sim()

extracts “n.sim”; see get.n.sim().

get.nonGrids()

extracts all variables not of type “grid”; see get.nonGrids().

Conducting a simulation

tryCatch.W.E()

catching and storing warnings and errors simultaneously; see tryCatch.W.E().

doCallWE()

innermost computation (return value of doOne()): returns value, error, warning, and run time; see doCallWE().

LEseeds()

create a list of advanced .Random.seed's for “L'Ecuyer-CMRG”; see LEseeds().

printInfo()

displays information about the sub-job just finished; see printInfo().

subjob()

computes one row of the virtual grid in a simulation; see subjob().

mkTimer()

creates a function to be passed to doCallWE() as timer; see mkTimer().

doLapply()

sequentially iterates over all subjobs via standard lapply().

doForeach()

iterates over all subjobs in parallel (via foreach(), package foreach).

doRmpi()

iterates over all subjobs in parallel (via Rmpi's mpi.apply()).

doMclapply()

iterates over all subjobs in parallel (via mclapply()).

doClusterApply()

iterates over all subjobs in parallel (via clusterApply()).

Analysis

doRes.equal()

convenience wrapper for comparing two results of the do* lapply-like functions; see doRes.equal().

mkAL()

converts a list of named 5-lists to an array of lists; see mkAL().

saveSim()

(optionally) converts a result list to an array of lists using mkAL(); see saveSim().

maybeRead()

(optionally) reads the provided .rds; see maybeRead().

getArray()

gets an array of 4-lists and computes an array of values, errors, warnings, or run times; see getArray().

array2df()

conveniently converts an array to a data.frame.

toLatex():

an S3 method for varlist and ftable.

fftable()

essentially calls format.ftable() and adds attributes ncv and nrv to the return object.

tablines()

computes ingredients for converting a character matrix with attributes to a LaTeX table.

wrapLaTable()

wraps a table and tabular environment around the lines of the body of a LaTeX table.

mayplot():

a matrix-like plot for arrays up to rank 5, with grid and gridBase.

Author(s)

Marius Hofert and Martin Maechler <maechler@stat.math.ethz.ch>

Maintainer: Marius Hofert <marius.hofert@math.ethz.ch>

References

Publication

Marius Hofert, Martin Maechler (2016). Parallel and Other Simulations in R Made Easy: An End-to-End Study. Journal of Statistical Software, 69(4), 1–44. doi:10.18637/jss.v069.i04

Preprint (for simsalapar 1.0-0; including timing info):

Hofert, M. and Mächler, M. (2013). Parallel and other simulations in R made easy: An end-to-end study. https://arxiv.org/abs/1309.4402

Examples

## Not run:  
 demo(TGforecasts)

## End(Not run)

Advancing .Random.seed for "L'Ecuyer-CMRG"

Description

LEseeds() creates a list of advanced .Random.seed's for "L'Ecuyer-CMRG".

Usage

LEseeds(n)

Arguments

Details

See, for example, Hofert and Mächler (2014) for how to use these functions.

Value

A list of length n containing the advanced .Random.seed's.

Author(s)

Marius Hofert and Martin Maechler.

See Also

.Random.seed for information about random number generators and seeds.

Tools For Converting To and From Arrays, Lists, and Array of Lists

Description

ul()

is a simple wrapper for unlist() with recursive=FALSE.

mkAL()

gets a list x with elements that are named lists of length five, see x below, and converts it to an array of lists.

saveSim()

(optionally) converts a result list to an array using mkAL() and (optionally) saves it to a file via saveRDS().

maybeRead()

if the provided ‘.rds’ file exists, this function reads it via readRDS(); otherwise, nothing is done.

getArray()

gets an array of 4-lists as returned by mkAL(), picks out the specified component comp, applies the specified function FUN (with useful defaults), and builds an array.

array2df()

auxiliary function to convert an array to a data.frame (correctly dealing with n.sim).

Usage

ul(x)

mkAL   (x, vList, repFirst, check=TRUE)
saveSim(x, vList, repFirst, sfile, check=TRUE, doAL=TRUE)

maybeRead(sfile, msg=TRUE)

getArray(x, comp=c("value", "error", "warning", "time"),
         FUN=NULL, err.value=NA)

array2df(x, responseName = "value")

Arguments

Details

mkAL() is useful when creating arrays from result lists returned from large(r) simulation studies which use doCallWE(). To create a proper argument x for mkAL(), the function ul() turns out to be useful to (stepwise) unlist nested lists.

getArray() converts arrays of lists as returned by mkAL() to an array of numeric (or logical, see below) after applying the specified FUN.
In case of an error, the corresponding entry in the resulting array is replaced by err.value.

The default FUN converts possible errors and warnings to logical (indicating whether there was a error or warning, respectively) and run times to numeric. For comp="value", the situation is trickier. First of all, the resulting array contains dimensions for variables of type “inner” and, if greater than 1, for the variable of type “N” (typically called "n.sim"); see the vignette for details.
Use FUN = identity to get at the full error or warning objects, for comp = "error" or for comp = "warning", respectively.

saveSim() and maybeRead() are useful for creating and (re)storing arrays from large(r) simulation studies (to avoid recomputation, to ease the data analysis etc.). saveSim() calls mkAL(), nowadays wrapped in tryCatch(.), such that the simulation is not lost, even when the resulting format cannot correctly be treated by mkAL(). Consequently, doAL is not much needed anymore. Note that both saveSim() and maybeRead() accept sfile=NULL in which case nothing is saved or read.

Value

For

ul()

the unlisted list; see unlist().

mkAL()

an array of lists.

saveSim()

the array returned by mkAL().

maybeRead()

the object read by readRDS() from sfile or nothing (if sfile does not exist).

getArray()

an array containing the values of the specified component comp after applying FUN to them. The default FUN produces an array, depending on comp, of

"value":

values or err.value (in case of an error)

"error":

logicals indicating whether there was an error

"warning":

logicals indicating whether there was a warning

"time":

timings as returned by doCallWE(), i.e., typically (from mkTimer's proc.time()[1]) the number of milliseconds of “"CPU user time"”.

array2df(x)

a data.frame with several columns built from the dimnames(x) and a column named responseName with the values of x.

Author(s)

Marius Hofert and Martin Maechler.

References

see simsalapar-package.

See Also

getEl() and mkNms() used by mkAL(). saveRDS() and readRDS(), the “workhorses” of saveSim() and maybeRead(), respectively.

Examples

## Not run: 
## Get at the full error objects, notably (message, call):
errObjs <- getArray(res, "error", FUN=identity)

## End(Not run)

if(FALSE) ## A longer, "interesting" example is in
 demo(robust.mean)

Cropping and Font Embedding PDF Device

Description

dev.off.pdf() is a wrapper of dev.off() which is meant for closing a pdf device. It also performs cropping and font embedding if chosen.

Usage

dev.off.pdf(file="Rplots.pdf", crop=NULL, embedFonts="", ...)

Arguments

Value

invisible().

Author(s)

Marius Hofert

See Also

dev.off() for closing a device, embedFonts() for font embedding. sfsmisc's pdf.end() for another approach.

Examples

## typical usage
doPDF <- !dev.interactive(orNone=TRUE)
if(doPDF) pdf(file=(file <- "crop_device.pdf"), width=6, height=6)
plot(1)
if(doPDF) dev.off.pdf(file)
if(file.exists(file)) file.remove(file)

Functions for Iterating Over All Subjobs

Description

doLapply() iterates over all subjobs (using the non-parallel lapply()). Similarly, but in parallel, for doForeach (based on CRAN package foreach's foreach()), doRmpi (based on Rmpi's mpi.apply()), doMclapply (based on parallel's mclapply()), and doClusterApply (based on parallel's clusterApply()).

doRes.equal() is simple convenience wrapper for all.equal(), for comparing two results (from the same varlist and doOne arguments) of the do* lapply-like functions above.

Usage

doLapply(vList, seed="seq", repFirst=TRUE,
       sfile=NULL, check=TRUE, doAL=TRUE, subjob.=subjob, monitor=FALSE,
       doOne, ...)
doForeach(vList, cluster=makeCluster(detectCores(), type="PSOCK"),
       cores=NULL, block.size = 1, seed="seq", repFirst=TRUE,
       sfile=NULL, check=TRUE, doAL=TRUE, subjob.=subjob, monitor=FALSE,
       doOne, extraPkgs=character(), exports=character(), ...)
doRmpi(vList,
       nslaves = if((sz <- Rmpi::mpi.universe.size()) <= 1) detectCores() else sz,
       load.balancing=TRUE, block.size = 1, seed="seq", repFirst=TRUE,
       sfile=NULL, check=TRUE, doAL=TRUE, subjob.=subjob, monitor=FALSE,
       doOne, exports=character(), ...)
doMclapply(vList, cores = if(.Platform$OS.type == "windows") 1 else detectCores(),
       load.balancing=TRUE, block.size = 1, seed="seq", repFirst=TRUE,
       sfile=NULL, check=TRUE, doAL=TRUE, subjob.=subjob, monitor=FALSE,
       doOne, ...)
doClusterApply(vList, cluster=makeCluster(detectCores(), type="PSOCK"),
       load.balancing=TRUE, block.size = 1, seed="seq", repFirst=TRUE,
       sfile=NULL, check=TRUE, doAL=TRUE, subjob.=subjob, monitor=FALSE,
       doOne, initExpr, exports=character(), ...)

doRes.equal(x, y, tol = 1e-15, ...)

Arguments

Details

See the vignette or references in simsalapar-package for how to use these functions.

For reasons to choose "MPI" as cluster type (if not on Windows), see the discussion starting at https://stat.ethz.ch/pipermail/r-sig-hpc/2013-April/001647.html.

For doForeach(), precisely one of cluster or cores has to be not NULL. This will determine whether the parallel computations are carried out on a cluster with multiple nodes or on a multi-core processor.

Value

The result of applying subjob() to all subjobs, converted with saveSim().

Author(s)

Marius Hofert and Martin Maechler.

See Also

subjob() for computing a subjob. doCallWE() for the return value of doOne(). .Random.seed for information about random number generators and seeds.

Examples

 if(simsalapar:::doExtras()) { ## needs some CPU
   demo(robust.mean) # 512 simulations, differing block sizes, ...
 }

Innermost Computation: Error Catching Version of do.call()

Description

doCallWE() performs the innermost computation of the simulation study at hand. It is a version of do.call(f, argl, *), with care of catching and storing both error and warnings (via tryCatch.W.E()) and measures user time. This is useful in large(r) simulation studies.

mkTimer() returns a function to be passed as timer to doCallWE().

Usage

doCallWE(f, argl, 
         timer = mkTimer(gcFirst=FALSE))

mkTimer(gcFirst)

Arguments

Details

Note that gcFirst=FALSE is default for a good reason: if a call to doOne() is relatively fast, calling gc() every time is unnecessarily expensive and may completely dominate the overall simulation run time. For serious run time measurement, gcFirst=TRUE is preferable, as it ensures less variable timings, see system.time.

Value

doCallWE() returns a list with components

Author(s)

Marius Hofert and Martin Maechler.

See Also

do.call, tryCatch.W.E.

Examples

set.seed(61)
L <- log(abs(rt(n=100, df = 1.5)))
r <- doCallWE(quantile, list(L, probs= 0.95))
## set timer for  "no timing" :
u <- doCallWE(quantile, list(L, probs= 0.95), timer = function(E) { E; NULL })
stopifnot(is.null(r$error),
	  all.equal(r$value, quantile(L, 0.95)),
	  identical(r[1:3], u[1:3]), is.null(u[["time"]]))

Checking a User's doOne

Description

doCheck() checks, if possible, a user's doOne() function for return objects of correct sizes.

Usage

doCheck(doOne, vList, nChks = ng, verbose = TRUE)

Arguments

Value

None.

Author(s)

Marius Hofert and Martin Maechler.

Examples

## definition
doCheck

Translate 'plotmath' expressions to LaTeX

Description

expr2latex() translates a “R graphics annotation” expression to the corresponding LaTeX one.

escapeLatex(), very similar to its original, escape_latex() from fortunes, escapes certain character combinations, such that the result can be used in LaTeX.

Usage

expr2latex(expr)
escapeLatex(x)

Arguments

Details

The expr2latex() function is recursively rendering (sub) expressions, until it uses the internal renderAtom() for simple symbols (is.symbol).

We currently work with some tables of math annotation expressions, lifted from the corresponding C source of R itself. (Hidden in simsalpar's namespace, we have AccentTable, BinTable, RelTable, Lgreek and Ugreek, currently.)

The current implementation is still incomplete.

Value

a character string with the LaTeX expression corresponding to “R graphics annotation” expression expr.

Author(s)

Martin Maechler.

See Also

plotmath for mathematical expressions to annotate R graphics.

toLatex() and its ftable method, toLatex().

Examples

expr2latex( quote( N[sim] ) )
expr2latex( quote( N[sim] ~ O(n) ) )
expr2latex( quote(x %notin% N) )
expr2latex( quote(x %+-% epsilon) )
expr2latex( quote(N[s*m^2]) )
expr2latex( quote( 2^{N[sim] - 3} ~~~ O(n^{n^2}) ) )

escapeLatex(c("#{positives}", "A | B"))

Tools For Working with Variable Specification Lists

Description

From a variable specification list (varlist),

getEl()

gets elements of a variable specification list that match the given variable type.

mkGrid()

builds a grid, e.g., for parallel evaluation, basically by calling do.call(expand.grid, <list>).

mkNms()

builds a list of names, e.g., to be used as dimnames for a corresponding simulation result array.

get.n.sim()

extracts n.sim or returns 1 if it is not contained in vList.

set.n.sim()

modifies or sets n.sim in vList.

get.nonGrids()

extracts all variables not having type="grid" and returns n.sim the same as get.n.sim().

Usage

getEl       (vList, type = "ALL", comp = "value")
mkGrid      (vList)
mkNms       (vList, addNms = FALSE)
get.n.sim   (vList)
set.n.sim   (vList, n)
get.nonGrids(vList)

Arguments

Details

These functions are useful when working with variable specification lists.

Value

For

getEl()

a named list containing the selected components of those variables that match the provided type.

mkGrid()

a data frame (data.frame).

mkNms()

a named list of the same length() and with the same names() as vList.

get.n.sim()

n.sim if it is contained in vList, 1 otherwise.

set.n.sim()

the varlist vList with a modified n.sim.

get.nonGrids()

list of length 2 containing the (possibly modified) n.sim and a list containing all variables not having type="grid".

Author(s)

Marius Hofert and Martin Maechler.

See Also

varlist, for construction of variable lists. expand.grid, the “workhorse” of mkGrid().

Examples

vList <-
 varlist(n.sim = list(type="N", expr = quote(N[sim]), value = 64),
         n     = list(type="grid",
                      value = c(20, 100, 500)), # sample sizes
         p     = list(type="grid",
                      value = c(3, 7, 15, 25)), # dimensions
         meth  = list(type="grid", expr = quote(italic(method)),
                      value = c("classical", "robust")))

getEl(vList, type="grid") # for those of type "grid", get all values
## for those of type "grid", get all components :
str(getEl(vList, type="grid", comp=NA))
stopifnot(identical(as(vList, "list"),
                    getEl(vList, type=c("N","grid"), comp = NA)))

(grd <- mkGrid(vList))
stopifnot(nrow(grd) == 3*4*2, ncol(grd) == 3)

getEl(vList)# -> all "value"s: the same as lapply(., `[[`, "value") :
stopifnot(identical(lapply(vList, `[[`, "value"),
                    getEl(vList)))
mkNms(vList)
mkNms(vList, addNms=TRUE)

get.n.sim(vl. <- set.n.sim(vList, NULL)) # 1
vl.$n.sim # NULL
set.n.sim(vl., 12)

Matrix-like Plot for Arrays up to Rank 5

Description

Produces a matrix-like plot for arrays up to rank 5, using grid and gridBase which allows traditional graphics, optionally via a user specified panel function panel.

Usage

mayplot(x, vList, row.vars = NULL, col.vars = NULL,
        xvar, method = if(has.n.sim) "boxplot" else "lines",
       panel.first = NULL, panel.last = NULL,
       type = "l", pch = NULL, ylim = "global",
       log = "", do.legend = TRUE,
       spc = c(0.04/max(1,n.x-1), 0.04/max(1,n.y-1)),
       axlabspc=c(0.12, 0.08), labspc=c(0.04, 0.04),
       n.sim.spc = 0.06, auxcol = c("gray40", "gray78", "gray90", "white"),
       pcol = c("black", "blue", "red", "orange"), grid.lwd = 1.6, ax.lwd = 2,
       tx.cex = 1.2, leg.cex = 1, xlab = NULL, ylab = NA,
       do.n.sim = has.n.sim,
       verbose = getOption("verbose"), show.layout = verbose, ...)

Arguments

Value

the layout, invisibly.

Author(s)

Marius Hofert and Martin Maechler.

See Also

matplot unit and grid.layout from package grid.

Examples

vLis <-
 varlist(d = list(type="grid", value = c(10, 100, 1000)),
         family=list(type="grid", value = c("Clayton", "Gumbel")),
         tau = list(type="grid", value = c(0.25, 0.5)),
         alpha = list(type="inner", value = c(0.95, 0.99, 0.999)))

iP <- c(4, 1:3)# <- permutation, putting alpha first
dNms <- mkNms(vLis)[iP]
## an array as from  x <- getArray( doMclapply(vLis, ..) ) :
x <- array(
    c(6.1981, 8.0478, 8.4265, 46.883, 74.359, 86.4394, 432.585, 743.27, 859.35,
      4.8508, 6.0286, 6.3965, 26.380, 35.132, 47.1517, 243.113, 311.36, 342.84,
      7.8546, 8.9769, 9.2199, 78.235, 89.493, 92.2875, 785.674, 893.63, 923.62,
      7.7164, 8.2866, 8.8169, 75.959, 82.806, 88.0626, 756.786, 831.65, 874.70),
    dim = sapply(dNms, length), dimnames = dNms)

mayplot(x, vLis, row.vars="family", col.vars="tau", xvar="alpha", log="y",
       ylab=bquote(widehat(VaR)[alpha]))
## the same, but no xlab and no ylab :
mayplot(x, vLis, row.vars="family", col.vars="tau", xvar="alpha", log="y", xlab=NA)

Subjob - Compute one Row of the Virtual Grid

Description

subjob() computes one row of the virtual grid in a simulation study, provides several seeding methods, and sub-job monitoring (information about the sub-job just finished).

printInfo is a named list of functions optionally to be used as monitor in subjob() for printing information at the end of each sub-job.

Usage

subjob(i, pGrid, nonGrids, n.sim, seed, keepSeed = FALSE,
       repFirst = TRUE, doOne,
       timer = mkTimer(gcFirst=FALSE), monitor = FALSE, ...)

printInfo # or
# printInfo[["default"]]

Arguments

Details

See the vignette or references in simsalapar-package for how to use these functions.

The case where seed is a numeric vector of length n.sim also leads to the same results no matter which variables are of type “grid” or “inner”; see demo(robust.mean) where this is tested. This is important to guarantee since one might want to change certain “inner” variables to “grid” variables due to load-balancing while computing the desired statistics based on the same seed (or generated data from this seed).

Value

printInfo

is a named list of functions which produce output (cat(..)) containing information about the sub-job which subjob() has just finished. Note that components "gfile" (“global file”) and "fileEach" each direct the monitoring output to files.

subjob()

returns a vector of length five if keepSeed is true and seed is not NA, otherwise (also by default), of length four. The first four components contain the return value of doCallWE(). If keepSeed is true, the fifth component contains .Random.seed before the call of doCallWE() (for reproducibility).

Author(s)

Marius Hofert and Martin Maechler.

See Also

doCallWE(); .Random.seed for information about random number generators and seeds.

For examples of implicit use of subjob, see doLapply.

Examples

names(printInfo)# currently "default", "gfile", "fileEach"

str(printInfo, give.attr=FALSE)
## the functions in printInfo share a common environment() with utility functions:
ls.str(environment(printInfo$default))
if(FALSE) # show them all
as.list(environment(printInfo$default))

Convert Flat Contingency Table (ftable) and VarLists to LaTeX Table

Description

The ftable method of toLatex() converts an ftable to a LaTeX table via tablines().

Analogously, the varlist method of toLatex() converts an varlist to a LaTeX table.

fftable() essentially calls format.ftable() and adds attributes ncv and nrv to the return object.

tablines() computes ingredients for converting a character matrix with attributes to a LaTeX table.

cattablines() is a small auxiliary function which creates rows of a LaTeX table from a given matrix.

Usage

## S3 method for class 'ftable'
toLatex(object, vList = NULL,
        x.escape = FALSE, exprFUN = expr2latex, escapeFUN = escapeLatex,
        align = NULL, booktabs = TRUE, head = NULL,
	rsep = "\\\\", sp = if(booktabs) 3 else 1.25, rsep.sp = NULL,
	csep = " & ", quote = FALSE, lsep=" \\textbar\\ ",
	do.table = TRUE, placement = "htbp", center = TRUE,
	fontsize = "normalsize", caption = NULL, label = NULL, ...)

## S3 method for class 'varlist'
toLatex(object,
	col.vars = c("Variable", "expression", "type", "value"),
	exprFUN = expr2latex, escapeFUN = escapeLatex,
	align = NULL, booktabs = TRUE, head = NULL,
	rsep = "\\\\", sp = if(booktabs) 3 else 1.25, rsep.sp = NULL, csep = " & ",
	do.table = TRUE, placement = "htbp", center = TRUE,
	fontsize = "normalsize", caption = NULL, label = NULL, ...)

fftable(x, lsep = " | ", quote = FALSE, method = "compact", ...)

tablines(x, align = NULL, booktabs = TRUE, head = NULL,
	 rsep = "\\\\", sp = if(booktabs) 3 else 1.25, rsep.sp = NULL,
	 csep = " & ", quote = FALSE)

cattablines(x, rsep = "\\\\", csep = " & ", include.rownames = TRUE)

Arguments

Value

toLatex() returns an object as from wrapLaTable().

fftable() returns a formatted flat contingency table as returned by format.ftable() with added attributes ncv (number of column variables) and nrv (number of row variables).

tablines() a list with components

cattablines() outputs the formatted lines for copy-and-paste into a LaTeX table.

Author(s)

Marius Hofert and Martin Maechler.

References

see simsalapar-package.

See Also

wrapLaTable() for how to wrap the lines of a LaTeX table created by tablines() in a LaTeX table and tabular environment.

Examples

## Different table layouts for the same content
(ft1 <- ftable(Titanic, col.vars = 1:4))
(ft2 <- ftable(Titanic, row.vars = 1))
(ft3 <- ftable(Titanic, row.vars = 1:2))
(ft4 <- ftable(Titanic, row.vars = 1:3))
(ft5 <- ftable(Titanic, row.vars = 1:4))

## What tablines() returns
tablines(fftable(ft2))

## LaTeX (booktabs/non-booktabs) versions
toLatex(ft1, do.table=FALSE)
toLatex(ft1, booktabs=FALSE)
toLatex(ft1, method="col.compact")
toLatex(ft1)
toLatex(ft2)
toLatex(ft3)
toLatex(ft4)
toLatex(ft5, booktabs=FALSE)
toLatex(ft5, method="col.compact")
toLatex(ft5)

## ``poor-man's approach'' for creating lines of a LaTeX table
set.seed(271)
tab <- matrix(runif(6), ncol=3)
ftab <- formatC(tab, digits=4, format="f")
cattablines(ftab)
rownames(ftab) <- LETTERS[1:nrow(ftab)]
cattablines(ftab)

Catching and Storing Warnings and Errors Simultaneously

Description

Catches and saves both warnings (warning) and errors (stop) and in the case of a warning, also the computed result.

Usage

tryCatch.W.E(expr)

Arguments

Details

This function is particularly useful in large(r) simulation studies to check all computations and guarantee their correctness.

Value

list with components

Author(s)

Marius Hofert and Martin Maechler, based on hints from Luke Tierney and Bill Dunlap, see https://stat.ethz.ch/pipermail/r-help/2010-December/262626.html.

References

see simsalapar-package.

See Also

the base function tryCatch() and demo(error.catching). Also, doCallWE(), of which tryCatch.W.E() is the “workhorse”.

Examples

## Adapted from demo(error.catching) :
str(r1 <- tryCatch.W.E( log( 2 ) ) )
str(r2 <- tryCatch.W.E( log(-1 ) ) )
str(r3 <- tryCatch.W.E( log("a") ) )
stopifnot(is.null(r1$warning),
          is.na  (r2$value),   inherits(r2$warning, "warning"),
          is.null(r3$warning), inherits(r3$value, "error"))

Variable Specification List - Generation and Class

Description

Generate variable specification lists. These are objects of the formal (aka “S4”) class "varlist". This class simply extends "namedList" and has a validity method (see validObject).

Usage

varlist(...)
dimnames2varlist(dmn)
## S4 method for signature 'varlist'
show(object)

Arguments

Details

value is typically an atomic vector (is.atomic) or a list, e.g., of functions; in the latter case, typically with names.

type can be one of "N", "frozen", "grid", or "inner". In short:

"N"

This type is reserved for a (single) variable named n.sim which provides the simulation replications; if it is not given, n.sim is implicitly treated as 1.

"frozen"

Variables of this type remain fixed (they do not vary) throughout the whole simultion study. They affect the final result but do not appear as a dimension in the result array of the simulation study. This is the default type (apart from n.sim which defaults to "N").

"grid"

Variables of this type are used to build a (physical) grid (a data.frame) with number of rows equal to the product of the lengths of all variables of this type. The simulation will use this grid to iterate n.sim times over all of its rows for conducting the required computations. Conceptually, this corresponds to iterating over a virtual grid seen as n.sim copies of the (physical) grid pasted together. The computations for one row in this virtual grid form one sub-job. One can use one of doLapply(), doForeach(), doRmpi(), doMclapply(), or doClusterApply() to iterate over all sub-jobs.

"inner"

Variables of this type are all dealt with within a sub-job for reasons of convenience, speed, load balancing etc.

The dimnames2varlist() functions creates a varlist from a named list of character vectors, typically resulting from dimnames(tt) of a table tt, see the Titanic example below.

For more details, see Hofert and Mächler (2014), and also the examples in demo(package="simsalapar") .

Value

an object of formal (aka “S4”) class "varlist".

Author(s)

Martin Maechler.

See Also

namedList; getEl for easy extraction of elements from a "varlist".

The toLatex method for varlists, toLatex.varlist.

doLapply(), doForeach(), doRmpi(), doMclapply(), doClusterApply() for the functions to iterate over the virtual grid.

Examples

showClass("varlist")

vList <- varlist(
    n.sim = list(value = 1000, expr = quote(N[sim])), # type = N
    n     = list(type="grid", value = c(20, 100, 500)), # sample sizes
    meth  = list(type="grid", expr = quote(italic(method)),
                 value = c("classical", "robust")),
    alpha = list(value = 0.95)) # default type = "frozen"

str(vList)# note the default 'expr' for  n and alpha; and type of alpha

## For more extensive examples, see also
demo(package="simsalapar")

## coerce to simple list  .. and back :
lvl <- as(vList, "list")
stopifnot(identical(
    do.call(varlist, lvl),
    vList ))

## From a data.frame to a LaTeX table :
str(dimnames(Titanic))
vlTitan <- dimnames2varlist(dimnames(Titanic))
vlTitan  # default 'type = "grid"' here
toLatex(vlTitan)

Wrapper for a floating LaTeX Table

Description

wrapLaTable() wraps (a table and tabular environment) around the lines of the body of a LaTeX table and utilizes writeLines() to write the LaTeX table.

Usage

wrapLaTable(x, align, do.table = TRUE, placement = "htbp", center = TRUE,
            fontsize = "normalsize", booktabs = TRUE,
            caption = NULL, label = NULL)

Arguments

Details

Note that necessary LaTeX packages (such as tabularx) have to be loaded in the preambel of the corresponding .tex or .Rnw file.

Value

a “LaTeX table”, of class "Latex" (where the print method uses writeLines()).

Author(s)

Marius Hofert.

References

see simsalapar-package.

See Also

toLatex() where it is used to create a LaTeX table.

Examples

ftab <- ftable(Titanic, row.vars = 1:2)
fftab <- fftable(ftab)
tlist <- tablines(fftab)

wrapLaTable(structure(tlist$body, head = tlist$head), align = tlist$align,
            caption="The Titanic data set.", label="tab:titanic")