ds.seq {dsBaseClient}R Documentation

ds.seq calling seqDS

Description

ds.seq calling assign function seqDS

Usage

ds.seq(FROM.value.char = "1", BY.value.char = "1",
  LENGTH.OUT.value.char = NULL, ALONG.WITH.name = NULL,
  newobj = "newObj", datasources = NULL)

Arguments

FROM.value.char

the starting value for the sequence expressed as an integer in character form. e.g. FROM.value.char="1" will start at 1, FROM.value.char="-10" will start at -10. Default = "1"

BY.value.char

the value to increment each step in the sequence expressed as a numeric e.g. BY.value.char="10" will increment by 10, while BY.value.char="-3.37" will reduce the value of each sequence element by -3.37. Default = "1" but does not have to be integer

LENGTH.OUT.value.char

The length of the sequence at which point its extension should be stopped. e.g. LENGTH.OUT.value.char="1000" will generate a sequence of length 1000. Default = NULL (must be specified) but must be a positive integer

ALONG.WITH.name

For convenience, rather than specifying a value for LENGTH.OUT it can often be better to specify a variable name as the <ALONG.WITH.name> argument. e.g. ALONG.WITH.name = "vector.name". This can be particularly useful in DataSHIELD where the length of the sequence you need to generate in each data set depends on the standard length of vectors in that data set and this will in general vary.

newobj

This a character string providing a name for the output sequence vector which defaults to 'newObj' if no name is specified.

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

Calls an assign function that uses the native R function seq() to create any one of a flexible range of sequence vectors that can then be used to help manage and analyse data. As it is an assign function the resultant vector is written as a new object onto all of the specified data source servers. For the purposes of creating the DataSHIELD equivalent to seq() in native R we have used all of the original arguments (see below) except the <to> argument. This simplifies the function and prevents some combinations of arguments that lead to an error in native R. The effect of the <to> argument - see help(seq) in native R - is to specify the terminal value of the sequence. However, when using seq() one can usually specify other arguments (see below) to mimic the desire effect of <to>. These include: <from>, the starting value of the sequence; <by>, its increment (+ or -), and <length.out> the length of the final vector in each data source.

Value

the object specified by the <newobj> argument (or default name newObj) which is written to the serverside. As well as writing the output object as <newobj> on the serverside, two validity messages are returned indicating whether <newobj> has been created in each data source and if so whether it is in a valid form. If its form is not valid in at least one study - e.g. because a disclosure trap was tripped and creation of the full output object was blocked - ds.seq() also returns any studysideMessages that can explain the error in creating the full output object. As well as appearing on the screen at run time,if you wish to see the relevant studysideMessages at a later date you can use the ds.message function. If you type ds.message("<newobj>") it will print out the relevant studysideMessage from any datasource in which there was an error in creating <newobj> and a studysideMessage was saved. If there was no error and <newobj> was created without problems no studysideMessage will have been saved and ds.message("<newobj>") will return the message: "ALL OK: there are no studysideMessage(s) on this datasource".

Author(s)

Paul Burton for DataSHIELD Development Team


[Package dsBaseClient version 5.0.0 ]