ds.rNorm {dsBaseClient}R Documentation

ds.rNorm calling rNormDS and setSeedDS

Description

Generates random (pseudorandom) numbers with a normal distribution

Usage

ds.rNorm(samp.size = 1, mean = 0, sd = 1, newobj = "newObject",
  seed.as.integer = NULL, return.full.seed.as.set = FALSE,
  force.output.to.k.decimal.places = 9, datasources = NULL)

Arguments

samp.size

the length of the random number vector to be created in each source. <samp.size> can be a numeric scalar and this then specifies the length of the random vectors in each source to be the same. If it is a numeric vector it enables the random vectors to be of different lengths in each source but the numeric vector must be of length equal to the number of data sources being used. Often, one wishes to generate random vectors of length equal to the length of standard vectors in each source. To do this most easily, issue a command such as: numobs.list<-ds.length('varname',type='split') where varname is an arbitrary vector of standard length in all sources. Then issue command: numobs<-unlist(numobs.list) to make numobs numeric rather than a list. Finally, declare samp.size=numobs as the first argument for the ds.rNorm function Please note that because (in this case) numobs is a clientside vector it should be specified without inverted commas (unlike the serverside vectors which may be used for the <mean> and <sd> arguments [see below]).

mean

a numeric scalar specifying the mean of the generating normal distribution in each data source. Alternatively you can specify the <mean> argument to be a serverside vector equal in length to the random number vector you want to generate and this allows the mean to vary by observation in the dataset. If you wish to specify a serverside vector in this way (e.g. called vector.of.means) you must specify the argument as a character string (..., mean="vector.of.means"...). If you simply wish to specify a single but different value in each source, then you can specify <mean> as a scalar and use the <datasources> argument to create the random vectors one source at a time. Default value for <mean> = 0.

sd

a numeric scalar specifying the standard deviation of the generating normal distribution in each data source. Alternatively you can specify the <sd> argument to be a serverside vector equal in length to the random number vector you want to generate and this allows the sd to vary by observation in the dataset. If you wish to specify a serverside vector in this way (e.g. called vector.of.sds) you must specify the argument as a character string (..., sd="vector.of.sds"...) If you simply wish to specify a single but different value in each source, then you can use the <datasources> argument to create the random vectors one source at a time. Default value = 1.

newobj

This a character string providing a name for the output random number vector which defaults to 'newObject' if no name is specified.

seed.as.integer

a numeric scalar or a NULL which primes the random seed in each data source. If <seed.as.integer> is a numeric scalar (e.g. 938) the seed in each study is set as 938*1 in the first study in the set of data sources being used, 938*2 in the second, up to 938*N in the Nth study. If <seed.as.integer> is set as 0 all sources will start with the seed value 0 and all the random number generators will therefore start from the same position. If you want to use the same starting seed in all studies but do not wish it to be 0, you can specify a non-zero scalar value for <seed.as.integer> and then use the <datasources> argument to generate the random number vectors one source at a time (e.g. ,datasources=default.opals[2] to generate the random vector in source 2). As an example, if the <seed.as.integer> value is 78326 then the seed in each source will be set at 78326*1 = 78326 because the vector of datasources being used in each call to the function will always be of length 1 and so the source-specific seed multiplier will also be 1. The function ds.rNorm calls the serverside assign function setSeedDS to create the random seeds in each source

return.full.seed.as.set

logical, if TRUE will return the full random number seed in each data source (a numeric vector of length 626). If FALSE it will only return the trigger seed value you have provided: eg if <seed.as.integer> = 32 and there are three studies, the ds.rNorm function will return: "$integer.seed.as.set.by.source", [1] 32 64 96, rather than the three vectors each of length 626 that represent the full seeds generated in each source. Default is FALSE.

force.output.to.k.decimal.places

scalar integer. Forces the output random number vector to have k decimal places. If 0 rounds it coerces decimal random number output to integer, a k in range 1-8 forces output to have k decimal places. If k = 9, no rounding occurs of native output. Default=9.

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

An assign function that creates a vector of pseudorandom numbers in each data source. This function generates normally distributed random numbers. The function's arguments specify the length of the output vector in each source and the mean and standard deviation (sd) of the normal distribution to generate from.

Value

Writes the pseudorandom number vector with the characteristics specified in the function call as a new serverside vector in each data source. Also returns key information to the clientside: the random seed trigger as specified by you in each source + (if requested) the full 626 length random seed vector this generated in each source (see info for the argument <return.full.seed.as.set>). The ds.rNorm function also returns a vector reporting the length of the pseudorandom vector created in each source.

Author(s)

Paul Burton for DataSHIELD Development Team


[Package dsBaseClient version 5.0.0 ]