mergeDS: mergeDS (assign function) called by ds.merge
In datashield/dsBase: DataSHIELD Server Site Base Functions

mergeDS

R Documentation

mergeDS (assign function) called by ds.merge

Description

merges (links) two data.frames together based on common values in defined vectors in each data.frame

Usage

mergeDS(
  x.name,
  y.name,
  by.x.names.transmit,
  by.y.names.transmit,
  all.x,
  all.y,
  sort,
  suffixes.transmit,
  no.dups,
  incomparables
)

Arguments

`x.name`	the name of the first data.frame to be merged specified in inverted commas. Specified via argument <x.name> of `ds.merge` function
`y.name`	the name of the second data.frame to be merged specified in inverted commas. Specified via argument <y.name> of `ds.merge` function
`by.x.names.transmit`	the name of a single variable or a vector of names of multiple variables (in transmittable form) containing the IDs or other data on which data.frame x is to be merged/linked to data.frame y. Specified via argument <by.x.names> of `ds.merge` function
`by.y.names.transmit`	the name of a single variable or a vector of names of multiple variables (in transmittable form) containing the IDs or other data on which data.frame y is to be merged/linked to data.frame x. Specified via argument <by.y.names> of `ds.merge` function
`all.x`	logical, if TRUE, then extra rows will be added to the output, one for each row in x that has no matching row in y. Specified via argument <all.x> of `ds.merge` function. Default = FALSE.
`all.y`	logical, if TRUE, then extra rows will be added to the output, one for each row in y that has no matching row in x. Specified via argument <all.y> of `ds.merge` function. Default = FALSE.
`sort`	logical, if TRUE the merged result should be sorted on elements in the by.x.names and by.y.names columns. Specified via argument <sort> of `ds.merge` function. Default = TRUE.
`suffixes.transmit`	a character vector of length 2 (in transmittable form) specifying the suffixes to be used for making unique common column names in the two input data.frames when they both appear in the merged data.frame. Specified via argument <suffixes> of `ds.merge` function. Default '.x' and '.y'.
`no.dups`	logical, when TRUE suffixes are appended in more cases to rigorously avoid duplicated column names in the merged data.frame. Specified via argument <no.dups> of `ds.merge` function. Default TRUE but was apparently implicitly FALSE before R version 3.5.0.
`incomparables`	values intended for merging on one column which cannot be matched. See 'match' in help for Native R `merge` function. Specified via argument <incomparables> of `ds.merge`

Details

For further information see details of the native R function merge and the DataSHIELD clientside function ds.merge.

Value

the merged data.frame specified by the <newobj> argument of ds.merge (or by default 'x.name_y.name' if the <newobj> argument is NULL) which is written to the serverside. In addition, two validity messages are returned to the clientside 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 there may be a studysideMessage 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".