# 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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 |

### Arguments

`object` |
an R object from which RNG settings can be
extracted, e.g. an integer vector containing a suitable
value for |

`...` |
extra arguments to allow extension and passed
to a suitable S4 method |

`num.ok` |
logical that indicates if single numeric
(not integer) RNG data should be considered as a valid
RNG seed ( |

`extract` |
logical that indicates if embedded RNG
data should be looked for and extracted ( |

`recursive` |
logical that indicates if embedded RNG
data should be extracted recursively ( |

`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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 | ```
# 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)
``` |