[Distr-commits] r632 - in pkg: . setRNG setRNG/R setRNG/S setRNG/inst setRNG/inst/doc setRNG/man setRNG/tests
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Thu Nov 19 23:19:05 CET 2009
Author: pgilbert
Date: 2009-11-19 23:19:04 +0100 (Thu, 19 Nov 2009)
New Revision: 632
Added:
pkg/setRNG/
pkg/setRNG/DESCRIPTION
pkg/setRNG/LICENSE
pkg/setRNG/Makefile
pkg/setRNG/NAMESPACE
pkg/setRNG/NEWS
pkg/setRNG/R/
pkg/setRNG/R/setRNG.R
pkg/setRNG/S/
pkg/setRNG/S/setRNG.S
pkg/setRNG/inst/
pkg/setRNG/inst/doc/
pkg/setRNG/inst/doc/setRNG.Stex
pkg/setRNG/man/
pkg/setRNG/man/00.setRNG.Intro.Rd
pkg/setRNG/man/getRNG.Rd
pkg/setRNG/man/random.number.test.Rd
pkg/setRNG/man/setRNG-package.Rd
pkg/setRNG/man/setRNG.Rd
pkg/setRNG/tests/
pkg/setRNG/tests/RNGtest.R
Log:
adding setRNG package.
Added: pkg/setRNG/DESCRIPTION
===================================================================
--- pkg/setRNG/DESCRIPTION (rev 0)
+++ pkg/setRNG/DESCRIPTION 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,16 @@
+Package: setRNG
+Title: Set (Normal) Random Number Generator and Seed
+Description: SetRNG provides utilities to help set and record the setting of
+ the seed and the uniform and normal generators used when a random
+ experiment is run. The utilities can be used in other functions
+ that do random experiments to simplify recording and/or setting all the
+ necessary information for reproducibility.
+ See the vignette and reference manual for examples.
+Depends: R (>= 2.5.0)
+Version: 2009.11-1
+Date: 2009-11-1
+LazyLoad: yes
+License: GPL-2 | file LICENSE
+Author: Paul Gilbert <pgilbert at bank-banque-canada.ca>
+Maintainer: Paul Gilbert <pgilbert at bank-banque-canada.ca>
+URL: http://www.bank-banque-canada.ca/pgilbert
Added: pkg/setRNG/LICENSE
===================================================================
--- pkg/setRNG/LICENSE (rev 0)
+++ pkg/setRNG/LICENSE 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,12 @@
+ Copyright 1993, 1994, 1995, 1996 Bank of Canada.
+ Copyright 1997 (June), Paul Gilbert.
+ Copyright 1997 (Aug.), Bank of Canada.
+ Copyright 1998-2007 Bank of Canada.
+
+ The user of this software has the right to use, reproduce and distribute it.
+ Bank of Canada and Paul Gilbert make no warranties with respect to the
+ software or its fitness for any particular purpose.
+ The software is distributed by the Bank of Canada and by Paul Gilbert
+ solely on an "as is" basis. By using the software, user agrees to accept
+ the entire risk of using this software.
+
Added: pkg/setRNG/Makefile
===================================================================
--- pkg/setRNG/Makefile (rev 0)
+++ pkg/setRNG/Makefile 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,7 @@
+PREREQ_PACS=
+
+include ../Makevars
+
+default: $(DEFAULT)
+
+include ../Makerules
Added: pkg/setRNG/NAMESPACE
===================================================================
--- pkg/setRNG/NAMESPACE (rev 0)
+++ pkg/setRNG/NAMESPACE 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,4 @@
+export("setRNG")
+export("random.number.test")
+export("getRNG")
+S3method("getRNG","default")
Added: pkg/setRNG/NEWS
===================================================================
--- pkg/setRNG/NEWS (rev 0)
+++ pkg/setRNG/NEWS 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,24 @@
+Changes in setRNG version 2009.11-1
+
+ o Standardized NEWS format for new function news().
+
+ o The result of setRNG is now returned with invisible() except in the case
+ it is called with no arguments. This avoids printout of large seeds.
+
+Changes in setRNG version 2008.3-1
+
+ o as.integer(seed) used explicitely to avoid warning caused when an
+ integer stored as a double was used to set the seed. This should
+ cause no changes other than eliminating the warning message.
+
+Changes in setRNG version 2006.4-1
+
+ o added setRNG-package.Rd overview.
+
+ o added namespaces
+
+Changes in setRNG version 2004.4-1
+
+ o setRNG is now maintained as a separate package
+
+ o Older NEWS is in the dse NEWS file.
Added: pkg/setRNG/R/setRNG.R
===================================================================
--- pkg/setRNG/R/setRNG.R (rev 0)
+++ pkg/setRNG/R/setRNG.R 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,216 @@
+
+###########################################################
+
+# Random number generation.
+
+###########################################################
+
+# Prior to R 0.99 Wichmann-Hill was the default and the DSE version of
+# Box-Muller was used for rnorm.
+
+setRNG <- function(kind=NULL, seed=NULL, normal.kind=NULL)
+ {# with a null argument this also serves as getRNG
+ #The next line means that setRNG with null args does not truly
+ # return the state of the RNG in the case when it has not been
+ # initialize. It first initializes it and then returns the state. The
+ # rational is that querying the state is usually for the purpose of
+ # reproducing it, so it must first be initialized to put it in a
+ # reproducible state.
+ if (!exists(".Random.seed", envir=.GlobalEnv, inherits = FALSE))
+ z <- runif(1)
+ old <- list(kind=RNGkind()[1],normal.kind=RNGkind()[2],
+ seed=get(".Random.seed", envir=.GlobalEnv, inherits = FALSE)[-1])
+
+ if (is.null(kind) & is.null(seed) & is.null(normal.kind)) return (old)
+ if (is.list(kind))
+ {seed <- kind$seed
+ normal.kind <- kind$normal.kind
+ kind <- kind$kind
+ }
+ #Something like this might be nice, but there does not seem to be a way
+ # to associate rng versions other than using R versions, and
+ # that is too strict. Perhaps RNGversion() could return something.
+ #v <- some number associated with kind and normal.kind
+ #if (is.null(v)) warning("version cannot be verified.")
+ #if (!all(unlist(RNGversion()) == unlist(v)))
+ # warning("rng used but version does not correspond to original. Differences may occur.")
+ k <- get(".Random.seed", envir=.GlobalEnv, inherits = FALSE)[1]
+ remove(".Random.seed", envir=.GlobalEnv) # otherwise RNGkind complains
+ RNGkind(kind=kind, normal.kind=normal.kind) # this sets .Random.seed
+ seed <- as.integer(seed) #fix case where an integer is stored as double
+ if ( 1==length(seed)) set.seed(seed)
+ else assign(".Random.seed",
+ c(get(".Random.seed", envir=.GlobalEnv, inherits = FALSE)[1], seed),
+ envir=.GlobalEnv)
+ invisible(old)
+ }
+
+
+getRNG <- function(e=NULL)UseMethod("getRNG")
+getRNG.default <- function(e=NULL)
+ {if (is.null(e)) k <- setRNG()
+ else if (!is.null(e$rng)) k <- e$rng
+ else if (!is.null(e$noise)) k <- e$noise$rng
+ else stop("RNG information not found.")
+ k
+ }
+
+
+#########################################################
+
+# test function (This test is run by other tests so it should
+# be defined here and not moved to tests directory.
+
+#########################################################
+
+
+random.number.test <- function()
+ {cat("Random number generator tests ...")
+ if (is.R())
+ {test.seed<- 979 #previous to R 1.0.0: c( 979, 1479, 1542)
+ # values from 0.49 beta
+ #test.valueU <-c(5.693354055333957e-01,1.051357751852140e-01,
+ # 5.846933178718317e-02, 7.537960906527452e-02, 7.043734921992200e-01)
+ #test.valueN <-c(-5.559389931781886e-01,
+ # -1.902431069568611e+00, 1.524595894866778e+00,
+ # -7.863494805034426e-01, 1.328128164898773e-01)
+ # values from 0.99.0a
+ # test.valueU <-c(0.25603057077527752, 0.07879165329010961,
+ # 0.60394682330171257, 0.20843868707503158, 0.97636939375111098)
+ # test.valueN <-c( -1.39965726956837644, -0.24025807684466990,
+ # 2.34362137305187446, -0.66321208109989371, -0.71183559894654214)
+ # values from 1.1.0 (devel) should also work in 1.0.1
+ test.valueU.R1.6.2 <-c(0.59132864479704950, 0.76406894316060192,
+ 0.18576870606880833, 0.81087542344137897, 0.05835627439859235)
+ test.valueN.R1.7.1 <-c( 0.959409416512901569, 0.046546246157109825,
+ -0.775306427558083988, -0.777761120323404387, -1.363043207314097227)
+ test.valueN.R1.6.2 <-c( 0.959409416509782953, 0.046546246156130192,
+ -0.775306427558391964, -0.777761120325662803, -1.363043207314267313)
+ test.valueU <-c(0.6159259434789419, 0.2200001638848335,
+ 0.7024894717615098, 0.4869760072324425, 0.2284618646372110)
+ test.valueN <- c(0.2947980960879867, 0.5315740209738240,
+ -0.7439218830522146, -0.9861002105572579, -0.3542773118879623)
+ }
+ if (!is.R())
+ {# above should really be if (is.Splus())
+ test.seed<- c(37, 39, 39, 4, 7, 2, 27, 58, 38, 15, 32, 2)
+ test.valueU.S <- c(0.4299328043125570, 0.3092006836086512,
+ 0.5808096211403608, 0.3061958812177181, 0.8137333435006440)
+ test.valueN.S <- c( -0.7613318231781665, -0.5724360196433543,
+ 0.8536399448225964, -0.2269096022522968, -0.8126790170570223)
+ }
+
+ old.seed <- setRNG(kind="default", seed=test.seed, normal.kind="default")
+ on.exit(setRNG(old.seed))
+
+ ok <- TRUE
+if ( !is.R())
+ {if (1e-14 < max(abs(runif(5)-test.valueU.S)))
+ {warning("The default runif number generator has been changed.")
+ ok <- FALSE
+ }
+
+ setRNG(kind="default", seed=test.seed, normal.kind="default")
+
+ if (1e-14 < max(abs(rnorm(5)-test.valueN.S)))
+ {warning("The default rnorm number generator has been changed.")
+ ok <- FALSE
+ }
+ }
+if ( is.R())
+ {if (as.numeric(version$major)+0.1*as.numeric(version$minor) > 1.62 )
+ {if (1e-14 < max(abs(runif(5)-test.valueU)))
+ {warning("The default runif number generator has been changed.")
+ ok <- FALSE
+ }
+
+ setRNG(kind="default", seed=test.seed, normal.kind="default")
+
+ if (1e-14 < max(abs(rnorm(5)-test.valueN)))
+ {warning("The default rnorm number generator has been changed.")
+ ok <- FALSE
+ }
+ }
+# As of R 1.7.0 the default generator changed. For R 0.99 to 1.6.2 the
+# following corresponded to kind="default",normal.kind="default"
+ setRNG(kind="Marsaglia-Multicarry", seed=test.seed, normal.kind="Kinderman-Ramage")
+
+ if (1e-14 < max(abs(runif(5)-test.valueU.R1.6.2)))
+ {warning("The Marsaglia-Multicarry runif number generator has been changed.")
+ ok <- FALSE
+ }
+
+# As of R 1.7.1 a bug was recognized in Kinderman-Ramage and it was changed. The
+# old version was named "Buggy Kinderman-Ramage"
+ setRNG(kind="Marsaglia-Multicarr", seed=test.seed, normal.kind="Kinderman-Ramage")
+
+if (as.numeric(version$major)+0.1*as.numeric(version$minor) >= 1.71 )
+ {if (1e-14 < max(abs(rnorm(5) - test.valueN.R1.7.1 )))
+ {warning("The Kinderman-Ramage rnorm number generator has been changed.")
+ ok <- FALSE}
+ setRNG(kind="Marsaglia-Multicarr", seed=test.seed, normal.kind="Buggy Kinderman-Ramage")
+ if (1e-14 < max(abs(rnorm(5) - test.valueN.R1.6.2 )))
+ {warning("The Buggy Kinderman-Ramage rnorm number generator has been changed.")
+ ok <- FALSE
+ }
+ }
+ else if (1e-14 < max(abs(rnorm(5) - test.valueN.R1.6.2 )))
+ {warning("The Kinderman-Ramage rnorm number generator (pre R 1.7.1)has been changed.")
+ ok <- FALSE
+ }
+ }
+
+ setRNG(kind="Wichmann-Hill", seed=c(979,1479,1542), normal.kind="Box-Muller")
+ if (setRNG()$kind != "Wichmann-Hill" ||
+ setRNG()$normal.kind != "Box-Muller" ||
+ all(setRNG()$seed != c(979,1479,1542) ))
+ {warning("RNG is not being set properly")
+ ok <- FALSE
+ }
+ if (1e-14 < max(abs(runif(5) -
+ c(0.56933540553339546, 0.10513577518521355, 0.05846933178718317,
+ 0.07537960906527452, 0.70437349219921996))))
+ {warning("The Wichmann-Hill runif number generator has been changed.")
+ ok <- FALSE
+ }
+
+# for the next R 1.0.0
+# setRNG(kind="Wichmann-Hill", seed=c(979,1479,1542), normal.kind="Box-Muller")
+# rnorm gives
+#[1] -1.92425218107175877 -0.89568905204068128 2.12213361588187510
+#[4] 0.81669202948845299 -0.13569189805256629
+# as does
+ setRNG(kind="Wichmann-Hill", seed=c(979,1479,1542), normal.kind="Box-Muller")
+ if (1e-14 < max(abs(rnorm(5) -
+ c(-1.92425218107175877, -0.89568905204068128, 2.12213361588187510,
+ 0.81669202948845299, -0.13569189805256629)
+ # pre R 1,0,0 c(0.4605069059114530, 0.7685565310963474, -0.3737680932387061,
+ # 0.5926372779538560, 1.4995245125275518)
+ )))
+ {warning("The Box-Muller rnorm number generator has been changed.")
+ ok <- FALSE
+ }
+ # this needs to be done twice with odd and even n to chech completely
+ if (1e-14 < max(abs(rnorm(5) -
+ c(-0.4602838255495997, 0.2761541652763959, 1.3265434523731297,
+ 0.6856247181400722, -1.8336523890846541) )))
+ {warning("The Box-Muller rnorm state is not properly preserved.")
+ ok <- FALSE
+ }
+ if (1e-14 < max(abs(rnorm(6) -
+ c(1.9850437759531543, 0.6107700961454843, -0.9419893721776470,
+ 1.1031328847642050, 0.4184702210057414, 0.9167797157851526) )))
+ {warning("The Box-Muller rnorm state is not properly preserved.")
+ ok <- FALSE
+ }
+
+ if (1e-14 < max(abs(rnorm(6) -
+ c(-0.724539745179790251, -0.439138566092752758, 1.466237618877826110,
+ 0.289289597398559639, 0.003007778996985022, 1.008712871048744297) )))
+ {warning("The Box-Muller rnorm state is not properly preserved.")
+ ok <- FALSE
+ }
+
+ if (ok) {cat("ok\n"); invisible(TRUE) } else { cat("failed!\n"); stop("failed")}
+ }
+
Added: pkg/setRNG/S/setRNG.S
===================================================================
--- pkg/setRNG/S/setRNG.S (rev 0)
+++ pkg/setRNG/S/setRNG.S 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,145 @@
+
+ RNGkind <- function(kind=NULL, normal.kind=NULL)
+ {# With a null argument this returns the current kind and normal.kind.
+ # kind = "default" resets the RNG to the Splus default.
+ # Splus does not allow arbitrary setting of .Random.seed so
+ # .RandomSeed is used. The existence of .RandomSeed is
+ # used to indicate whether an alternate RNG is used and the
+ # first element of .RandomSeed indicates the generator.
+ # Note this does not always work with For loops if where=0 is used.
+ old <- if(exists(".RandomSeed"))
+ c("Wichmann-Hill")[1+.RandomSeed[1]] else "default"
+ if ( !is.null(kind))
+ {# set the RNG kind
+ if (kind[[1]] == "default")
+ {if(exists(".RandomSeed", where=1)) remove(".RandomSeed", where=1)}
+ else if (kind[[1]] == "Wichmann-Hill")
+ assign(".RandomSeed", c(0, as.integer(100000*runif(3))), where=1)
+ else stop("Only Wichmann-Hill, default or NULL supported for kind.")}
+ old.normal <- if(exists(".RNORMtransform", where=1))
+ .RNORMtransform else "default"
+ if ( !is.null(normal.kind))
+ {if(exists(".BM.seed", where=1)) remove(".BM.seed", where=1)
+ if (normal.kind == "Box-Muller")
+ assign(".RNORMtransform", normal.kind, where=1)
+ else if (normal.kind == "default")
+ {if(exists(".RNORMtransform", where=1))
+ remove(".RNORMtransform", where=1)
+ if(exists(".RandomSeed", where=1))
+ {warning("kind also set to default as required by default normal.kind")
+ remove(".RandomSeed", where=1)
+ }
+ }
+ else stop("Only Box-Muller, default or NULL supported for normal.kind.")
+ }
+ c(old, old.normal)
+ }
+
+ if (!exists("set.seed.Splus")) set.seed.Splus <- set.seed
+
+ set.seed <- function(seed=NULL)
+ {# with a null argument this also serves as get.seed.
+ kind <- RNGkind()
+ if ( is.null(seed))
+ {if (kind[1] == "default") seed <-.Random.seed
+ else seed <-.RandomSeed[-1]
+ }
+ else
+ {# set seed
+ if (kind[1] == "default")
+ {if (1==length(seed)) set.seed.Splus(seed)
+ else assign(".Random.seed", seed, where=1)#default
+ }
+ else if (kind[1] == "Wichmann-Hill")
+ {if (3 != length(seed))
+ stop("seed length is not consistent with kind Wichmann-Hill.")
+ #Note this does not always work with For loops if where=0 is used.
+ assign(".RandomSeed", c(0,seed), where=1)
+ }
+ else stop("seed does not match RNG kind.")
+ }
+ seed
+ }
+
+
+ setRNG <- function(kind=NULL, seed=NULL, normal.kind=NULL)
+ {# with a null argument this also serves as getRNG
+ old <- list(kind=RNGkind()[1], normal.kind=RNGkind()[2],
+ seed=set.seed())
+ if (is.null(kind) & is.null(seed) & is.null(normal.kind)) return (old)
+ if (is.list(kind))
+ {seed <- kind$seed
+ normal.kind <- kind$normal.kind
+ kind <- kind$kind
+ }
+ RNGkind(kind=kind, normal.kind=normal.kind)
+ set.seed(seed)
+ old
+ }
+
+
+ if (!exists("runif.default")) runif.default <- runif
+ runif <- function(n, min=0, max=1)
+ {# This typically just calls runif.default, but allows using other
+ # RNGs to generate the same sequence in R and S.
+ # eg: setRNG(seed=c(1:3), kind="Wichmann-Hill")
+ # runif(10)
+
+ if(RNGkind()[1] == "default") return(runif.default(n, min=min, max=max))
+ else seed <- set.seed() # returns the setting
+ kind <- RNGkind()[1]
+ if(kind == "Wichmann-Hill")
+ {out <- numeric(n)
+ if (3 != length(seed)) stop("seed setting is not consistent with RNG.")
+ x <- seed[1]; y <- seed[2]; z <- seed[3]
+ for(i in 1:length(out))
+ {x <- (171*x) %% 30269
+ y <- (172*y) %% 30307
+ z <- (170*z) %% 30323
+ out[i] <- (x/30269 + y/30307 + z/30323) %% 1.0
+ }
+ set.seed( c(x,y,z))
+ }
+ else stop("runif RNG kind not supported.")
+ out
+ }
+
+
+ if (!exists("rnorm.default")) rnorm.default <- rnorm
+
+ rnorm <- function(n, mean=0, sd=1, compiled=F)
+ {# This typically just calls rnorm.default, but provides the possibility of
+ # using Wichmann-Hill to generate the same runif sequence in R and S and
+ # then generate the same normally distributed numbers with Box-Muller.
+ # eg: setRNG(seed=1:3, kind="Wichmann-Hill", normal.kind="Box-Muller")
+ # where 1:3 should be a valid seed.
+ # This replicates R values, given by
+ # setRNG(seed=1:3, kind="Wichmann-Hill", normal.kind="Box-Muller"),
+
+
+ if(RNGkind()[2] != "Box-Muller") return(rnorm.default(n, mean=mean, sd=sd))
+ else
+ {if(n==0) return(numeric(0))
+ # if(exists(".BM.seed", envir=.GlobalEnv))
+ if(exists(".BM.seed", where=0))
+ {out <- get(".BM.seed", where=0)
+ remove(".BM.seed", where=0)
+ }
+ else out <- NULL
+ # next should be true except when n==1 and an odd value has been saved
+ if (length(out) < n)
+ {rv <- runif(n-length(out) + (n-length(out))%%2)
+ rv <- matrix(rv, 2, length(rv)/2)
+ rv <- c( rbind(sqrt(-2*log(rv[2,])) * cos(2*pi*rv[1,]),
+ sqrt(-2*log(rv[2,])) * sin(2*pi*rv[1,])))
+ out <- c(out, rv)
+ }
+ if (1 == (length(out) - n))
+ {#drop last point and keep for next call
+ assign(".BM.seed", out[length(out)], where=0)
+ out <- out[-length(out)]
+ }
+ if(n !=length(out)) stop("something is rotten in the state of rnorm.")
+ }
+ mean + out*sd
+}
Added: pkg/setRNG/inst/doc/setRNG.Stex
===================================================================
--- pkg/setRNG/inst/doc/setRNG.Stex (rev 0)
+++ pkg/setRNG/inst/doc/setRNG.Stex 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,68 @@
+\documentclass[english]{article}
+\begin{document}
+
+%\VignetteIndexEntry{setRNG Guide}
+\SweaveOpts{eval=TRUE,echo=TRUE,results=hide,fig=FALSE}
+\begin{Scode}{echo=FALSE,results=hide}
+ options(continue=" ")
+\end{Scode}
+
+\section{setRNG Functions}
+
+In R, the functions in this package are made available with
+
+\begin{Scode}
+library("setRNG")
+\end{Scode}
+
+As of R-2.1.0 the code from the vignette that generates this guide can
+be loaded into an editor with \emph{edit(vignette("setRNG"))}.
+This uses the default editor, which can be changed using \emph{options()}.
+Also, it should be possible to view the pdf version of the guide for this
+package with \emph{print(vignette("setRNG"))}.
+
+
+This library provides tools to simplify recording and resetting the random
+number generator, to help make monte carlo experiments easily reproducible.
+It uses the R/S tools for setting the seed, but also records and sets
+the mechanism for converting uniform numbers to normally distributed numbers.
+(It could be extended to other transformations, but I have not done that.)
+
+The setRNG function would typically be called by simulation programs. For
+example, if \emph{rng=NULL} is an argument to the function then the code
+
+\begin{Scode}{eval=FALSE,echo=FALSE,results=hide}
+ rng <- NULL
+\end{Scode}
+
+\begin{Scode}{eval=FALSE,echo=TRUE,results=hide}
+if(!require("setRNG")) {
+ stop("This function requires the setRNG package.") }
+if(is.null(rng)) rng <- setRNG() else
+ {old.rng <- setRNG(rng); on.exit(setRNG(old.rng)) }
+\end{Scode}
+
+should be used before the random number generator is used. This will set the
+RNG information if given, and in all cases record the RNG information which
+can then be returned with the result
+of the simulation. (\emph{setRNG()} returns the setting so do not skip this if
+\emph{rng=NULL}.) With the information recorded the simulation can always be
+reproduced if
+necessary. In the case where the rng is set to a specified value it is
+good practice to set it back to the original value on exit. This prevents other
+random experiments from accidentally being affected by the rng setting.
+
+The library also implements an approach to random number generation
+which allows the same random experiments to be replicated in S and R.
+The functions in the S directory allow the R results using
+Wichmann-Hill and Box-Muller to be replicated in S. These were done with
+the aid of an example from B. D. Ripley. (The files in the S
+directory of the package are for use with S not R.)
+These functions are intended primarily as a way to confirm that simulations and
+estimations with simulated data work in
+the same way in both S and R, not as an improved RNG. (It has only been tested
+in Splus 3.3) Default and other
+RNGs can still be used and are preferred for both speed and
+theoretical reasons.
+
+\end{document}
Added: pkg/setRNG/man/00.setRNG.Intro.Rd
===================================================================
--- pkg/setRNG/man/00.setRNG.Intro.Rd (rev 0)
+++ pkg/setRNG/man/00.setRNG.Intro.Rd 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,14 @@
+\name{00.setRNG.Intro}
+\alias{00.setRNG.Intro}
+\docType{package}
+
+\title{setRNG}
+
+\description{Programs to set random number generator (and seed) in R and S.}
+
+\details{ See \code{\link{setRNG-package}} ( in the help system use
+ package?setRNG or ?"setRNG-package") for an overview.
+}
+\keyword{package}
+
+
Added: pkg/setRNG/man/getRNG.Rd
===================================================================
--- pkg/setRNG/man/getRNG.Rd (rev 0)
+++ pkg/setRNG/man/getRNG.Rd 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,41 @@
+\name{getRNG}
+\alias{getRNG}
+\alias{getRNG.default}
+
+\title{get the RND and seed from an object}
+\description{
+Get the random number generator and seed used to generate an object.
+}
+\usage{
+ getRNG(e=NULL)
+ \method{getRNG}{default}(e=NULL)
+}
+\arguments{
+ \item{e}{an object generated by simulation (which stored the RNG
+ information).}
+}
+\value{The random seed and other random number generation information
+ used to generate the object. }
+\details{Extract the RNG information used to generate the object. If \code{e}
+ is \code{NULL} then \code{getRNG} returns the RNG setting, as
+ returned by \code{setRNG()}. Otherwise,
+ the default method assumes the object is a list and the RNG information
+ is in the element \code{rng} or \code{noise\$rng}.
+ }
+\seealso{
+\code{\link{setRNG}},
+\code{\link{.Random.seed}}
+}
+\examples{
+\dontrun{
+if (require("dse")) {
+ data("eg1.DSE.data.diff", package="dse")
+ model <- estVARXls(eg1.DSE.data.diff)
+ sim <- simulate(model)
+ getRNG(sim)
+ }
+}
+}
+\keyword{ts}
+\keyword{programming}
+\keyword{utilities}
Added: pkg/setRNG/man/random.number.test.Rd
===================================================================
--- pkg/setRNG/man/random.number.test.Rd (rev 0)
+++ pkg/setRNG/man/random.number.test.Rd 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,32 @@
+\name{random.number.test}
+\alias{random.number.test}
+\title{Test the random number generator}
+\description{Test the random number generator.}
+\usage{
+ random.number.test()
+ }
+\arguments{None}
+\value{logical}
+\details{
+ This function checks that the
+ RNG is working properly and has not been changed. If the RNG does not return
+ values as in previous versions of R then the function executes
+ \code{stop()}. Since changes to the RNG will cause comparisons of
+ simulation results to fail, this is a useful check before investigating more
+ complicated problems that may be a result of other "improvements" in your
+ simulation or estimation programs.
+}
+\section{Side Effects}{Executes \code{stop()} if the tests fail.}
+\seealso{
+ \code{\link{set.seed}}
+ \code{\link{RNGkind}}
+ \code{\link{runif}}
+ \code{\link{rnorm}}
+ \code{\link{setRNG}}
+}
+\examples{
+ random.number.test()
+}
+\keyword{programming}
+\keyword{utilities}
+
Added: pkg/setRNG/man/setRNG-package.Rd
===================================================================
--- pkg/setRNG/man/setRNG-package.Rd (rev 0)
+++ pkg/setRNG/man/setRNG-package.Rd 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,67 @@
+\name{setRNG-package}
+\alias{setRNG-package}
+\alias{setRNG.Intro}
+
+\docType{package}
+
+\title{setRNG}
+
+\section{Usage}{
+ library("setRNG")
+}
+
+\description{
+ Programs to set random number generator (and seed) in R and S.}
+\section{Introduction}{
+This library provides tools to simplify recording and resetting the random
+number generator, to help make monte carlo experiments easily reproducible.
+It uses the R/S tools for setting the seed, but also records and sets
+the mechanism for converting uniform numbers to normally distributed numbers.
+(It could be extended to other transformations, but I have not done that.)
+
+The setRNG function would typically be called by simulation programs (see
+example) to set the
+RNG information if given, and record the RNG information
+in all cases. This information can be returned with the result
+of the simulation. That way the simulation can always be reproduced if
+necessary.
+
+The library also implements an approach to random number generation
+which allows the same random experiments to be replicated in S and R.
+The functions in the S/ directory allow the R results using
+Wichmann-Hill and Box-Muller to be replicated in S. These were done with
+the aid of an example from B. D. Ripley. (The files in the S/
+directory of the package are for use with S not R.)
+These functions are intended primarily as a way to confirm that simulations and
+estimations with simulated data work in
+the same way in both S and R, not as an improved RNG. (It has only been tested
+in Splus 3.3) Default and other
+RNGs can still be used and are preferred for both speed and
+theoretical reasons.
+}
+
+
+\examples{
+setRNG(kind="Wichmann-Hill", seed=c(979,1479,1542), normal.kind="Box-Muller")
+rnorm(10)
+
+sim <-function(rng=NULL)
+ {if(!require("setRNG")) stop("This function requires the setRNG package.")
+ if(is.null(rng)) rng <- setRNG() # returns setting so don't skip if NULL
+ else {old.rng <- setRNG(rng); on.exit(setRNG(old.rng)) }
+ x <- list(numbers=rnorm(10))
+ x$rng <- rng
+ x
+ }
+
+z <- sim()
+sim()$numbers
+sim(rng=getRNG(z))$numbers
+z$numbers
+
+}
+\keyword{programming}
+\keyword{interface}
+\keyword{utilities}
+\keyword{distribution}
+
Added: pkg/setRNG/man/setRNG.Rd
===================================================================
--- pkg/setRNG/man/setRNG.Rd (rev 0)
+++ pkg/setRNG/man/setRNG.Rd 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,42 @@
+\name{setRNG}
+\alias{setRNG}
+\title{Set the Random Number Generator}
+\description{Set the RNG or return information about the setting of the RNG.}
+\usage{
+ setRNG(kind=NULL, seed=NULL, normal.kind=NULL)
+ }
+\arguments{None required
+ \item{kind}{a character string.}
+ \item{seed}{a vector of numbers (depending on kind).}
+ \item{normal.kind}{a character string.}
+}
+\value{The old setting.}
+\details{
+ Sets the uniform and normal random number generators and the seed.
+ The old setting is returned using \code{invisible()} in a format
+ which can be used in another call to \code{setRNG}. (This would reset to the
+ original value.) If no arguments are given the current setting is returned,
+ not using \code{invisible()}. In R see \code{RNGkind} for more details.
+
+ Note that in a function using \code{setRNG} it is good practice to
+ assign the old setting to a variable, then reset to the old value on exiting
+ the function (using \code{on.exit}). This avoids the possibility that
+ overall RNG behaviour in a session, other than within your function, may be
+ disrupted by your function.
+}
+\section{Side Effects}{Sets global variables controlling the uniform and normal random
+ number generators and the global seed.}
+\seealso{
+ \code{\link{RNGkind}},
+ \code{\link{set.seed}},
+ \code{\link{runif}},
+ \code{\link{rnorm}},
+ \code{\link{random.number.test}}
+}
+\examples{
+setRNG(kind="Wichmann-Hill", seed=c(979,1479,1542), normal.kind="Box-Muller")
+rnorm(10)
+}
+\keyword{programming}
+\keyword{utilities}
+
Added: pkg/setRNG/tests/RNGtest.R
===================================================================
--- pkg/setRNG/tests/RNGtest.R (rev 0)
+++ pkg/setRNG/tests/RNGtest.R 2009-11-19 22:19:04 UTC (rev 632)
@@ -0,0 +1,4 @@
+ require("setRNG")
+ Sys.info()
+
+ random.number.test()
More information about the Distr-commits
mailing list