Random                 package:base                 R Documentation

_R_a_n_d_o_m _N_u_m_b_e_r _G_e_n_e_r_a_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     '.Random.seed' is an integer vector, containing the random number
     generator (RNG) *state* for random number generation in R.  It can
     be saved and restored, but should not be altered by the user.

     'RNGkind' is a more friendly interface to query or set the kind of
     RNG in use.

     'RNGversion' can be used to set the random generators as they were
     in an earlier R version (for reproducibility).

     'set.seed' is the recommended way to specify seeds.

_U_s_a_g_e:

     .Random.seed <- c(rng.kind, n1, n2, ...)
     save.seed <- .Random.seed

     RNGkind(kind = NULL, normal.kind = NULL)
     RNGversion(vstr)
     set.seed(seed, kind = NULL)

_A_r_g_u_m_e_n_t_s:

    kind: character or 'NULL'.  If 'kind' is a character string, set
          R's RNG to the kind desired. If it is 'NULL', return the
          currently used RNG. Use '"default"' to return to the R
          default.

normal.kind: character string or 'NULL'.  If it is a character string,
          set the method of Normal generation. Use '"default"' to
          return to the R default.

    seed: a single value, interpreted as an integer.

    vstr: a character string containing a version number, e.g.,
          '"1.6.2"'

rng.kind: integer code in '0:k' for the above 'kind'.

n1, n2, ...: integers. See the details for how many are required (which
          depends on 'rng.kind').

_D_e_t_a_i_l_s:

     The currently available RNG kinds are given below.  'kind' is
     partially matched to this list.  The default is
     '"Mersenne-Twister"'.

     '"_W_i_c_h_m_a_n_n-_H_i_l_l"' The seed, '.Random.seed[-1] == r[1:3]' is an
          integer vector of length 3, where each 'r[i]' is in '1:(p[i]
          - 1)', where 'p' is the length 3 vector of primes, 'p =
          (30269, 30307, 30323)'. The Wichmann-Hill generator has a
          cycle length of 6.9536e12 (= 'prod(p-1)/4', see _Applied
          Statistics_ (1984) *33*, 123 which corrects the original
          article).

     '"_M_a_r_s_a_g_l_i_a-_M_u_l_t_i_c_a_r_r_y"': A _multiply-with-carry_ RNG is used, as
          recommended by George Marsaglia in his post to the mailing
          list 'sci.stat.math'. It has a period of more than 2^60 and
          has passed all tests (according to Marsaglia).  The seed is
          two integers (all values allowed).

     '"_S_u_p_e_r-_D_u_p_e_r"': Marsaglia's famous Super-Duper from the 70's. 
          This is the original version which does _not_ pass the MTUPLE
          test of the Diehard battery.  It has a period of about
          4.6*10^18 for most initial seeds.  The seed is two integers
          (all values allowed for the first seed: the second must be
          odd).

          We use the implementation by Reeds et al. (1982-84).

          The two seeds are the Tausworthe and congruence long
          integers, respectively.  A one-to-one mapping to S's
          '.Random.seed[1:12]' is possible but we will not publish one,
          not least as this generator is *not* exactly the same as that
          in recent versions of S-PLUS.

     '"_M_e_r_s_e_n_n_e-_T_w_i_s_t_e_r":' From Matsumoto and Nishimura (1998). A
          twisted GFSR with period 2^19937 - 1 and equidistribution in
          623 consecutive dimensions (over the whole period).  The
          "seed" is a 624-dimensional set of 32-bit integers plus a
          current position in that set.


     '"_K_n_u_t_h-_T_A_O_C_P":' From Knuth (1997).  A GFSR using lagged Fibonacci
          sequences with subtraction. That is, the recurrence used is

                 X[j] = (X[j-100] - X[j-37]) mod 2^30

          and the "seed" is the set of the 100 last numbers (actually
          recorded as 101 numbers, the last being a cyclic shift of the
          buffer).  The period is around 2^129.


     '"_K_n_u_t_h-_T_A_O_C_P-_2_0_0_2":' The 2002 version which not backwards
          compatible with the earlier version: the initialization of
          the GFSR from the seed was altered. R did not allow you to
          choose consecutive seeds, the reported 'weakness', and
          already scrambled the seeds.


     '"_u_s_e_r-_s_u_p_p_l_i_e_d":' Use a user-supplied generator. See
          'Random.user' for details.

     'normal.kind' can be '"Kinderman-Ramage"',  '"Buggy
     Kinderman-Ramage"', '"Ahrens-Dieter"', '"Box-Muller"',
     '"Inversion"' (the default), or '"user-supplied"'.  (For
     inversion, see the reference in 'qnorm'.) The Kinderman-Ramage
     generator used in versions prior to 1.7.1 had several
     approximation errors and should only be used for reproduction of
     older results.

     'set.seed' uses its single integer argument to set as many seeds
     as are required.  It is intended as a simple way to get quite
     different seeds by specifying small integer arguments, and also as
     a way to get valid seed sets for the more complicated methods
     (especially '"Mersenne-Twister"' and '"Knuth-TAOCP"').

