ds.setSeed {dsBaseClient}R Documentation

ds.setSeed calling setSeedDS

Description

Primes the pseudorandom number generator in a data source

Usage

ds.setSeed(seed.as.integer = NULL, datasources = NULL)

Arguments

seed.as.integer

a numeric scalar or a NULL which primes the random seed in each data source. The current limitation on the value of the integer that can be specified is -2147483647 up to +2147483647 (this is +/- ([2^31]-1)). Because you only specify one integer in the call to ds.setSeed (i.e. the value for the <seed.as.integer> argument) that value will be used as the priming trigger value in all of the specified data sources and so the pseudorandom number generators will all start from the same position and if a vector of pseudorandom number values is requested based on one of DataSHIELD's pseudorandom number generating functions precisely the same random vector will be generated in each source. If you want to avoid this you can specify a different priming value in each source by using the the <datasources> argument to generate the random number vectors one source at a time with a different integer in each case. Furthermore, if you use any one of DataSHIELD's pseudorandom number generating functions (ds.rNorm, ds.rUnif, ds.rPois or ds.rBinom) the function call itself automatically uses the single integer priming seed you specify to generate different integers in each source. Thus, by default, when you are generating pseudorandom number vectors in a series of different data sources using the standard DataSHIELD functions the vectors will be different in each source. Given the inbuilt choice of arguments for set.seed() that are fixed in DataSHIELD's setSeedDS function, if a given priming integer is specified as the argument <seed.as.integer> in ds.setSeed the .Random.seed vector that will be generated will be the same on any data source internationally (regardless of the flavour of R). Please note that the first two elements of .Random.seed do not vary meaningfully, in particular, before a seed is set, element 2 varies between different R platforms, but once the seed has been set, it becomes 624 which happens then to be the length of the remaining 624 elements (3-626) of .Random.seed which provide the meaningful component of the random number seed.

datasources

specifies the particular opal object(s) to use. If the <datasources> argument is not specified the default set of opals will be used. The default opals are called default.opals and the default can be set using the function ds.setDefaultOpals. If the <datasources> is to be specified, it should be set without inverted commas: e.g. datasources=opals.em or datasources=default.opals. If you wish to apply the function solely to e.g. the second opal server in a set of three, the argument can be specified as: e.g. datasources=opals.em[2]. If you wish to specify the first and third opal servers in a set you specify: e.g. datasources=opals.em[c(1,3)]

Details

ds.setSeed calls the aggregate function setSeedDS in each data source, passing it a single integer value which acts as a trigger value in that source to generate an instance of the full pseudorandom number seed that is a vector of integers of length 626 called .Random.seed. Each time a new pseudorandom number is generated, the current .Random.seed vector provides a deterministic but very close to behaviourally random way to generate that pseudorandom number and to completely regenerate the random seed vector. Unusually, because setSeedDS is effectively the same as the set.seed() function in native R, although it writes a new object to the serverside (i.e. the integer vector of length 626 known as .Random.seed [see info for the argument <seed.as.integer>]) because this is done directly via calling a native R function this has been set up as an aggregate function not an assign function.

Value

Sets the values of the vector of integers of length 626 known as .Random.seed on each data source that is the true current state of the random seed in each source. Also returns the value of the trigger integer that has primed the random seed vector (.Random.seed) in each source and also the integer vector (626 elements) that is .Random.seed itself.

Author(s)

Paul Burton for DataSHIELD Development Team


[Package dsBaseClient version 5.0.0 ]