ds.rbind {dsBaseClient}R Documentation

ds.rbind calling rbindDS

Description

Take a sequence of vector, matrix or data-frame arguments and combine them by row to produce a matrix.

Usage

ds.rbind(x = NULL, DataSHIELD.checks = FALSE, force.colnames = NULL,
  newobj = "rbind.out", datasources = NULL,
  notify.of.progress = FALSE)

Arguments

x

This is a vector of character strings representing the names of the elemental components to be combined. For example, the call: ds.rbind(x=c('matrix.m','matrix.n'),newobj='rbind_output') will stack matrix.m on top of matrix.n provided the number of columns of matrix.m and matrix.n are the same. The output object rbind_output is written to the serverside. As many elemental components as needed may be combined using ds.rbind provided they all have the same number of columns. For convenience the x argument can alternatively be specified in a two step procedure, the first being a call to the native R environment on the client server: x.components<-c('matrix.m','matrix.n') then ds.rbind(x=x.components,newobj='rbind_output'). Column names are taken either from the column names of the first object specified in the <x> argument. Alternatively new column names can be user specified using <force.colnames>

DataSHIELD.checks

logical, if TRUE checks are made that all input objects exist and are of an appropriate class. These checks are relatively slow and so the <DataSHIELD.checks> argument is defaulted to FALSE

force.colnames

NULL or a vector of character strings representing the required column names of the output object. For example: force.colnames=c("colname1","name.of.second.column", "lastcol") for an output object with three columns. If <force.colnames> is NULL column names are inferred from the names or column names of the first object specified in the <x> argument. The vector of column names must have the same number of elements as there are columns in the output object. In other words as every specified object in the <x> argument must have the same number of columns the vector of column names must have the same number of elements as there are columns in every object specified in the <x> argument If the length of the column name vector is incorrect a studysideMessage is returned: "Number of column names does not match number of columns in output object. Here 'N' names are required.Please see help for ds.rbind function" where 'N' is the actual number of columns in the output object

newobj

This a character string providing a name for the output data.frame which defaults to 'cbind.out' 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)]

notify.of.progress

specifies if console output should be produce to indicate progress. The default value for notify.of.progress is FALSE.

Details

A sequence of vector, matrix or data-frame arguments is combined row by row to produce a matrix which is written to the serverside. For more details see the native R function rbind. The handling of argument <x> is similar to that of functions ds.cbind and ds.dataFrame

Value

the object specified by the <newobj> argument (or default name <rbind.out>). which is written to the serverside. Unlike the ds.cbind function even if one of the objects specified in the <x> argument is a data.frame the output object will always be of class matrix 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.cbind() 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 ]