1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/RNG.R
3\name{getRNG}
4\alias{getRNG}
5\alias{hasRNG}
6\alias{nextRNG}
7\alias{setRNG}
8\title{Getting/Setting RNGs}
9\usage{
10getRNG(object, ..., num.ok = FALSE, extract = TRUE, recursive = TRUE)
11
12hasRNG(object)
13
14nextRNG(object, ..., ndraw = 0L)
15
16setRNG(object, ..., verbose = FALSE, check = TRUE)
17}
18\arguments{
19\item{object}{an R object from which RNG settings can be extracted, e.g. an
20integer vector containing a suitable value for \code{.Random.seed} or embedded
21RNG data, e.g., in S3/S4 slot \code{rng} or \code{rng$noise}.}
22
23\item{...}{extra arguments to allow extension and passed to a suitable S4 method
24\code{.getRNG} or \code{.setRNG}.}
25
26\item{num.ok}{logical that indicates if single numeric (not integer) RNG data should be
27considered as a valid RNG seed (\code{TRUE}) or passed to \code{\link{set.seed}}
28into a proper RNG seed (\code{FALSE}) (See details and examples).}
29
30\item{extract}{logical that indicates if embedded RNG data should be looked for and
31extracted (\code{TRUE}) or if the object itself should be considered as an
32RNG specification.}
33
34\item{recursive}{logical that indicates if embedded RNG data should be extracted
35recursively (\code{TRUE}) or only once (\code{FASE}).}
36
37\item{ndraw}{number of draws to perform before returning the RNG seed.}
38
39\item{verbose}{a logical that indicates if the new RNG settings should
40be displayed.}
41
42\item{check}{logical that indicates if only valid RNG kinds should be
43accepted, or if invalid values should just throw a warning.
44Note that this argument is used only on R >= 3.0.2.}
45}
46\value{
47\code{getRNG}, \code{getRNG1}, \code{nextRNG} and \code{setRNG}
48usually return an integer vector of length > 2L, like \code{\link{.Random.seed}}.
49
50\code{getRNG} and \code{getRNG1} return \code{NULL} if no RNG data was found.
51
52\code{setRNG} invisibly returns the old RNG settings as
53they were before changing them.
54}
55\description{
56\code{getRNG} returns the Random Number Generator (RNG) settings used for
57computing an object, using a suitable \code{.getRNG} S4 method to extract
58these settings.
59For example, in the case of objects that result from multiple model fits,
60it would return the RNG settings used to compute the best fit.
61}
62\details{
63This function handles single number RNG specifications in the following way:
64\describe{
65\item{integers}{Return them unchanged, considering them as encoded RNG kind
66specification (see \code{\link{RNG}}). No validity check is performed.}
67\item{real numbers}{If \code{num.ok=TRUE} return them unchanged.
68Otherwise, consider them as (pre-)seeds and pass them to \code{\link{set.seed}}
69to get a proper RNG seed.
70Hence calling \code{getRNG(1234)} is equivalent to \code{set.seed(1234); getRNG()}
71(See examples).
72}
73}
74}
75\examples{
76#--- getRNG ---
77# get current RNG settings
78s <- getRNG()
79head(s)
80showRNG(s)
81
82# get RNG from a given single numeric seed
83s1234 <- getRNG(1234)
84head(s1234)
85showRNG(s1234)
86# this is identical to the RNG seed as after set.seed()
87set.seed(1234)
88identical(s1234, .Random.seed)
89# but if num.ok=TRUE the object is returned unchanged
90getRNG(1234, num.ok=TRUE)
91
92# single integer RNG data = encoded kind
93head(getRNG(1L))
94
95# embedded RNG data
96s <- getRNG(list(1L, rng=1234))
97identical(s, s1234)
98
99
100#--- hasRNG ---
101# test for embedded RNG data
102hasRNG(1)
103hasRNG( structure(1, rng=1:3) )
104hasRNG( list(1, 2, 3) )
105hasRNG( list(1, 2, 3, rng=1:3) )
106hasRNG( list(1, 2, 3, noise=list(1:3, rng=1)) )
107
108
109#--- nextRNG ---
110head(nextRNG())
111head(nextRNG(1234))
112head(nextRNG(1234, ndraw=10))
113
114
115#--- setRNG ---
116
117obj <- list(x=1000, rng=123)
118setRNG(obj)
119rng <- getRNG()
120runif(10)
121set.seed(123)
122rng.equal(rng)
123
124
125}
126\seealso{
127\code{\link{.Random.seed}}, \code{\link{showRNG}}
128}
129