ds.recodeValues.o {dsBetaTestClient}R Documentation

ds.recodeValues.o

Description

Converts the values of a specified set of individual elements in a vector into a specified set of new values

Usage

ds.recodeValues.o(var.name = NULL, values2replace.vector = NULL,
  new.values.vector = NULL, newobj = NULL,
  force.output.format = "no", datasources = NULL)

Arguments

var.name

A character string specifying the name of the vector whose values are to be changed

values2replace.vector

A vector containing the value of elements in <var.name> that are to be changed. This must either be specified in format c(1,2,8,...) where all values are numeric or, more generally, as c(1,2,"hhh",-1,"b",NA,5,...) where the values specified can include numerics, characters (in inverted commas) or NA (missing) values. Note when NA is specified it is specified as NA not "NA". The <values2replace.vector> must not be specified as a single character string: e.g. "c(1,2,8)". No value in <values2replace.vector> can be repeated. Values that do not occur in the <var.name> vector can be included (they simply do nothing).

new.values.vector

A vector of the same length as <values2replace.vector> to which the values in <values2replace.vector> are to be changed in recoding the vector <var.name>. The specification format is identical to that for <values2replace.vector> except that values in <new.values.vector> can be repeated.

newobj

A character string specifying the name of the vector to which the new recoded variable is to be written. If no <newobj> argument is specified, the recoded variable name defalults to "var.name_recoded" where <var.name> is the first argument of the function.

force.output.format

A boolean.

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.o. If the <datasources> is to be specified, it should be set without 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

The elements to change are identified solely by value, not position of the elements in the vector - this is because of the potential disclosure risk of the latter approach. Recoding is undertaken by replacing all elements in the input vector, which is specified by the argument <var.name>, that have a value equal to the kth element of <values2replace.vector> with the value corresponding to the kth element of <new.values.vector>. This implies strict ordered one-to-one mapping. There is no need to ensure that the values in either <values2replace.vector> or <new.values.vector> are numerically or alphabetically ordered. If the only change required is to modify. There is one quirk in the function: specifically, if the only requirement is to replace NA (missing) values in <var-name> with a new non-missing value, the argument <values2replace.vector> cannot simply be specified as NA or c(NA) because this represents a vector with no non-missing values which confuses the analytic processing. As an easy work round however, you can instead specify a second value in the two value replacement vectors that maps to itself and thereforechanges changes nothing. So, for example, <value2replace.vector> can be specified as c(3,NA) and <new.values.vector> as c(3,99). This then changes NAs to 99s while leaving values of 3 as 3.

Value

the object specified by the <newobj argument (or default name varname_recoded) which is written to the serverside . In addition, a validity message indicating whether <newobj> has been correctly created at each source is returned to the client. There are some circumstances in which it will be reported that <newobj> has been created in every datasource but in one or more data servers <newobj> will contain an error message rather than the recoded vector. The reason for this will appear as a warning in the screen output as the function is run - it will generally be because one or more of the inputs or outputs to the function fails to satisfy the disclosure thresholds that have been specified for your analysis. As well as appearing on the screen at run time, the warning is also written as a studysideMessage, which is saved as a list object named <newobj>$studysideMessage. If you wish to see the studysideMessage at a later date you can use the ds.message.o function. If you type ds.message.o("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.o("newobj") will return the message: "ALL OK: there are no studysideMessage(s) on this datasource".

Author(s)

Burton PR; Gaye A


[Package dsBetaTestClient version 0.2.0 ]