setBiocSeed: Smart seed setter
In LTLA/BiocSeed: Setting the Random Seed in Bioconductor Packages

Description Usage Arguments Details Value Author(s) Examples

View source: R/setBiocSeed.R

Set the seed in a “deterministically variable” manner, typically for use within functions that have some stochastic component. This aims to provide a compromise between convenient reproducibility and statistical rigor.

setBiocSeed(x, seed = NULL)

unsetBiocSeed(previous)

enableBiocSeed()

disableBiocSeed()

`x`	An integer or character vector, or a list containing any number of such vectors.
`seed`	An optional integer scalar specifying the actual seed to use.
`previous`	An integer vector corresponding to the previous seed or `NA`, typically returned by `setBiocSeed`.
`digits`	Integer scalar specifying the number of significant digits to retain for double or complex `x`.

The choice of seed is based on x, somehow derived from the dataset of interest. Specifically, we take the integer/character vectors in x and hash them to obtain an integer to use as the seed. This ensures that results for any given dataset are reproducible while avoiding the use of a constant seed for all datasets.

The original seed in .Random.seed is restored upon calling unsetBiocSeed. This ensures that we do not clobber the seed in the user's session by consistently resetting it to the same value. The typical pattern is to call unsetBiocSeed in on.exit with the return value of setBiocSeed.

Alternatively, the user can explicitly pass in a non-NULL value for seed, which is used directly rather than deriving the seed from x. This may be useful if the seed derived from x is not appropriate and/or the user wants to test out the effects of different seeds. Note that this, again, has no effect in nested calls beyond the first.

Finally, the entire system can be turned on or with disableBiocSeed and enableBiocSeed. This is useful for backcompatibility where users can control the process via the global set.seed.

setBiocSeed will set the global seed to some deterministically chosen value based on x. It invisibly returns the old value of .Random.seed.

unsetBiocSeed will restore the global seed to what it was before calling setBiocSeed. It will also return NULL invisibly.

disableBiocSeed will cause all setBiocSeed and unsetBiocSeed to be no-ops. This is reversed by enableBiocSeed. Both functions return NULL invisibly.

Aaron Lun

info <- setBiocSeed(letters)
runif(5)
unsetBiocSeed(info)

# Same as above.
info <- setBiocSeed(letters)
runif(5)
unsetBiocSeed(info)

# Different, but deterministically so.
info <- setBiocSeed(LETTERS)
runif(5)
unsetBiocSeed(info)

# Does not affect the RNG outside of the set/unset pair.
info <- setBiocSeed(LETTERS)
X <- runif(5)
unsetBiocSeed(info)
runif(1)

info <- setBiocSeed(LETTERS)
X <- runif(5)
unsetBiocSeed(info)
runif(1)

# Typical usage in a function:
FUN <- function(x) {
    info <- setBiocSeed(head(x))
    on.exit(unsetBiocSeed(info))
    sample(x)
}

FUN(1:10)
FUN(1:10)