subjob: Subjob - Compute one Row of the Virtual Grid
In simsalapar: Tools for Simulation Studies in Parallel

subjob

R Documentation

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.

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

simsalapar documentation built on April 27, 2023, 9:05 a.m.