Package 'dsBaseClient'

Description

Computes the absolute values for a specified numeric or integer vector. This function is similar to R function abs.

Usage

ds.abs(x = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

The function calls the server-side function absDS that computes the absolute values of the elements of a numeric or integer vector and assigns a new vector with those absolute values on the server-side. The name of the new generated vector is specified by the user through the argument newobj, otherwise is named by default to abs.newobj.

Value

ds.abs assigns a vector for each study that includes the absolute values of the input numeric or integer vector specified in the argument x. The created vectors are stored in the servers.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Examples

## Not run: 

  # 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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 
  
  # Example 1: Generate a normally distributed variable with zero mean and variance equal
  #  to one and then get their absolute values
  ds.rNorm(samp.size=100, mean=0, sd=1, newobj='var.norm', datasources=connections)
  # check the quantiles
  ds.summary(x='var.norm', datasources=connections)
  ds.abs(x='var.norm', newobj='var.norm.abs', datasources=connections)
  # check now the changes in the quantiles
  ds.summary(x='var.norm.abs', datasources=connections)  

  # Example 2: Generate a sequence of negative integer numbers from -200 to -100
  # and then get their absolute values
  ds.seq(FROM.value.char = '-200', TO.value.char = '-100', BY.value.char = '1', 
         newobj='negative.integers', datasources=connections)
  # check the quantiles
  ds.summary(x='negative.integers', datasources=connections)
  ds.abs(x='negative.integers', newobj='positive.integers', datasources=connections)
  # check now the changes in the quantiles
  ds.summary(x='positive.integers', datasources=connections)

  # clear the Datashield R sessions and logout
  datashield.logout(connections) 


## End(Not run)

Description

Converts the input object into a character class. This function is based on the native R function as.character.

Usage

ds.asCharacter(x.name = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

Server function called: asCharacterDS

Value

ds.asCharacter returns the object converted into a class character that is written to the server-side. Also, two validity messages are returned to the client-side indicating the name of the newobj which has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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 class character
  ds.asCharacter(x.name = "D$LAB_TSC",
                 newobj = "char.obj",
                 datasources = connections[1]) #only the first Opal server is used ("study1")
                 
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

Coerces an R object into a matrix maintaining original class for all columns in data frames.

Usage

ds.asDataMatrix(x.name = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

This function is based on the native R function data.matrix.

Server function called: asDataMatrixDS.

Value

ds.asDataMatrix returns the object converted into a matrix that is written to the server-side. Also, two validity messages are returned to the client-side indicating the name of the newobj which has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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 matrix
  ds.asDataMatrix(x.name = "D",
                  newobj = "mat.obj",
                  datasources = connections[1]) #only the first Opal server is used ("study1")
                 
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

This function assigns a server-side numeric vector into a factor class.

Usage

ds.asFactor(
  input.var.name = NULL,
  newobj.name = NULL,
  forced.factor.levels = NULL,
  fixed.dummy.vars = FALSE,
  baseline.level = 1,
  datasources = NULL
)

Arguments

Details

Converts a numeric vector into a factor type which is represented either as a vector or as a matrix of dummy variables depending on the argument fixed.dummy.vars. The matrix of dummy variables also depends on the argument baseline.level.

ds.asFactor.R and its associated serverside functions asFactorDS1 and asFactorDS2 are to be used when you have variable that has up to 40 unique levels across all sources combined. If one of the sources does not contain any subjects at a particular level, that level will still be created as an empty category. In the end all sources thus include a factor variable with consistent factor levels across all sources - one level for every unique value that occurs in at least one source. This is important when you wish to fit models using ds.glm because the factor levels must be consistent across all studies or the model will not fit.

But in order for this to be possible, all sources have to share all of the unique values their source holds for the variable. This allows the client to create a single vector containing all of the unique factor levels across ALL sources. But this is potentially disclosive if there are too many levels. There are therefore two checks on the number of levels in each source. One is simply a test of whether the number of levels exceeds a value specified by the Roption value 'nfilter.max.levels' which is set by default to 40, but the data custodian for the source can choose any alternative value he/she chooses. The second test is of whether the levels are too dense: ie do the number of levels exceed a specified proportion of the full length of the relevant vector in the particular source. The max density is set by the Roption value 'nfilter.levels' which takes the default value 0.33 but can again be modified by the data custodian.

In combination, these two checks mean that if a factor has 35 levels in a given study where the total length of the variable to be converted to a factor is 1000 individuals, the ds.asFactor function will process that variable appropriately. But if it had had 45 levels it would have been blocked by 'nfilter.max.levels' and if the total length of the variable in that study had only been 70 subjects it would have been blocked by the density criterion held in 'nfilter.levels'.

If you have a factor with more than 40 levels in each source - perhaps most commonly an ID of some sort that you need to provide as an argument to eg a tapply function. Then you cannot use ds.asFactor. Typically in these circumstance you simply want to create a factor that is appropriate for each source but you do not need to ensure that all levels are consistent across all sources. In that case, you can use the ds.asFactorSimple function which does no more than coerce a numeric or character variable to a factor. Because you do not need to share unique factor levels between sources, there is then no disclosure issue.

To understand how the matrix of the dummy variable is created let's assume that we have the vector (1, 2, 1, 3, 4, 4, 1, 3, 4, 5) of ten integer numbers. If we set the argument fixed.dummy.vars = TRUE, baseline.level = 1 and forced.factor.levels = c(1,2,3,4,5). The input vector is converted to the following matrix of dummy variables:

For the same example if the baseline.level = 3 then the matrix is:

In the first instance the first row of the matrix has zeros in all entries indicating that the first data point belongs to level 1 (as the baseline level is equal to 1). The second row has 1 at the first (DV2) column and zeros elsewhere, indicating that the second data point belongs to level 2. In the second instance (second matrix) where the baseline level is equal to 3, the first row of the matrix has 1 at the first (DV1) column and zeros elsewhere, indicating again that the first data point belongs to level 1. Also as we can see the fourth row of the second matrix has all its elements equal to zero indicating that the fourth data point belongs to level 3 (as the baseline level, in that case, is 3).

If the baseline.level is set to be equal to a value that is not one of the levels of the factor then a matrix of dummy variables is created having as many columns as the number of levels. In that case in each row there is a unique entry equal to 1 at a certain column indicating the level of each data point. So, for the above example where the vector has five levels if we set the baseline.level equal to a value that does not belong to those five levels (baseline.level=8) the matrix of dummy variables is:

Server functions called: asFactorDS1 and asFactorDS2

Value

ds.asFactor returns the unique levels of the converted variable in ascending order and a validity message with the name of the created object on the client-side and the output matrix or vector in the server-side.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 

  ## Version 6, for version 5 see 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()

  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 

  ds.asFactor(input.var.name = "D$PM_BMI_CATEGORICAL", 
              newobj.name = "fact.obj", 
              forced.factor.levels = NULL, #a vector with all unique levels 
                                           #from all studies is created
              fixed.dummy.vars = TRUE, #create a matrix of dummy variables
              baseline.level = 1,
              datasources = connections)#all the Opal servers are used, in this case 3 
                                        #(see above the connection to the servers) 
  ds.asFactor(input.var.name = "D$PM_BMI_CATEGORICAL", 
              newobj.name = "fact.obj", 
              forced.factor.levels = c(2,3), #the variable is split in 2 levels
              fixed.dummy.vars = TRUE, #create a matrix of dummy variables
              baseline.level = 1,
              datasources = connections[1])#only the first Opal server is used ("study1")

   # Clear the Datashield R sessions and logout  
   datashield.logout(connections) 

## End(Not run)

Description

ds.asFactorSimple calls the assign function asFactorSimpleDS and thereby coerces a numeric or character vector into a factor

Usage

ds.asFactorSimple(
  input.var.name = NULL,
  newobj.name = NULL,
  datasources = NULL
)

Arguments

Details

The function converts the input variable into a factor. Unlike ds.asFactor and its serverside functions, ds.asFactorSimple does no more than coerce the class of a variable to make it a factor on the serverside in each data source. It does not check for or enforce consistency of factor levels across sources or allow you to force an arbitrary set of levels unless those levels actually exist in the sources. Furthermore, it does not allow you to create an array of binary dummy variables that is equivalent to a factor. If you need to do any of these things you will have to use the ds.asFactor function.

Value

an output vector of class factor to the serverside. In addition, returns a validity message with the name of the created object on the client-side and if creation fails an error message which can be viewed using datashield.errors().

Author(s)

DataSHIELD Development Team

Description

Coerces an R object into an integer class. This function is based on the native R function as.integer.

Usage

ds.asInteger(x.name = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

This function is based on the native R function as.integer. The only difference is that the DataSHIELD function first converts the values of the input object into characters and then convert those to integers. This addition, it is important for the case where the input object is of class factor having integers as levels. In that case, the native R as.integer function returns the underlying level codes and not the values as integers. For example as.integer in R converts the factor vector:
[1] 0 1 1 2 1 0 1 0 2 2 2 1
Levels: 0 1 2
to the following integer vector: 1 2 2 3 2 1 2 1 3 3 3 2

Server function called: asIntegerDS

Value

ds.asInteger returns the R object converted into an integer that is written to the server-side. Also, two validity messages are returned to the client-side indicating the name of the newobj which has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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 an integer
  ds.asInteger(x.name = "D$LAB_TSC",
                  newobj = "int.obj",
                  datasources = connections[1]) #only the first Opal server is used ("study1")
  ds.class(x = "int.obj", datasources = connections[1])   
  
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

Coerces an R object into a list. This function is based on the native R function as.list.

Usage

ds.asList(x.name = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

Server function called: asListDS

Value

ds.asList returns the R object converted into a list which is written to the server-side. Also, two validity messages are returned to the client-side indicating the name of the newobj which has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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 List
  ds.asList(x.name = "D",
  newobj = "D.asList", 
  datasources = connections[1]) #only the first Opal server is used ("study1")
  ds.class(x = "D.asList", datasources = connections[1])   
              
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

Coerces an R object into a logical class. This function is based on the native R function as.logical.

Usage

ds.asLogical(x.name = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

Server function called: asLogicalDS

Value

ds.asLogical returns the R object converted into a logical that is written to the server-side. Also, two validity messages are returned to the client-side indicating the name of the newobj which has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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 logical
  ds.asLogical(x.name = "D$LAB_TSC", 
               newobj = "logical.obj", 
               datasources =connections[1]) #only the first Opal server is used ("study1")
  ds.class(x = "logical.obj", datasources = connections[1])  
               
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

Coerces an R object into a matrix. This converts all columns into character class.

Usage

ds.asMatrix(x.name = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

This function is based on the native R function as.matrix. If this function is applied to a data frame, all columns are converted into a character class. If you wish to convert a data frame to a matrix but maintain all data columns in their original class you should use the function ds.asDataMatrix.

Server function called: asMatrixDS

Value

ds.asMatrix returns the object converted into a matrix that is written to the server-side. Also, two validity messages are returned to the client-side indicating the name of the newobj which has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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 matrix
  ds.asMatrix(x.name = "D",
              newobj = "mat.obj",
              datasources = connections[1]) #only the first Opal server is used ("study1")
                 
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

Coerces an R object into a numeric class. This function is based on the native R function as.numeric.

Usage

ds.asNumeric(x.name = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

This function is based on the native R function as.numeric. However, it behaves differently with some specific classes of variables. For example, if the input object is of class factor, it first converts its values into characters and then convert those to numerics. This behaviour is important for the case where the input object is of class factor having numbers as levels. In that case, the native R as.numeric function returns the underlying level codes and not the values as numbers. For example as.numeric in R converts the factor vector:
0 1 1 2 1 0 1 0 2 2 2 1
Levels: 0 1 2
to the following numeric vector: 1 2 2 3 2 1 2 1 3 3 3 2
In contrast DataSHIELD converts an input factor with numeric levels to its original numeric values.

Server function called: asNumericDS

Value

ds.asNumeric returns the R object converted into a numeric class that is written to the server-side. Also, two validity messages are returned to the client-side indicating the name of the newobj which has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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 numeric class
  ds.asNumeric(x.name = "D$LAB_TSC",
                  newobj = "num.obj",
                  datasources = connections[1]) #only the first Opal server is used ("study1")
  ds.class(x = "num.obj", datasources = connections[1]) 
                
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

This function assigns a datashield object to a name, hence creating a new object.

Usage

ds.assign(toAssign = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

The new object is stored on the server-side.

ds.assign causes a remote assignment by using DSI::datashield.assign. The toAssign argument is checked at the server and assigned the variable called newobj on the server-side.

Value

ds.assign returns the R object assigned to a name that is written to the server-side.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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") 
  
  # Assign a variable to a name
  ds.assign(toAssign = "D$LAB_TSC",
            newobj = "labtsc",
            datasources = connections[1]) #only the first Opal server is used ("study1")
                
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

This function calculates the C-statistic or AUC for logistic regression models.

Usage

ds.auc(pred = NULL, y = NULL, datasources = NULL)

Arguments

Details

The AUC determines the discriminative ability of a model.

Value

returns the AUC and its standard error

Author(s)

Demetris Avraam for DataSHIELD Development Team

Description

It compares R objects using the standard set of Boolean operators (==, !=, >, >=, <, <=) to create a vector with Boolean indicators that can be of class logical (TRUE/FALSE) or numeric (1/0).

Usage

ds.Boole(
  V1 = NULL,
  V2 = NULL,
  Boolean.operator = NULL,
  numeric.output = TRUE,
  na.assign = "NA",
  newobj = NULL,
  datasources = NULL
)

Arguments

Details

A combination of different Boolean operators using AND operator can be obtained by multiplying two or more binary/Boolean vectors together. In this way, observations taking the value 1 in every vector will then take the value 1 in the final vector (after multiplication) while all others will take the value 0. Instead the combination using OR operator can be obtained by the sum of two or more vectors and applying ds.Boole using the operator >= 1.

In na.assign if 'NA' is specified, the missing values remain as NAs in the output vector. If '1' or '0' is specified the missing values are converted to 1 or 0 respectively or TRUE or FALSE depending on the argument numeric.output.

Server function called: BooleDS

Value

ds.Boole returns the object specified by the newobj argument which is written to the server-side. Also, two validity messages are returned to the client-side indicating the name of the newobj which has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 

  ## 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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 

  # Generating Boolean indicators
  ds.Boole(V1 = "D$LAB_TSC",
           V2 = "D$LAB_TRIG",
           Boolean.operator = ">",
           numeric.output = TRUE, #Output vector of 0 and 1
           na.assign = "NA",      
           newobj = "Boole.vec",
           datasources = connections[1]) #only the first server is used ("study1")
           
  ds.Boole(V1 = "D$LAB_TSC",
           V2 = "D$LAB_TRIG",
           Boolean.operator = "<",
           numeric.output = FALSE, #Output vector of TRUE and FALSE 
           na.assign = "1", #NA values are converted to TRUE
           newobj = "Boole.vec",
           datasources = connections[2]) #only the second server is used ("study2") 
                      
  ds.Boole(V1 = "D$LAB_TSC",
           V2 = "D$LAB_TRIG",
           Boolean.operator = ">",
           numeric.output = TRUE, #Output vector of 0 and 1
           na.assign = "0", #NA values are converted to 0      
           newobj = "Boole.vec",
           datasources = connections) #All servers are used
  
  # Clear the Datashield R sessions and logout           
  datashield.logout(connections)

## End(Not run)

Description

Draw boxplot with data on the study servers (data frames or numeric vectors) with the option of grouping using categorical variables on the dataset (only for data frames)

Usage

ds.boxPlot(
  x,
  variables = NULL,
  group = NULL,
  group2 = NULL,
  xlabel = "x axis",
  ylabel = "y axis",
  type = "pooled",
  datasources = NULL
)

Arguments

Value

ggplot object

Examples

## Not run: 
  ## Version 6, for version 5 see the Wiki
  
  ### Please ensure you have a training Virtual Machine running,
  # or that you have a live connection to a server.
     
  # 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") 
  
  ## Create a boxplot of one variable
  ds.boxPlot("D", "LAB_HDL", datasources = connections)
 
  ## Create a boxplot that is split by study:
  ds.boxPlot("D", "LAB_HDL", type= "split", datasources = connections)
  
  ## Create a boxplot of two variables variable
  ds.boxPlot("D", c("LAB_HDL", "LAB_TRIG"), type="pooled",
  datasources = connections)
  # only one plot is created (of the aggregated results of all servers)
  
  ## Create a boxplot of two variables, which are split by a factor
  ds.boxPlot("D", c("LAB_HDL", "LAB_TRIG"), group = "GENDER",
  datasources = connections)
  
  ## Create a boxplot with x- and y-axis labels
  ds.boxPlot("D", c("LAB_HDL", "LAB_TRIG"), group = "GENDER",
  xlabel = "Variable", ylabel = "Measurement", datasources = connections)
  
  ## Improve the presentation of ds.boxplot output using ggplot:
  ### User must save the output, which is in a ggplot format already:
  a <- ds.boxPlot("D", c("LAB_HDL", "LAB_TRIG"), group = "GENDER",
  xlabel = "Variable", ylabel = "Measurement", datasources = connections)
                 
  ### Then customise output "a" using ggplot tools:
  a + ggplot2::scale_fill_discrete(name = "Gender", labels = c("Male", "Female"))
  
  ### Or use an alternative way, to maintain the aesthetics:
  a + ggplot2::scale_fill_brewer(name = "Gender", labels = c("Male", "Female"))
                                                                                
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections)
  

## End(Not run)

Description

Internal function. Renders a ggplot boxplot by retrieving from the server side a list with the identity stats and other parameters to render the plot without passing any data from the original dataset

Usage

ds.boxPlotGG(
  x,
  group = NULL,
  group2 = NULL,
  xlabel = "x axis",
  ylabel = "y axis",
  type = "pooled",
  datasources = NULL
)

Arguments

Value

ggplot object

Description

Internal function

Usage

ds.boxPlotGG_data_Treatment(
  table,
  variables,
  group = NULL,
  group2 = NULL,
  datasources = NULL
)

Arguments

Value

Does not return nothing, it creates the table "boxPlotRawData" on the server arranged to be passed to the ggplot boxplot function. Structure of the created table:

Column 'x': Names on the X axis of the boxplot, aka variables to plot
Column 'value': Values for that variable (raw data of columns rbinded)
Column 'group': (Optional) Values of the grouping variable
Column 'group2': (Optional) Values of the second grouping variable

Description

Internal function

Usage

ds.boxPlotGG_data_Treatment_numeric(vector, datasources = NULL)

Arguments

Value

Does not return nothing, it creates the table "boxPlotRawDataNumeric" on the server arranged to be passed to the ggplot boxplot function. Structure of the created table:

Column 'x': Names on the X axis of the boxplot, aka name of the vector (vector argument)
Column 'value': Values for that variable

Description

Draw boxplot with information from a numeric vector

Usage

ds.boxPlotGG_numeric(
  x,
  xlabel = "x axis",
  ylabel = "y axis",
  type = "pooled",
  datasources = NULL
)

Arguments

Value

ggplot object

Description

Draws a boxplot with the option of adding two grouping variables from data held on a table

Usage

ds.boxPlotGG_table(
  x,
  variables,
  group = NULL,
  group2 = NULL,
  xlabel = "x axis",
  ylabel = "y axis",
  type = "pooled",
  datasources = NULL
)

Arguments

Value

ggplot object

Description

The function calculates blood pressure z-scores in two steps: Step 1. Calculates z-score of height according to CDC growth chart (Not the WHO growth chart!). Step 2. Calculates z-score of BP according to the fourth report on BP management, USA

Usage

ds.bp_standards(
  sex = NULL,
  age = NULL,
  height = NULL,
  bp = NULL,
  systolic = TRUE,
  newobj = NULL,
  datasources = NULL
)

Arguments

Value

assigns a new object on the server-side. The assigned object is a list with two elements: the 'Zbp' which is the zscores of the blood pressure and 'perc' which is the percentiles of the BP zscores.

Author(s)

Demetris Avraam for DataSHIELD Development Team

References

The fourth report on the diagnosis, evaluation, and treatment of high blood pressure in children and adolescents: https://www.nhlbi.nih.gov/sites/default/files/media/docs/hbp_ped.pdf

Description

Concatenates objects into one vector.

Usage

ds.c(x = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

To avoid combining the character names and not the vectors on the client-side, the names are coerced into a list and the server-side function loops through that list to concatenate the list's elements into a vector.

Server function called: cDS

Value

ds.c returns the vector of concatenating R objects which are written to the server-side.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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") 
  
  # Create a vector with combined objects
  myvect <- c("D$LAB_TSC", "D$LAB_HDL")
  ds.c(x = myvect,
       newobj = "new.vect",
       datasources = connections[1]) #only the first Opal server is used ("study1")
                
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

Takes a sequence of vector, matrix or data-frame arguments and combines them by column to produce a data-frame.

Usage

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

Arguments

Details

A sequence of vector, matrix or data-frame arguments is combined column by column to produce a data-frame that is written to the server-side.

This function is similar to the native R function cbind.

In DataSHIELD.checks the checks are relatively slow. Default DataSHIELD.checks value is FALSE.

If force.colnames is NULL (which is recommended), the column names are inferred from the names or column names of the first object specified in the x argument. If this argument is not NULL, then the column names of the assigned data.frame have the same order as the characters specified by the user in this argument. Therefore, the vector of force.colnames must have the same number of elements as the columns in the output object. In a multi-site DataSHIELD setting to use this argument, the user should make sure that each study has the same number of names and column names of the input elements specified in the x argument and in the same order in all the studies.

Server function called: cbindDS

Value

ds.cbind returns a data frame combining the columns of the R objects specified in the function which is written to the server-side. It also returns to the client-side two messages with the name of newobj that has been created in each data source and DataSHIELD.checks result.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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()

  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 

  # Example 1: Assign the exponent of a numeric variable at each server and cbind it 
  # to the data frame D
  
  ds.exp(x = "D$LAB_HDL",
         newobj = "LAB_HDL.exp",
         datasources = connections) 
         
  ds.cbind(x = c("D", "LAB_HDL.exp"),
           DataSHIELD.checks = FALSE,
           newobj = "D.cbind.1",
           datasources = connections)
             
  # Example 2: If there are duplicated column names in the input objects the function adds
  # a suffix '.k' to the kth replicate". If also the argument DataSHIELD.checks is set to TRUE
  # the function returns a warning message notifying the user for the existence of any duplicated
  # column names in each study
  
  ds.cbind(x = c("LAB_HDL.exp", "LAB_HDL.exp"), 
           DataSHIELD.checks = TRUE,
           newobj = "D.cbind.2",
           datasources = connections)
           
  ds.colnames(x = "D.cbind.2",
              datasources = connections)            
             
  # Example 3: Generate a random normally distributed variable of length 100 at each study,
  # and cbind it to the data frame D. This example fails and  returns an error as the length
  # of the generated variable "norm.var" is not the same as the number of rows in the data frame D
  
  ds.rNorm(samp.size = 100,
           newobj = "norm.var",
           datasources = connections) 
           
  ds.cbind(x = c("D", "norm.var"), 
           DataSHIELD.checks = FALSE,
           newobj = "D.cbind.3", 
           datasources = connections)                 
                   
  # Clear the Datashield R sessions and logout  
  datashield.logout(connections) 
  
## End(Not run)

Description

Change the reference level of a factor, by putting the reference group first.

This function is similar to R function relevel.

Usage

ds.changeRefGroup(
  x = NULL,
  ref = NULL,
  newobj = NULL,
  reorderByRef = FALSE,
  datasources = NULL
)

Arguments

Details

This function allows the user to re-order the vector, putting the reference group first. It should be mentioned that by default the reference is the first level in the vector of levels. If the user chooses the re-order a warning is issued as this can introduce a mismatch of values if the vector is put back into a table that is not reordered in the same way. Such mismatch can render the results of operations on that table invalid.

Server function called: changeRefGroupDS

Value

ds.changeRefGroup returns a new vector with the specified level as a reference which is written to the server-side.

Author(s)

DataSHIELD Development Team

See Also

ds.cbind Combines objects column-wise.

ds.levels to obtain the levels (categories) of a vector of type factor.

ds.colnames to obtain the column names of a matrix or a data frame

ds.asMatrix to coerce an object into a matrix type.

ds.dim to obtain the dimensions of a matrix or a data frame.

Examples

## Not run: 

  ## 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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 

  # Changing the reference group in the server-side
 
    # Example 1: rename the categories and change the reference with re-ordering
      # print out the levels of the initial vector
      ds.levels(x= "D$PM_BMI_CATEGORICAL",
                datasources = connections)

      # define a vector with the new levels and recode the initial levels
      newNames <- c("normal", "overweight", "obesity")
      ds.recodeLevels(x = "D$PM_BMI_CATEGORICAL",
                      newCategories = newNames,
                      newobj = "bmi_new",
                      datasources = connections)

      # print out the levels of the new vector
      ds.levels(x = "bmi_new",
                datasources = connections)

      # Set the reference to "obesity" without changing the order (default)
      ds.changeRefGroup(x = "bmi_new",
                        ref = "obesity",
                        newobj = "bmi_ob",
                        datasources = connections)

      # print out the levels; the first listed level (i.e. the reference) is now 'obesity'
      ds.levels(x = "bmi_ob",
                datasources = connections)

    # Example 2: change the reference and re-order by the reference level
      # If re-ordering is sought, the action is completed but a warning is issued
      ds.recodeLevels(x = "D$PM_BMI_CATEGORICAL",
                      newCategories = newNames,
                      newobj = "bmi_new",
                     datasources = connections)
      ds.changeRefGroup(x = "bmi_new",
                        ref = "obesity",
                        newobj = "bmi_ob",
                        reorderByRef = TRUE,
                        datasources = connections)

           
  # Clear the Datashield R sessions and logout
  datashield.logout(connections) 

## End(Not run)

Description

Retrieves the class of an R object. This function is similar to the R function class.

Usage

ds.class(x = NULL, datasources = NULL)

Arguments

Details

Same as the native R function class.

Server function called: classDS

Value

ds.class returns the type of the R object.

Author(s)

DataSHIELD Development Team

See Also

ds.exists to verify if an object is defined (exists) on the server-side.

Examples

## Not run: 

  ## 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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 

  # Getting the class of the R objects stored in the server-side
  ds.class(x = "D", #whole dataset
           datasources = connections[1]) #only the first server ("study1") is used

  ds.class(x = "D$LAB_TSC", #select a variable
           datasources = connections[1]) #only the first server ("study1") is used
           
  # Clear the Datashield R sessions and logout
  datashield.logout(connections) 

## End(Not run)

Description

Retrieves column names of an R object on the server-side. This function is similar to R function colnames.

Usage

ds.colnames(x = NULL, datasources = NULL)

Arguments

Details

The input is restricted to the object of type data.frame or matrix.

Server function called: colnamesDS

Value

ds.colnames returns the column names of the specified server-side data frame or matrix.

Author(s)

DataSHIELD Development Team

See Also

ds.dim to obtain the dimensions of a matrix or a data frame.

Examples

## Not run: 

  ## 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()

  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D")

  # Getting column names of the R objects stored in the server-side
  ds.colnames(x = "D",
              datasources = connections[1]) #only the first server ("study1") is used
  # Clear the Datashield R sessions and logout
  datashield.logout(connections)

## End(Not run)

Description

Selects complete cases of a data frame, matrix or vector that contain missing values.

Usage

ds.completeCases(x1 = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

In the case of a data frame or matrix, ds.completeCases deletes all rows containing one or more missing values. However ds.completeCases in vectors only deletes the observation recorded as NA.

Server function called: completeCasesDS

Value

ds.completeCases generates a modified data frame, matrix or vector from which all rows containing at least one NA have been deleted. The output object is stored on the server-side. Only two validity messages are returned to the client-side indicating the name of the newobj that has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 

  # Select complete cases from different R objects

  ds.completeCases(x1 = "D", #data frames in the Opal servers 
                             #(see above the connection to the Opal servers)
                   newobj = "D.completeCases", # name for the output object 
                                               # that is stored in the Opal servers
                   datasources = connections)  # All Opal servers are used 
                                               # (see above the connection to the Opal servers)
                 
  ds.completeCases(x1 = "D$LAB_TSC", #vector (variable) of the data frames in the Opal servers 
                                     #(see above the connection to the Opal servers)
                   newobj = "LAB_TSC.completeCases", #name for the output variable 
                                                     #that is stored in the Opal servers
                   datasources = connections[2]) #only the second Opal server is used ("study2")
                   
  # Clear the Datashield R sessions and logout
  datashield.logout(connections) 
  
## End(Not run)

Description

It generates a contour plot of the pooled data or one plot for each dataset on the client-side.

Usage

ds.contourPlot(
  x = NULL,
  y = NULL,
  type = "combine",
  show = "all",
  numints = 20,
  method = "smallCellsRule",
  k = 3,
  noise = 0.25,
  datasources = NULL
)

Arguments

Details

The ds.contourPlot function first generates a density grid and uses it to plot the graph. The cells of the grid density matrix that hold a count of less than the filter set by DataSHIELD (usually 5) are considered invalid and turned into 0 to avoid potential disclosure. A message is printed to inform the user about the number of invalid cells.

The ranges returned by each study and used in the process of getting the grid density matrix are not the exact minimum and maximum values but rather close approximates of the real minimum and maximum value. This was done to reduce the risk of potential disclosure.

In the k parameter the user can choose any value for k equal to or greater than the pre-specified threshold used as a disclosure control for this method and lower than the number of observations minus the value of this threshold. k default value is 3 (we suggest k to be equal to, or bigger than, 3). Note that the function fails if the user uses the default value but the study has set a bigger threshold. The value of k is used only if the argument method is set to 'deterministic'. Any value of k is ignored if the argument method is set to 'probabilistic' or 'smallCellsRule'.

In noise any value of noise is ignored if the argument method is set to 'deterministic' or 'smallCellsRule'. The user can choose any value for noise equal to or greater than the pre-specified threshold 'nfilter.noise'. Default noise value is 0.25. The added noise follows a normal distribution with zero mean and variance equal to a percentage of the initial variance of each input variable.

Server functions called: heatmapPlotDS, rangeDS and densityGridDS

Value

ds.contourPlot returns a contour plot to the client-side.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 

  ## 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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 
  
  # Generating contour plots

  ds.contourPlot(x = "D$LAB_TSC",
                 y = "D$LAB_HDL",
                 type = "combine", 
                 show = "all",
                 numints = 20,
                 method = "smallCellsRule",  
                 k = 3, 
                 noise = 0.25,
                 datasources = connections)

  # clear the Datashield R sessions and logout
  datashield.logout(connections)


## End(Not run)

Description

This function calculates the correlation of two variables or the correlation matrix for the variables of an input data frame.

Usage

ds.cor(x = NULL, y = NULL, type = "split", datasources = NULL)

Arguments

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 the user to decide the 'relevance' of the correlation based on the number of complete cases included in the correlation calculations.

If the argument y is not NULL, the dimensions of the object have to be compatible with the argument x.

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 type is set to '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 '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: corDS

Value

ds.cor returns a list containing the number of missing values in each variable, 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 with a level having fewer counts than the pre-specified 'nfilter.tab' threshold.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 

## 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()
  
  # Log onto the remote Opal training servers
  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", 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", datasources = connections)

  # clear the Datashield R sessions and logout
  datashield.logout(connections)


## End(Not run)

Description

This is similar to the R stats function cor.test.

Usage

ds.corTest(
  x = NULL,
  y = NULL,
  method = "pearson",
  exact = NULL,
  conf.level = 0.95,
  type = "split",
  datasources = NULL
)

Arguments

Details

Runs a two-sided correlation test between paired samples, using one of Pearson's product moment correlation coefficient, Kendall's tau or Spearman's rho. Server function called: corTestDS

Value

ds.corTest returns to the client-side the results of the correlation test.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 

 ## 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") 
  
  # test for correlation
  ds.corTest(x = "D$LAB_TSC",
             y = "D$LAB_HDL",
             datasources = connections[1]) #Only first server is used ("study1")
                
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

This function calculates the covariance of two variables or the variance-covariance matrix for the variables of an input data frame.

Usage

ds.cov(
  x = NULL,
  y = NULL,
  naAction = "pairwise.complete",
  type = "split",
  datasources = NULL
)

Arguments

Details

In addition to computing covariances; this function produces a table outlining the number of complete cases and a table outlining the number of missing values to allow for the user to decide about the 'relevance' of the covariance based on the number of complete cases included in the covariance calculations.

If the argument y is not NULL, the dimensions of the object have to be compatible with the argument x.

If naAction is set to '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 covariances. If naAction is set to '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 covariances of those pairs.

If type is set to 'split' (default), the covariance of two variables or the variance-covariance 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 'combine', the pooled covariance, the total number of complete cases and the total number of missing values aggregated from all the involved studies, are returned.

Server function called: covDS

Value

ds.cov returns a list containing the number of missing values in each variable, the number of missing values casewise or pairwise depending on the argument naAction, the covariance matrix, the number of used complete cases and an error message which indicates whether or not the input variables pass the 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 with a level having fewer counts than the pre-specified 'nfilter.tab' threshold. If any of the input variables do not pass the disclosure controls then all the output values are replaced with NAs. If all the variables are valid and pass the controls, then the output matrices are returned and also an error message is returned but it is replaced by NA.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 

## 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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 
  
  # Calculate the covariance between two vectors
  ds.assign(newobj='labhdl', toAssign='D$LAB_HDL', datasources = connections)
  ds.assign(newobj='labtsc', toAssign='D$LAB_TSC', datasources = connections)
  ds.assign(newobj='gender', toAssign='D$GENDER', datasources = connections)
  ds.cov(x = 'labhdl',
         y = 'labtsc',
         naAction = 'pairwise.complete',
         type = 'combine',
         datasources = connections)
  ds.cov(x = 'labhdl',
         y = 'gender',
         naAction = 'pairwise.complete',
         type = 'combine',
         datasources = connections[1]) #only the first Opal server is used ("study1")

  # clear the Datashield R sessions and logout
  datashield.logout(connections)


## End(Not run)

Description

Creates a data frame from its elemental components: pre-existing data frames, single variables or matrices.

Usage

ds.dataFrame(
  x = NULL,
  row.names = NULL,
  check.rows = FALSE,
  check.names = TRUE,
  stringsAsFactors = TRUE,
  completeCases = FALSE,
  DataSHIELD.checks = FALSE,
  newobj = NULL,
  datasources = NULL,
  notify.of.progress = FALSE
)

Arguments

Details

It creates a data frame by combining pre-existing data frames, matrices or variables.

The length of all component variables and the number of rows of the data frames or matrices must be the same. The output data frame will have the same number of rows.

Server functions called: classDS, colnamesDS, dataFrameDS

Value

ds.dataFrame returns the object specified by the newobj argument which is written to the serverside. Also, two validity messages are returned to the client-side indicating the name of the newobj that has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 

  ## 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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 
  
  # Create a new data frame
  ds.dataFrame(x = c("D$LAB_TSC","D$GENDER","D$PM_BMI_CATEGORICAL"),
               row.names = NULL,
               check.rows = FALSE,
               check.names = TRUE,
               stringsAsFactors = TRUE, #character variables are converted to a factor 
               completeCases = TRUE, #only rows with not missing values are selected
               DataSHIELD.checks = FALSE,
               newobj = "df1",
               datasources = connections[1], #only the first Opal server is used ("study1")
               notify.of.progress = FALSE)


  # Clear the Datashield R sessions and logout
  datashield.logout(connections) 

## End(Not run)

Description

Adds extra columns with missing values in a data frame on the server-side.

Usage

ds.dataFrameFill(df.name = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

This function checks if the input data frames have the same variables (i.e. the same column names) in all of the used studies. When a study does not have some of the variables, the function generates those variables as vectors of missing values and combines them as columns to the input data frame. If any of the generated variables are of class factor, the function assigns to those the corresponding levels of the factors given from the studies where such factors exist.

Server function called: dataFrameFillDS

Value

ds.dataFrameFill returns the object specified by the newobj argument which is written to the server-side. Also, two validity messages are returned to the client-side indicating the name of the newobj that has been created in each data source and if it is in a valid form.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Examples

## Not run: 

  ## 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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 
  
  # Create two data frames with one different column
  
  ds.dataFrame(x = c("D$LAB_TSC","D$LAB_TRIG","D$LAB_HDL",
                     "D$LAB_GLUC_ADJUSTED","D$PM_BMI_CONTINUOUS"),
               newobj = "df1",
               datasources = connections[1])
               
  ds.dataFrame(x = c("D$LAB_TSC","D$LAB_TRIG","D$LAB_HDL","D$LAB_GLUC_ADJUSTED"),
               newobj = "df1",
               datasources = connections[2])
  
  # Fill the data frame with NA columns
  
  ds.dataFrameFill(df.name = "df1",
                   newobj = "D.Fill",
                   datasources = connections[c(1,2)]) # Two servers are used


  # Clear the Datashield R sessions and logout
  datashield.logout(connections) 

## End(Not run)

Description

Sorts a data frame using a specified sort key.

Usage

ds.dataFrameSort(
  df.name = NULL,
  sort.key.name = NULL,
  sort.descending = FALSE,
  sort.method = "default",
  newobj = NULL,
  datasources = NULL
)

Arguments

Details

It sorts a specified data.frame on the serverside using a sort key also on the server-side. The sort key can either sit in the data.frame or outside it. The sort key can be forced to be interpreted as alphabetic or numeric.

When a numeric vector is sorted alphabetically, the order can look confusing. For example, if we have a numeric vector to sort:
vector.2.sort = c(-192, 76, 841, NA, 1670, 163, 147, 101, -112, -231, -9, 119, 112, NA)

When sorting numbers in an ascending (default) manner, the largest negative numbers get ordered first leading up to the largest positive numbers and finally (by default in R) NAs being positioned at the end of the vector:
numeric.sort = c(-231, -192, -112, -9, 76, 101, 112, 119, 147, 163, 841, 1670, NA, NA)

Instead, if the same vector is sorted alphabetically the the resultant vector is:

alphabetic.sort = (-112, -192, -231, -9, 101, 112, 119, 147, 163, 1670, 76, 841, NA, NA)

Server function called: dataFrameSortDS.

Value

ds.dataFrameSort returns the sorted data frame is written to the server-side. Also, two validity messages are returned to the client-side indicating the name of the newobj which has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 
  ## 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") 
  
  # Sorting the data frame
  ds.dataFrameSort(df.name = "D",
                   sort.key.name = "D$LAB_TSC",
                   sort.descending = TRUE,
                   sort.method = "numeric",
                   newobj = "df.sort",
                   datasources = connections[1]) #only the first Opal server is used ("study1")
                   
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

Subsets a data frame by rows and/or by columns.

Usage

ds.dataFrameSubset(
  df.name = NULL,
  V1.name = NULL,
  V2.name = NULL,
  Boolean.operator = NULL,
  keep.cols = NULL,
  rm.cols = NULL,
  keep.NAs = NULL,
  newobj = NULL,
  datasources = NULL,
  notify.of.progress = FALSE
)

Arguments

Details

Subset a pre-existing data frame using the standard set of Boolean operators (==, !=, >, >=, <, <=). The subsetting is made by rows, but it is also possible to select columns to keep or remove. Instead, if you wish to keep all rows in the subset (e.g. if the primary plan is to subset by columns and not by rows) the V1.name and V2.name parameters can be used to specify a vector of the same length as the data frame to be subsetted in each study in which every element is 1 and there are no missing values. For more information see the example 2 below.

Server functions called: dataFrameSubsetDS1 and dataFrameSubsetDS2

Value

ds.dataFrameSubset returns the object specified by the newobj argument which is written to the server-side. Also, two validity messages are returned to the client-side indicating the name of the newobj which has been created in each data source and if it is in a valid form.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 

 ## 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") 
  
  # Subsetting a data frame
  #Example 1: Include some rows and all columns in the subset
  ds.dataFrameSubset(df.name = "D",
                     V1.name = "D$LAB_TSC",
                     V2.name = "D$LAB_TRIG",
                     Boolean.operator = ">",
                     keep.cols = NULL, #All columns are included in the new subset
                     rm.cols = NULL, #All columns are included in the new subset
                     keep.NAs = FALSE, #All rows with NAs are removed
                     newobj = "new.subset",
                     datasources = connections[1],#only the first server is used ("study1")
                     notify.of.progress = FALSE)
  #Example 2: Include all rows and some columns in the new subset
    #Select complete cases (rows without NA)
    ds.completeCases(x1 = "D",
                     newobj = "complet",
                     datasources = connections)
    #Create a vector with all ones
    ds.make(toAssign = "complet$LAB_TSC-complet$LAB_TSC+1",
            newobj = "ONES",
            datasources = connections) 
    #Subset the data
    ds.dataFrameSubset(df.name = "complet",
                       V1.name = "ONES",
                       V2.name = "ONES",
                       Boolean.operator = "==",
                       keep.cols = c(1:4,10), #only columns 1, 2, 3, 4 and 10 are selected
                       rm.cols = NULL,
                       keep.NAs = FALSE,
                       newobj = "subset.all.rows",
                       datasources = connections, #all servers are used
                       notify.of.progress = FALSE)                
                     
  # Clear the Datashield R sessions and logout                 
  datashield.logout(connections) 
  

## End(Not run)

Description

This function generates a grid density object which can then be used to produced heatmap or contour plots.

Usage

ds.densityGrid(
  x = NULL,
  y = NULL,
  numints = 20,
  type = "combine",
  datasources = NULL
)

Arguments

Details

The cells with a count > 0 and < nfilter.tab are considered invalid and the count is set to 0.

In DataSHIELD the user does not have access to the micro-data so and extreme values such as the maximum and the minimum are potentially non-disclosive so this function does not allow for the user to set the limits of the density grid and the minimum and maximum values of the x and y vectors. These elements are set by the server-side function densityGridDS to 'valid' values (i.e. values that do not lead to leakage of micro-data to the user).

Server function called: densityGridDS

Value

ds.densityGrid returns a grid density matrix.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 

 ## 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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 
 
  #Generate the density grid
  # Example1: generate a combined grid density object (default)
  ds.densityGrid(x="D$LAB_TSC",
                 y="D$LAB_HDL",
                 datasources = connections)#all opal servers are used

  # Example2: generate a grid density object for each study separately
  ds.densityGrid(x="D$LAB_TSC",
                 y="D$LAB_HDL",
                 type="split",
                 datasources = connections[1])#only the first Opal server is used ("study1")

  # Example3: generate a grid density object where the number of intervals is set to 15, for
  #           each study separately
  ds.densityGrid(x="D$LAB_TSC",
                 y="D$LAB_HDL",
                 type="split",
                 numints=15,
                 datasources = connections)

  # clear the Datashield R sessions and logout
  datashield.logout(connections)


## End(Not run)

Description

Gives the dimensions of an R object on the server-side. This function is similar to R function dim.

Usage

ds.dim(x = NULL, type = "both", checks = FALSE, datasources = NULL)

Arguments

Details

The function returns the dimension of the server-side input object (e.g. array, matrix or data frame) from every single study and the pooled dimension of the object by summing up the individual dimensions returned from each study.

In checks parameter is suggested that checks should only be undertaken once the function call has failed.

Server function called: dimDS

Value

ds.dim retrieves to the client-side the dimension of the object in the form of a vector where the first element indicates the number of rows and the second element indicates the number of columns.

Author(s)

DataSHIELD Development Team

See Also

ds.dataFrame to generate a table of the type data frame.

ds.changeRefGroup to change the reference level of a factor.

ds.colnames to obtain the column names of a matrix or a data frame

ds.asMatrix to coerce an object into a matrix type.

ds.length to obtain the size of a vector.

Examples

## Not run: 

  ## 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") 
  

  # Calculate the dimension
  ds.dim(x="D", 
         type="combine", #global dimension
         checks = FALSE,
         datasources = connections)#all opal servers are used
  ds.dim(x="D",
         type = "both",#separate dimension for each study
                       #and the pooled dimension (default) 
         checks = FALSE,
         datasources = connections)#all opal servers are used
  ds.dim(x="D", 
         type="split", #separate dimension for each study
         checks = FALSE,
         datasources = connections[1])#only the first opal server is used ("study1")

  # clear the Datashield R sessions and logout
  datashield.logout(connections)


## End(Not run)

Description

Creates a data.frame, matrix or tibble on the serverside that is equivalent to that same data.frame, matrix or tibble (DMT) on the clientside.

Usage

ds.dmtC2S(dfdata = NA, newobj = NULL, datasources = NULL)

Arguments

Details

ds.dmtC2S calls assign function dmtC2SDS. To keep the function simple (though less flexible), a number of the parameters specifying the DMT to be generated on the serverside are fixed by the characteristics of the DMT to be copied rather than explicitly specifying them as selected arguments. In consequence, they have been removed from the list of arguments and are instead given invariant values in the first few lines of code. These include: from="clientside.dmt", nrows.scalar=NULL, ncols.scalar=NULL, byrow = FALSE. The specific value "clientside.dmt" for the argument <from> simply means that the required information is generated from the characteristics of a clientside DMT. The <nrows.scalar> and <ncols.scalar> are fixed empirically by the number of rows and columns of the DMT to be copied. <byrow> specifies writing the serverside DMT by columns or by rows and this is defaulted to byrow=FALSE i.e. "by column".

Value

the object specified by the <newobj> argument (or default name "dmt.copied.C2S") which is written as a data.frame/matrix/tibble to the serverside.

Author(s)

Paul Burton for DataSHIELD Development Team - 3rd June, 2021

Description

This function is based on the native R function elspline from the lspline package. This function computes the basis of piecewise-linear spline such that, depending on the argument marginal, the coefficients can be interpreted as (1) slopes of consecutive spline segments, or (2) slope change at consecutive knots.

Usage

ds.elspline(
  x,
  n,
  marginal = FALSE,
  names = NULL,
  newobj = NULL,
  datasources = NULL
)

Arguments

Details

If marginal is FALSE (default) the coefficients of the spline correspond to slopes of the consecutive segments. If it is TRUE the first coefficient correspond to the slope of the first segment. The consecutive coefficients correspond to the change in slope as compared to the previous segment. Function elspline wraps lspline and computes the knot positions such that they cut the range of x into n equal-width intervals.

Value

an object of class "lspline" and "matrix", which its name is specified by the newobj argument (or its default name "elspline.newobj"), is assigned on the serverside.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Description

Looks if an R object of the given name is defined on the server-side. This function is similar to the R function exists.

Usage

ds.exists(x = NULL, datasources = NULL)

Arguments

Details

In DataSHIELD it is not possible to see the data on the servers of the collaborating studies. It is only possible to get summaries of objects stored on the server-side. It is however important to know if an object is defined (i.e. exists) on the server-side. This function checks if an object does exist on the server-side.

Server function called: exists

Value

ds.exists returns a logical object. TRUE if the object is on the server-side and FALSE otherwise.

Author(s)

DataSHIELD Development Team

See Also

ds.class to check the type of an object.

ds.length to check the length of an object.

ds.dim to check the dimension of an object.

Examples

## Not run: 

  ## 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") 
  
  # Check if the object exist in the server-side
  ds.exists(x = "D", 
            datasources = connections) #All opal servers are used
  ds.exists(x = "D", 
            datasources = connections[1]) #Only the first Opal server is used (study1)
            
  # clear the Datashield R sessions and logout
  datashield.logout(connections)


## End(Not run)

Description

Computes the exponential values for a specified numeric vector. This function is similar to R function exp.

Usage

ds.exp(x = NULL, newobj = NULL, datasources = NULL)

Arguments

Details

Server function called: exp.

Value

ds.exp returns a vector for each study of the exponential values for the numeric vector specified in the argument x. The created vectors are stored in the server-side.

Author(s)

DataSHIELD Development Team

Examples

## Not run: 

  ## 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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 
  
  # compute exponential function of the 'PM_BMI_CONTINUOUS' variable
  ds.exp(x = "D$PM_BMI_CONTINUOUS",
         newobj = "exp.PM_BMI_CONTINUOUS",
         datasources = connections[1]) #only the first Opal server is used (study1)

  # clear the Datashield R sessions and logout
  datashield.logout(connections) 


## End(Not run)

Description

Takes the global ranks and quantiles held in the serverside data data frame that is written by ranksSecureDS4 and named as specified by the argument (<output.ranks.df>) and converts these values into a series of quantile values that identify, for example, which value of V2BR across all of the studies corresponds to the median or to the 95 indication in which study the V2BR corresponding to a particular quantile falls and, in fact, the relevant value may fall in more than one study and may appear multiple times in any one study. Finally, the output data frame containing this information is written to the clientside and to the serverside at each study separately.

Usage

ds.extractQuantiles(
  extract.quantiles,
  extract.summary.output.ranks.df,
  extract.ranks.sort.by,
  extract.rm.residual.objects,
  extract.datasources = NULL
)

Arguments

Details

ds.extractQuantiles is a clientside function which should usually be called from within the clientside function ds.ranksSecure.If you try to call ds.extractQuantiles directly(i.e. not by running ds.ranksSecure) you are almost certainly going to have to set up quite a few vectors and scalars that are normally set by ds.ranksSecure and this is likely to be difficult. ds.extractQuantiles itself calls two serverside functions extractQuantilesDS1 and extractQuantilesDS2. For more details about the cluster of functions that collectively enable secure global ranking and estimation of global quantiles see the associated document entitled "secure.global.ranking.docx". In particular this explains how ds.extractQuantiles works. Also see the header file for ds.ranksSecure.

Value

the final main output of ds.extractQuantiles is a data frame object named "final.quantile.df". This contains two vectors. The first named "evaluation.quantiles" lists the full set of quantiles you have requested for evaluation as specified by the argument "quantiles.for.estimation" in ds.ranksSecure and explained in more detail above under the information for the argument "extract.quantiles" in this function. The second vector is called "final.quantile.vector" which details the values of V2BR that correspond to the evaluation quantiles in vector 1. The information in the data frame "final.quantile.df" is generic: there is no information identifying in which study each value of V2BR falls. This data frame is written to the clientside (as it is non-disclosive) and is also copied to the serverside in every study. This means it is easily accessible from anywhere in the DataSHIELD environment. For more details see the associated document entitled "secure.global.ranking.docx".

Author(s)

Paul Burton 11th November, 2021

Description

Draws a forestplot of the coefficients for Study-Level Meta-Analysis performed with DataSHIELD

Usage

ds.forestplot(mod, variable = NULL, method = "ML", layout = "JAMA")

Arguments

Value

Results a foresplot object created with 'meta::forest'.

Examples

## Not run: 
  # Run a logistic regression
  
  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()
  
  # Log onto the remote Opal training servers
  connections <- DSI::datashield.login(logins = logindata, assign = TRUE, symbol = "D") 
  
  # Fit the logistic regression model

  mod <- ds.glmSLMA(formula = "DIS_DIAB~GENDER+PM_BMI_CONTINUOUS+LAB_HDL",
                data = "D",
                family = "binomial",
                datasources = connections)
                
  # Plot the results of the model
  ds.forestplot(mod)

## End(Not run)

Description

This function calls the gamlssDS that is a wrapper function from the gamlss R package. The function returns an object of class "gamlss", which is a generalized additive model for location, scale and shape (GAMLSS). The function also saves the residuals as an object on the server-side with a name specified by the newobj argument. In addition, if the argument centiles is set to TRUE, the function calls the centiles function from the gamlss package and returns the sample percentages below each centile curve.

Usage

ds.gamlss(
  formula = NULL,
  sigma.formula = "~1",
  nu.formula = "~1",
  tau.formula = "~1",
  family = "NO()",
  data = NULL,
  method = "RS",
  mu.fix = FALSE,
  sigma.fix = FALSE,
  nu.fix = FALSE,
  tau.fix = FALSE,
  control = c(0.001, 20, 1, 1, 1, 1, Inf),
  i.control = c(0.001, 50, 30, 0.001),
  centiles = FALSE,
  xvar = NULL,
  newobj = NULL,
  datasources = NULL
)

Arguments