RNGstr: Formatting RNG Information

In rngtools: Utility functions for working with Random Number Generators

Description

These functions retrieve/prints formated information about RNGs.

RNGtype returns the same type of values as RNGkind() (character strings), except that it can extract the RNG settings from an object. If object is missing it returns the kinds of the current RNG settings, i.e. it is identical to RNGkind().

showRNG displays human readable information about RNG settings. If object is missing it displays information about the current RNG.

RNGinfo is equivalent to RNGtype but returns a named list instead of an unnamed character vector.

RNGdigest computes a hash from the RNG settings associated with an object.

Usage

  RNGstr(object, n = 7L, ...)

  RNGtype(object, ..., provider = FALSE)

  showRNG(object = getRNG(), indent = "#", ...)

  RNGinfo(object = getRNG(), ...)

  RNGdigest(object = getRNG())

Arguments

object	RNG seed (i.e. an integer vector), or an object that contains embedded RNG data. For RNGtype this must be either a valid RNG seed or a single integer that must be a valid encoded RNG kind (see RNGkind).
n	maximum length for a seed to be showed in full. If the seed has length greater than n, then only the first three elements are shown and a digest hash of the complete seed is appended to the string.
provider	logical that indicates if the library that provides the RNG should also be returned as a third element.
indent	character string to use as indentation prefix in the output from showRNG.
...	extra arguments passed to RNGtype.

Details

All functions can retrieve can be called with objects that are – valid – RNG seeds or contain embedded RNG data, but none of them change the current RNG setting. To effectively change the current settings on should use setRNG.

RNGstr returns a description of an RNG seed as a single character string.

RNGstr formats seeds by collapsing them in a comma separated string. By default, seeds that contain more than 7L integers, have their 3 first values collapsed plus a digest hash of the complete seed.

Value

a single character string

RNGtype returns a 2 or 3-long character vector.

Examples

# default is a 626-long integer
RNGstr()
# what would be the seed after seeding with set.seed(1234)
RNGstr(1234)
# another RNG (short seed)
RNGstr(c(401L, 1L, 1L))
# no validity check is performed
RNGstr(2:3)
# get RNG type
RNGtype()
RNGtype(provider=TRUE)
RNGtype(1:3)

# type from encoded RNG kind
RNGtype(107L)
# this is different from the following which treats 107 as a seed for set.seed
RNGtype(107)
showRNG()
# as after set.seed(1234)
showRNG(1234)
showRNG()
set.seed(1234)
showRNG()
# direct seeding
showRNG(1:3)
# this does not change the current RNG
showRNG()
showRNG(provider=TRUE)
# get info as a list
RNGinfo()
RNGinfo(provider=TRUE)
# from encoded RNG kind
RNGinfo(107)
# compute digest hash from RNG settings
RNGdigest()
RNGdigest(1234)
# no validity check is performed
RNGdigest(2:3)

Example output

[1] "10403L, 1L, ..., -62050802L [66ed76ed4dfcda86047f57de900516e2]"
[1] "10403L, 624L, ..., -1896522223L [31e774b05102e6a88705686b036c1ba9]"
[1] "401L, 1L, 1L"
[1] "2L, 3L"
              kind        normal.kind        sample.kind 
"Mersenne-Twister"        "Inversion"        "Rejection" 
              kind        normal.kind        sample.kind           provider 
"Mersenne-Twister"        "Inversion"        "Rejection"             "base" 
                    kind              normal.kind              sample.kind 
  "Marsaglia-Multicarry" "Buggy Kinderman-Ramage"               "Rounding" 
           kind     normal.kind     sample.kind 
"L'Ecuyer-CMRG" "Ahrens-Dieter"      "Rounding" 
              kind        normal.kind        sample.kind 
"Mersenne-Twister"        "Inversion"        "Rejection" 
# RNG kind:  Mersenne-Twister / Inversion / Rejection 
# RNG state: 10403L, 1L, ..., -62050802L [66ed76ed4dfcda86047f57de900516e2] 
# RNG kind:  Mersenne-Twister / Inversion / Rejection 
# RNG state: 10403L, 624L, ..., -1896522223L [31e774b05102e6a88705686b036c1ba9] 
# RNG kind:  Mersenne-Twister / Inversion / Rejection 
# RNG state: 10403L, 1L, ..., -62050802L [66ed76ed4dfcda86047f57de900516e2] 
# RNG kind:  Mersenne-Twister / Inversion / Rejection 
# RNG state: 10403L, 624L, ..., -1896522223L [31e774b05102e6a88705686b036c1ba9] 
# RNG kind:  Marsaglia-Multicarry / Buggy Kinderman-Ramage / Rounding 
# RNG state: 1L, 2L, 3L 
# RNG kind:  Mersenne-Twister / Inversion / Rejection 
# RNG state: 10403L, 624L, ..., -1896522223L [31e774b05102e6a88705686b036c1ba9] 
# RNG kind:  Mersenne-Twister / Inversion / Rejection [base] 
# RNG state: 10403L, 624L, ..., -1896522223L [31e774b05102e6a88705686b036c1ba9] 
$kind
[1] "Mersenne-Twister"

$normal.kind
[1] "Inversion"

$sample.kind
[1] "Rejection"

$kind
[1] "Mersenne-Twister"

$normal.kind
[1] "Inversion"

$sample.kind
[1] "Rejection"

$provider
[1] "base"

$kind
[1] "Mersenne-Twister"

$normal.kind
[1] "Inversion"

$sample.kind
[1] "Rejection"

[1] "31e774b05102e6a88705686b036c1ba9"
[1] "31e774b05102e6a88705686b036c1ba9"
[1] "9d1bafcc4a1a18040eb8ba710712e25c"

rngtools documentation built on May 2, 2019, 5 p.m.