rngtools 1.2

Getting/Setting RNGs

Usage

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

hasRNG(object)

.getRNG(object, ...)

getRNG1(object, ...)

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

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

.setRNG(object, ...)

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.

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.

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.

hasRNG tells if an object has embedded RNG data.

.getRNG is an S4 generic that extract RNG settings from a variety of object types. Its methods define the workhorse functions that are called by getRNG.

getRNG1 is defined to provide separate access to the RNG settings as they were at the very beginning of a whole computation, which might differ from the RNG settings returned by getRNG, that allows to reproduce the result only.

nextRNG returns the RNG settings as they would be after seeding with object.

setRNG set the current RNG with a seed, using a suitable .setRNG method to set these settings.

.setRNG is an S4 generic that sets the current RNG settings, from a variety of specifications. Its methods define the workhorse functions that are called by setRNG.

Details

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

  1. integersReturn them unchanged, considering them as encoded RNG kind specification (see RNG). No validity check is performed.
  2. real numbersIf 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).

Think of a sequence of separate computations, from which only one result is used for the result (e.g. the one that maximises a likelihood): getRNG1 would return the RNG settings to reproduce the complete sequence of computations, while getRNG would return the RNG settings necessary to reproduce only the computation whose result has maximum likelihood.

Methods

  1. .getRNGsignature(object = "ANY"): Default method that tries to extract RNG information from object, by looking sequentially to a slot named 'rng', a slot named 'rng.seed' or an attribute names 'rng'.

    It returns NULL if no RNG data was found.

  2. .getRNGsignature(object = "missing"): Returns the current RNG settings.

  3. .getRNGsignature(object = "list"): Method for S3 objects, that aims at reproducing the behaviour of the function getRNG of the package getRNG.

    It sequentially looks for RNG data in elements 'rng', noise$rng if element 'noise' exists and is a list, or in attribute 'rng'.

  4. .getRNGsignature(object = "numeric"): Method for numeric vectors, which returns the object itself, if it has more than one element, coerced into an integer vector if necessary, as it is assumed to already represent a value for .Random.seed.

    Or if object has a single element, the value of .Random.seed as it would be after calling set.seed(object, ...) In this case, all arguments in ... are passed to set.seed. Note that this does not change the current RNG.

  5. getRNG1signature(object = "ANY"): Default method that is identical to getRNG(object, ...).

  6. .setRNGsignature(object = "character"): Sets the RNG to kind object, assuming is a valid RNG kind: it is equivalent to RNGkind(object, .... All arguments in ... are passed to RNGkind.

  7. .setRNGsignature(object = "numeric"): Sets the RNG settings using object directly the new value for .Random.seed or to initialise it with set.seed.

Examples

# get current RNG settings
s <- getRNG()

head(s)



[1]        403          1   23081109 -438644945 1816876598 1704940128

showRNG(s)



# RNG kind:  Mersenne-Twister / Inversion 
# RNG state: 403L, 1L, ..., 629228039L [71bb91a50169a0c4d2ea6d90193d7997] 

# get RNG from a given single numeric seed
s1234 <- getRNG(1234)

head(s1234)



[1]         403         624 -1394370482 -1723143049  2071488076  1659356893

showRNG(s1234)



# RNG kind:  Mersenne-Twister / Inversion 
# RNG state: 403L, 624L, ..., -1896522223L [eacb7c1288e03421d428feb736099548] 

# this is identical to the RNG seed as after set.seed()
set.seed(1234)

identical(s1234, .Random.seed)



[1] TRUE

# but if num.ok=TRUE the object is returned unchanged
getRNG(1234, num.ok=TRUE)



[1] 1234

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



[1] 1

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

identical(s, s1234)



[1] FALSE

# test for embedded RNG data
hasRNG(1)



[1] FALSE

hasRNG( structure(1, rng=1:3) )



[1] TRUE

hasRNG( list(1, 2, 3) )



[1] FALSE

hasRNG( list(1, 2, 3, rng=1:3) )



[1] TRUE

hasRNG( list(1, 2, 3, noise=list(1:3, rng=1)) )



[1] TRUE

head(nextRNG())



[1]        403          1 1407173775  141192598  911446336 1689480195

head(nextRNG(1234))



[1]         403         624 -1394370482 -1723143049  2071488076  1659356893

head(nextRNG(1234, ndraw=10))



[1]        403         10 1407173775  141192598  911446336 1689480195

obj <- list(x=1000, rng=123)

setRNG(obj)

rng <- getRNG()

runif(10)



 [1] 0.2875775 0.7883051 0.4089769 0.8830174 0.9404673 0.0455565 0.5281055 0.8924190 0.5514350 0.4566147

set.seed(123)

rng.equal(rng)



[1] TRUE

# set RNG kind
old <- setRNG('Marsaglia')

# restore
setRNG(old)

# directly set .Random.seed
rng <- getRNG()

r <- runif(10)

setRNG(rng)

rng.equal(rng)



[1] TRUE

# initialise from a single number (<=> set.seed)
setRNG(123)

rng <- getRNG()

runif(10)



 [1] 0.2875775 0.7883051 0.4089769 0.8830174 0.9404673 0.0455565 0.5281055 0.8924190 0.5514350 0.4566147

set.seed(123)

rng.equal(rng)



[1] TRUE

See also

.Random.seed, showRNG