_V_a_l_u_e:

     '.Random.seed' is an 'integer' vector whose first element _codes_
     the kind of RNG and normal generator. The lowest two decimal
     digits are in '0:(k-1)' where 'k' is the number of available RNGs.
     The hundreds represent the type of normal generator (starting at
     '0').

     In the underlying C, '.Random.seed[-1]' is 'unsigned'; therefore
     in R '.Random.seed[-1]' can be negative, due to the representation
     of an unsigned integer by a signed integer.

     'RNGkind' returns a two-element character vector of the RNG and
     normal kinds in use _before_ the call, invisibly if either
     argument is not 'NULL'. 'RNGversion' returns the same information.

     'set.seed' returns 'NULL', invisibly.

_N_o_t_e:

     Initially, there is no seed;  a new one is created from the
     current time when one is required.  Hence, different sessions will
     give different simulation results, by default.

     '.Random.seed' saves the seed set for the uniform random-number
     generator, at least for the system generators.  It does not
     necessarily save the state of other generators, and in particular
     does not save the state of the Box-Muller normal generator.  If
     you want to reproduce work later, call 'set.seed' rather than set
     '.Random.seed'.

     As from R 1.8.0, '.Random.seed' is only looked for in the user's
     workspace.

_A_u_t_h_o_r(_s):

     of RNGkind: Martin Maechler. Current implementation, B. D. Ripley

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole. ('set.seed', storing in
     '.Random.seed'.)

     Wichmann, B. A.  and Hill, I. D. (1982) _Algorithm AS 183: An
     Efficient and Portable Pseudo-random Number Generator_, Applied
     Statistics, *31*, 188-190; Remarks: *34*, 198 and *35*, 89.

     De Matteis, A. and Pagnutti, S. (1993) _Long-range Correlation
     Analysis of the Wichmann-Hill Random Number Generator_, Statist.
     Comput., *3*, 67-70.

     Marsaglia, G. (1997) _A random number generator for C._ Discussion
     paper, posting on Usenet newsgroup 'sci.stat.math' on September
     29, 1997.

     Reeds, J., Hubert, S. and Abrahams, M. (1982-4) C implementation
     of SuperDuper, University of California at Berkeley.  (Personal
     communication from Jim Reeds to Ross Ihaka.)

     Marsaglia, G. and Zaman, A. (1994) Some portable very-long-period
     random number generators. _Computers in Physics_, *8*, 117-121.

     Matsumoto, M. and Nishimura, T. (1998) Mersenne Twister: A
     623-dimensionally equidistributed uniform pseudo-random number
     generator, _ACM Transactions on Modeling and Computer Simulation_,
     *8*, 3-30.
      Source code at <URL:
     http://www.math.keio.ac.jp/~matumoto/emt.html>.

     Knuth, D. E. (1997) _The Art of Computer Programming._ Volume 2,
     third edition.
      Source code at <URL:
     http://www-cs-faculty.stanford.edu/~knuth/taocp.html>.

     Knuth, D. E. (2002) _The Art of Computer Programming._ Volume 2,
     third edition, ninth printing.
      See <URL: http://Sunburn.Stanford.EDU/~knuth/news02.html>.

     Kinderman, A. J. and Ramage, J. G. (1976) Computer generation of
     normal random variables. _Journal of the American Statistical
     Association_ *71*, 893-896.

     Ahrens, J.H. and Dieter, U. (1973) Extensions of Forsythe's method
     for random sampling from the normal distribution. _Mathematics of
     Computation_ *27*, 927-937.

     Box, G.E.P. and Muller, M.E. (1958) A note on the generation of
     normal random deviates. _Annals of Mathmatical Statistics_ *29*,
     610-611.

_S_e_e _A_l_s_o:

     'runif', 'rnorm', ....

_E_x_a_m_p_l_e_s:

     ## the default random seed is 626 integers, so only print a few
     runif(1); .Random.seed[1:6]; runif(1); .Random.seed[1:6]
     ## If there is no seed, a "random" new one is created:
     rm(.Random.seed); runif(1); .Random.seed[1:6]

     RNGkind("Wich")# (partial string matching on 'kind')

     ## This shows how 'runif(.)' works for Wichmann-Hill,
     ## using only R functions:

     p.WH <- c(30269, 30307, 30323)
     a.WH <- c(  171,   172,   170)
     next.WHseed <- function(i.seed = .Random.seed[-1])
       { (a.WH * i.seed) %% p.WH }
     my.runif1 <- function(i.seed = .Random.seed)
       { ns <- next.WHseed(i.seed[-1]); sum(ns / p.WH) %% 1 }
     rs <- .Random.seed
     (WHs <- next.WHseed(rs[-1]))
     u <- runif(1)
     stopifnot(
      next.WHseed(rs[-1]) == .Random.seed[-1],
      all.equal(u, my.runif1(rs))
     )

     ## ----
     .Random.seed
     ok <- RNGkind()
     RNGkind("Super")#matches  "Super-Duper"
     RNGkind()
     .Random.seed # new, corresponding to  Super-Duper

     ## Reset:
     RNGkind(ok[1])

