R/ds.mice.cc.R

In gflcampos/dsMiceClient: DataSHIELD client-side functions for the mice package

#'
#'@title Select complete cases
#'@description Extracts the complete cases, also known as \emph{listwise deletion}.
#'\code{cc(x)} is similar to 
#'\code{na.omit(x)}, but returns an object of the same class 
#'as the input data. Dimensions are not dropped.
#'
#'@param varname A character object that will be the name of the variable 
#'to which the result of the function will be assigned on the server-side
#'@param x An \code{R} object. Methods are available for classes
#'\code{mids}, \code{data.frame} and \code{matrix}. Also, \code{x} 
#'could be a vector.
#'@examples
#'
#'
#'# In this example, we assume that the Opal server to which we are connecting, 
#'# has a table that contains the 'boys' data from the original mice package.
#'
## Load DataSHIELD libraries
#'library(dsBaseClient)
#'library(dsMiceClient)
#'
#'# Build login information
#'server <- c("server_name")
#'url <- c("opal_url")
#'user <- "username"
#'password <- "password"
#'table <- c("project_name.table_name")
#'logindata <- data.frame(server,url,user,password,table)
#'
#'# Login and assign the 'boys' dataset to varable 'D' on the server-side
#'opals<-datashield.login(logins=logindata, assign=TRUE)
#'
#'# Check dimension of D
#'ds.dim('D')
#'
#'# Extract complete cases from D and assign result to D2
#'ds.mice.cc("D2", "D")
#'
#'# Check dimension of D2 (should be equal to or smaller than dim of D)
#'ds.dim('D2')
#'
#'@export

ds.mice.cc = function(varname = NULL, x = NULL, checks=TRUE, datasources=NULL) {
  
  # check that varname and x are not NULL
  if (is.null(varname) || is.null(x)) {
    stop("Please provide the following arguments:\n",
      "\tvarname: name of the variable to which the result will be assigned on the server-side\n",
      "\tx: an object of class mids, data.frame, matrix or vector\n", call.=FALSE)
  }
  
  # if no opal login details are provided look for 'opal' objects in the environment
  if (is.null(datasources)) {
    datasources <- dsBaseClient:::findLoginObjects()
  }
  
  # check that x is defined in the remote server environment
  dsBaseClient:::isDefined(datasources, x)
  
  # call the server-side function ccDS
  cally <- paste0("ccDS(", x, ")")
  datashield.assign(datasources, varname, as.symbol(cally))
  
  # check that the new object has been created and display a message accordingly
  finalcheck <- dsBaseClient:::isAssigned(datasources, varname)
}