getRNG: 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.

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.

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

Examples

Run this code

# NOT RUN {
#--- 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)


# }