Merge pull request datashield#363 from davraam/v6.1.1-dev

remove the "naAction" argument from ds.cor

Author: StuartWheater

R/ds.cor.R

@@ -3,42 +3,35 @@
 #' @description This function calculates the correlation of two variables or the correlation
 #' matrix for the variables of an input data frame.
 #' @details In addition to computing correlations; this function produces a table outlining the
-#' number of complete cases and a table outlining the number of missing values to allow for the
+#' number of complete cases and a table outlining the number of missing values to allow the
 #' user to decide the 'relevance' of the correlation based on the number of complete
 #' cases included in the correlation calculations.
 #' 
 #' If the argument \code{y} is not NULL, the dimensions of the object have to be 
 #' compatible with the argument \code{x}. 
 #' 
-#' If \code{naAction} is set to \code{'casewise.complete'}, then the function omits all the rows
-#' in the whole data frame that include at least one cell with a missing value before the calculation of correlations.
-#' If \code{naAction} is set to \code{'pairwise.complete'} (default),
-#' then the function divides the input data frame to 
-#' subset data frames formed by each pair between two variables 
-#' (all combinations are considered) and omits the rows
-#' with missing values at each pair separately and then calculates the correlations of those pairs.
+#' The function calculates the pairwise correlations based on casewise complete cases which means that
+#' it omits all the rows in the input data frame that include at least one cell with a missing value,
+#' before the calculation of correlations.
 #' 
-#'  If \code{type} is set to \code{'split'} (default), the correlation of two variables or the
-#'  variance-correlation matrix of an input data frame and the number of 
-#'  complete cases and missing values are returned for every single study. 
-#'  If type is set to \code{'combine'}, the pooled correlation, the total number of complete cases 
-#'  and the total number of missing values aggregated from all the involved studies, are returned.
+#' If \code{type} is set to \code{'split'} (default), the correlation of two variables or the
+#' variance-correlation matrix of an input data frame and the number of complete cases and missing
+#' values are returned for every single study. If type is set to \code{'combine'}, the pooled
+#' correlation, the total number of complete cases and the total number of missing values aggregated
+#' from all the involved studies, are returned.
 #'  
-#'  Server function called: \code{corDS}
+#' Server function called: \code{corDS}
 #' 
 #' @param x a character string providing the name of the input vector, data frame or matrix.
 #' @param y a character string providing the name of the input vector, data frame or matrix.
 #' Default NULL. 
-#' @param naAction a character string giving a method for computing correlations in the
-#' presence of missing values. This must be set to  \code{'casewise.complete'} or
-#' \code{'pairwise.complete'}. Default \code{'casewise.complete'}. For more information see details. 
 #' @param type a character string that represents the type of analysis to carry out. 
 #' This must be set to \code{'split'} or \code{'combine'}.  Default \code{'split'}. For more information see details.
 #' @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.cor} returns a list containing the number of missing values in each variable,
-#' the number of missing variables casewise or pairwise depending on the argument \code{naAction}, the correlation matrix, 
+#' the number of missing variables casewise, the correlation matrix, 
 #' the number of used complete cases. The function applies two disclosure controls. The first disclosure
 #' control checks that the number of variables is not bigger than a percentage of the individual-level records (the allowed
 #' percentage is pre-specified by the 'nfilter.glm'). The second disclosure control checks that none of them is dichotomous
@@ -73,22 +66,20 @@
 #'   connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 
 #'   
 #'   # Example 1: Get the correlation matrix of two continuous variables
-#'   ds.cor(x="D$LAB_TSC", y="D$LAB_TRIG", type="combine", naAction='casewise.complete', 
-#'          datasources = connections)
+#'   ds.cor(x="D$LAB_TSC", y="D$LAB_TRIG", type="combine", datasources = connections)
 #'   
 #'   # Example 2: Get the correlation matrix of the variables in a dataframe
 #'   ds.dataFrame(x=c("D$LAB_TSC", "D$LAB_TRIG", "D$LAB_HDL", "D$PM_BMI_CONTINUOUS"), 
 #'                newobj="D.new", check.names=FALSE, datasources=connections)
-#'   ds.cor("D.new", type="combine", naAction = "casewise.complete", datasources = connections)
-#'   ds.cor("D.new", type="combine", naAction = "pairwise.complete", datasources = connections)
+#'   ds.cor("D.new", type="combine", datasources = connections)
 #' 
 #'   # clear the Datashield R sessions and logout
 #'   datashield.logout(connections)
 #'
 #' }
 #' @export
 #' 
-ds.cor <- function(x=NULL, y=NULL, naAction='casewise.complete', type="split", datasources=NULL){
+ds.cor <- function(x=NULL, y=NULL, type="split", datasources=NULL){
 
   # look for DS connections
   if(is.null(datasources)){
@@ -128,12 +119,12 @@ ds.cor <- function(x=NULL, y=NULL, naAction='casewise.complete', type="split", d
 
   # call the server side function
   if(('matrix' %in% typ) | ('data.frame' %in% typ)){
-    calltext <- call("corDS", x, NULL, naAction)
+    calltext <- call("corDS", x, NULL)
   }else{
     if(!(is.null(y))){
-      calltext <- call("corDS", x, y, naAction)
+      calltext <- call("corDS", x, y)
     }else{
-      calltext <- call("corDS", x, NULL, naAction)
+      calltext <- call("corDS", x, NULL)
     }
   }
   output <- DSI::datashield.aggregate(datasources, calltext)
@@ -156,12 +147,7 @@ ds.cor <- function(x=NULL, y=NULL, naAction='casewise.complete', type="split", d
       correlation[[i]] <- stats::cov2cor(covariance[[i]])
       results[[i]] <- list(output[[i]][[4]][[1]], output[[i]][[4]][[2]], correlation[[i]], output[[i]][[3]])
       n1 <- "Number of missing values in each variable"
-      if(naAction=='casewise.complete'){
-        n2 <- "Number of missing values casewise"
-      }
-      if(naAction=='pairwise.complete'){
-        n2 <- "Number of missing values pairwise"
-      }
+      n2 <- "Number of missing values casewise"
       n3 <- "Correlation Matrix"
       n4 <- "Number of complete cases used"
       names(results[[i]]) <- c(n1, n2, n3, n4)
@@ -198,12 +184,7 @@ ds.cor <- function(x=NULL, y=NULL, naAction='casewise.complete', type="split", d
 
 	  results <- list(combined.missing.cases.vector, combined.missing.cases.matrix, combined.complete.cases, combined.correlation)
       n1 <- "Number of missing values in each variable"
-      if(naAction=='casewise.complete'){
-        n2 <- "Number of missing values casewise"
-      }
-      if(naAction=='pairwise.complete'){
-        n2 <- "Number of missing values pairwise"
-      }
+      n2 <- "Number of missing values casewise"
 	    n3 <- "Number of complete cases used"
 	    n4 <- "Correlation Matrix"
 	    names(results) <- c(n1, n2, n3, n4)