rngtools: rng – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

rng

Getting/Setting RNGs

Description

getRNG returns the Random Number Generator (RNG) settings used for computing an object, using a suitable .getRNG S4 method to extract these settings. For example, in the case of objects that result from multiple model fits, it would return the RNG settings used to compute the best fit.

Usage

getRNG(object, ..., num.ok = FALSE, extract = TRUE, recursive = TRUE)

hasRNG(object)

nextRNG(object, ..., ndraw = 0L)

setRNG(object, ..., verbose = FALSE, check = TRUE)

Arguments

`object`	an R object from which RNG settings can be extracted, e.g. an integer vector containing a suitable value for `.Random.seed` or embedded RNG data, e.g., in S3/S4 slot `rng` or `rng$noise`.
`...`	extra arguments to allow extension and passed to a suitable S4 method `.getRNG` or `.setRNG`.
`num.ok`	logical that indicates if single numeric (not integer) RNG data should be considered as a valid RNG seed (`TRUE`) or passed to `set.seed` into a proper RNG seed (`FALSE`) (See details and examples).
`extract`	logical that indicates if embedded RNG data should be looked for and extracted (`TRUE`) or if the object itself should be considered as an RNG specification.
`recursive`	logical that indicates if embedded RNG data should be extracted recursively (`TRUE`) or only once (`FASE`).
`ndraw`	number of draws to perform before returning the RNG seed.
`verbose`	a logical that indicates if the new RNG settings should be displayed.
`check`	logical that indicates if only valid RNG kinds should be accepted, or if invalid values should just throw a warning. Note that this argument is used only on R >= 3.0.2.

Details

This function handles single number RNG specifications in the following way:

integers: Return them unchanged, considering them as encoded RNG kind specification (see RNG). No validity check is performed.
real numbers: If num.ok=TRUE return them unchanged. Otherwise, consider them as (pre-)seeds and pass them to set.seed to get a proper RNG seed. Hence calling getRNG(1234) is equivalent to set.seed(1234); getRNG() (See examples).

Value

getRNG, getRNG1, nextRNG and setRNG usually return an integer vector of length > 2L, like .Random.seed.

getRNG and getRNG1 return NULL if no RNG data was found.

setRNG invisibly returns the old RNG settings as they were before changing them.

Examples

#--- getRNG ---
# get current RNG settings
s <- getRNG()
head(s)
showRNG(s)

# get RNG from a given single numeric seed
s1234 <- getRNG(1234)
head(s1234)
showRNG(s1234)
# this is identical to the RNG seed as after set.seed()
set.seed(1234)
identical(s1234, .Random.seed)
# but if num.ok=TRUE the object is returned unchanged
getRNG(1234, num.ok=TRUE)

# single integer RNG data = encoded kind 
head(getRNG(1L))

# embedded RNG data
s <- getRNG(list(1L, rng=1234))
identical(s, s1234)
 

#--- hasRNG ---
# test for embedded RNG data
hasRNG(1)
hasRNG( structure(1, rng=1:3) )
hasRNG( list(1, 2, 3) )
hasRNG( list(1, 2, 3, rng=1:3) )
hasRNG( list(1, 2, 3, noise=list(1:3, rng=1)) )


#--- nextRNG ---
head(nextRNG())
head(nextRNG(1234))
head(nextRNG(1234, ndraw=10))


#--- setRNG ---

obj <- list(x=1000, rng=123)
setRNG(obj)
rng <- getRNG()
runif(10)
set.seed(123)
rng.equal(rng)

rngtools

Utility Functions for Working with Random Number Generators

v1.5

GPL-3

Authors

Renaud Gaujoux [aut, cre], Max Kuhn [ctb]

Initial release

rng