array-stuff {simsalapar}

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

x

for

ul()

a list.

mkAL(), saveSim()

a list (of length n.sim * nrow(pGrid)) where each element is a list of length five, containing the named elements "value", "error", "warning", "time", and ".Random.seed", the first four as returned by doCallWE().

getArray()

an array of lists as returned by mkAL().

array2df()

a numeric array as returned by getArray(*, "value").

vList

a list of variable specifications. Each variable specification is itself a named list which must contain a "value" component.

repFirst

logical; must match the value of repFirst in the x <- do*Apply() call where x has been created.

check

logical activating consistency checks for x.

sfile

a file name, typically with extension ‘.rds’ or NULL.

doAL

logical indicating if mkAL() should be called, or rather just x be saved.

msg

logical indicating whether a message is printed when an object is read from sfile.

err.value

numeric which is used to replace the value of the array entry in case of an error.

comp

character string denoting the component.

FUN

function to be applied right before the resulting array array is constructed.

responseName

(for arrady2df():) a string specifying the name of the “value” column of the resulting data frame.

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)