R: Getting/Setting RNGs

getRNG {rngtools} | R Documentation

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

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

### Usage

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

      hasRNG(object)

      .getRNG(object, ...)

      getRNG1(object, ...)

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

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

      .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.
`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.
`verbose` | a logical that indicates if the new RNG settings should be displayed.

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

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.

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

### Methods

.getRNG

  `signature(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.

.getRNG

  `signature(object = "missing")`: Returns the current RNG settings.

.getRNG

  `signature(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'`.

.getRNG

  `signature(object = "numeric")`: Method for numeric vectors, which returns the object itself, coerced into an integer vector if necessary, as it is assumed to already represent a value for `.Random.seed`.

getRNG1

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

.setRNG

  `signature(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`.

.setRNG

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

### See Also

`.Random.seed`, `showRNG`

### Examples

    # 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)
    # 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)) )
    head(nextRNG())
    head(nextRNG(1234))
    head(nextRNG(1234, ndraw=10))
    obj <- list(x=1000, rng=123)
    setRNG(obj)
    rng <- getRNG()
    runif(10)
    set.seed(123)
    rng.equal(rng)
    # set RNG kind
    old <- setRNG('Marsaglia')
    # restore
    setRNG(old)
    # directly set .Random.seed
    rng <- getRNG()
    r <- runif(10)
    setRNG(rng)
    rng.equal(rng)

    # initialise from a single number (<=> set.seed)
    setRNG(123)
    rng <- getRNG()
    runif(10)
    set.seed(123)
    rng.equal(rng)

[Package rngtools version 1.2.4 Index]