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