subjob {simsalapar}

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

i

row number of the virtual grid. i.sim and j together determine i.

pGrid

“physical grid” of all combinations of variables of type "grid", as returned by mkGrid(<varlist>).

nonGrids

values of non-"grid"-variables (if provided, passed to doOne()), i.e., typically get.nonGrids(<varlist>)[["nonGrids"]].

n.sim

number of simulation replications.

seed

one of:

NULL

.Random.seed remains untouched. If it does not exist, generate it by calling runif(1). This case typically leads to non-reproducible results.

numeric(n.sim)

a numeric vector of length n.sim containing the seed for each simulation replications (same seed for each row in the (physical) grid; this ensures least variance across computations for the same replication). This case leads to reproducible results.

vector("list", n.sim)

a list of length n.sim containing seeds (typically numeric vectors) for each of the n.sim simulation replications (same seed for each row in the (physical) grid). The seeds are assigned to .Random.seed in globalenv() and can thus be used for other random number generators such as "L'Ecuyer-CMRG", see set.seed(). This case leads to reproducible results.

NA

.Random.seed remains untouched. If it does not exist, so be it. No fifth component is concatenated to the result of the doOne() call in this case even when keepSeed=TRUE (where in all other cases, the seed is appended as 5th component). This method typically leads to non-reproducible results.

character string

a character string specifying a seeding method. Currently only "seq" in which case the seeds 1 to n.sim for the n.sim simulation replications are used. This is the default. Functionally, it is a special case of the “numeric(n.sim)” specification above (with seed = 1:n.sim) and hence leads to reproducible results.

keepSeed

logical indicating if .Random.seed should be appended to each return value of doCallWE() - unless seed = NA.

repFirst

logical; if TRUE (the default), all n.sim replications are computed for a row in the (physical) grid first, before the next row is considered; if FALSE, first all rows of the (physical) grid are computed for a fixed replicate until the next replicate is considered.

doOne

function for computing one row in the (physical) grid; must return a numeric vector, matrix, or array.

timer

a function similar to system.time(), passed to doCallWE().

monitor

logical or function indicating whether or how monitoring output is displayed. TRUE defaults to the printInfo[["default"]] function.

...

additional arguments passed to doOne().

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))