Merge pull request datashield#570 from datashield/v6.4.0-dev-feat/as-data-frame

V6.4.0 dev feat/as data frame

Author: StuartWheater

R/ds.asDataFrame.R

@@ -0,0 +1,82 @@
+#' @title  Converts a server-side R object into a data frame
+#' @description Coerces an R object into a data frame maintaining original
+#' class for all columns in data frames.
+#' @details This function is based on the native R function \code{data.frame}.
+#'
+#' Server function called: \code{asDataFrameDS}.
+#' @param x.name a character string providing  the name of the input object to be coerced to
+#' a data frame
+#' @param newobj a character string that provides the name for the output object
+#'  that is stored on the data servers. Default \code{asdataframe.newobj}.
+#' @param datasources a list of \code{\link{DSConnection-class}}
+#' objects obtained after login. If the \code{datasources} argument is not specified
+#' the default set of connections will be used: see \code{\link{datashield.connections_default}}.
+#' @return \code{ds.asDataFrame} returns the object converted into a data frame
+#' that is written to the server-side.
+#' @examples
+#' \dontrun{
+#'   ## Version 6, for version 5 see the Wiki
+#'
+#'   # connecting to the Opal servers
+#'
+#'   require('DSI')
+#'   require('DSOpal')
+#'   require('dsBaseClient')
+#'
+#'   builder <- DSI::newDSLoginBuilder()
+#'   builder$append(server = "study1",
+#'                  url = "http://192.168.56.100:8080/",
+#'                  user = "administrator", password = "datashield_test&",
+#'                  table = "CNSIM.CNSIM1", driver = "OpalDriver")
+#'   builder$append(server = "study2",
+#'                  url = "http://192.168.56.100:8080/",
+#'                  user = "administrator", password = "datashield_test&",
+#'                  table = "CNSIM.CNSIM2", driver = "OpalDriver")
+#'   builder$append(server = "study3",
+#'                  url = "http://192.168.56.100:8080/",
+#'                  user = "administrator", password = "datashield_test&",
+#'                  table = "CNSIM.CNSIM3", driver = "OpalDriver")
+#'   logindata <- builder$build()
+#'
+#'   connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D")
+#'
+#'   # Converting the R object into a data frame
+#'   ds.asDataFrame(x.name = "D",
+#'                   newobj = "mat.obj",
+#'                   datasources = connections[1]) #only the first server is used ("study1")
+#'
+#'   # Clear the Datashield R sessions and logout
+#'   datashield.logout(connections)
+#'
+#' }
+#' @author Tim Cadman
+#' @export
+ds.asDataFrame <- function(x.name=NULL, newobj=NULL, datasources=NULL){
+
+  # look for DS connections
+  if(is.null(datasources)){
+    datasources <- datashield.connections_find()
+  }
+
+  # ensure datasources is a list of DSConnection-class
+  if(!(is.list(datasources) && all(unlist(lapply(datasources, function(d) {methods::is(d,"DSConnection")}))))){
+    stop("The 'datasources' were expected to be a list of DSConnection-class objects", call.=FALSE)
+  }
+
+  if(is.null(x.name)){
+    stop("Please provide the name of the input vector!", call.=FALSE)
+  }
+
+  # check if the input object is defined in all the studies
+  isDefined(datasources, x.name)
+
+  # create a name by default if user did not provide a name for the new variable
+  if(is.null(newobj)){
+    newobj <- "asdataframe.newobj"
+  }
+
+  # call the server side function that does the job
+	calltext <- call("asDataFrameDS", x.name)
+	DSI::datashield.assign(datasources, newobj, calltext)
+
+}

tests/testthat/test-arg-ds.asDataFrame.R

@@ -0,0 +1,30 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2018-2022 University of Newcastle upon Tyne. All rights reserved.
+#
+# This program and the accompanying materials
+# are made available under the terms of the GNU Public License v3.0.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#-------------------------------------------------------------------------------
+
+#
+# Set up
+#
+
+connect.studies.dataset.cnsim(list("LAB_TSC"))
+
+#
+# Tests
+#
+
+context("ds.asDataFrame::arg::test errors")
+test_that("asDataFrame_errors", {
+  expect_error(ds.asDataMatrix(), "Please provide the name of the input vector!", fixed=TRUE)
+})
+
+#
+# Done
+#
+
+disconnect.studies.dataset.cnsim()

tests/testthat/test-smk-ds.asDataFrame.R

@@ -0,0 +1,55 @@
+#-------------------------------------------------------------------------------
+# Copyright (c) 2018-2022 University of Newcastle upon Tyne. All rights reserved.
+#
+# This program and the accompanying materials
+# are made available under the terms of the GNU Public License v3.0.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#-------------------------------------------------------------------------------
+
+#
+# Set up
+#
+
+context("ds.asDataFrame::smk::setup")
+
+connect.studies.dataset.cnsim(list("GENDER"))
+
+test_that("setup", {
+    ds_expect_variables(c("D"))
+})
+
+#
+# Tests
+#
+
+context("ds.asDataFrame::smk::simple test")
+test_that("simple test", {
+    ds.asDataMatrix("D$GENDER")
+    ds.asDataFrame(x.name="asdatamatrix.newobj")
+    res.class <- ds.class("asdataframe.newobj")
+    print(res.class)
+    expect_length(res.class, 3)
+    expect_length(res.class$sim1, 1)
+    expect_true("data.frame" %in% res.class$sim1)
+    expect_length(res.class$sim2, 1)
+    expect_true("data.frame" %in% res.class$sim2)
+    expect_length(res.class$sim3, 1)
+    expect_true("data.frame" %in% res.class$sim3)
+})
+
+#
+# Done
+#
+
+context("ds.asDataFrame::smk::shutdown")
+
+test_that("shutdown", {
+    ds_expect_variables(c("D", "asdatamatrix.newobj", "asdataframe.newobj"))
+})
+
+disconnect.studies.dataset.cnsim()
+
+context("ds.asDataFrame::smk::done")
+