ds.matrixDiag: Calculates matrix diagonals in the server-side

View source: R/ds.matrixDiag.R

ds.matrixDiagR Documentation

Calculates matrix diagonals in the server-side

Description

Extracts the diagonal vector from a square matrix or creates a diagonal matrix based on a vector or a scalar value on the server-side.

Usage

ds.matrixDiag(
  x1 = NULL,
  aim = NULL,
  nrows.scalar = NULL,
  newobj = NULL,
  datasources = NULL
)

Arguments

x1

a character string specifying the name of a server-side scalar or vector. Also, a numeric value or vector specified from the client-side can be speficied. This argument depends on the value specified in aim. For more information see Details.

aim

a character string specifying the behaviour of the function. This can be set as: "serverside.vector.2.matrix", "serverside.scalar.2.matrix", "serverside.matrix.2.vector", "clientside.vector.2.matrix" or "clientside.scalar.2.matrix". For more information see Details.

nrows.scalar

an integer specifying the dimensions of the matrix note that the matrix is square (same number of rows and columns). If this argument is not specified the matrix dimensions are defined by the length of the vector. For more information see Details.

newobj

a character string that provides the name for the output variable that is stored on the data servers. Default matrixdiag.newobj.

datasources

a list of DSConnection-class objects obtained after login. If the datasources argument is not specified the default set of connections will be used: see datashield.connections_default.

Details

The function behaviour is different depending on the value specified in the aim argument:
(1) If aim = "serverside.vector.2.matrix" the function takes a server-side vector and writes out a square matrix with the vector as its diagonal and all off-diagonal values = 0. The dimensions of the output matrix are determined by the length of the vector. If the vector length is k, the output matrix has k rows and k columns.
(2) If aim = "serverside.scalar.2.matrix" the function takes a server-side scalar and writes out a square matrix with all diagonal values equal to the value of the scalar and all off-diagonal values = 0. The dimensions of the square matrix are determined by the value of the nrows.scalar argument.
(3) If aim = "serverside.matrix.2.vector" the function takes a square server-side matrix and extracts its diagonal values as a vector which is written to the server-side.
(4) If aim = "clientside.vector.2.matrix" the function takes a vector specified on the client-side and writes out a square matrix to the server-side with the vector as its diagonal and all off-diagonal values = 0. The dimensions of the output matrix are determined by the length of the vector.
(5) If aim = "clientside.scalar.2.matrix" the function takes a scalar specified on the client-side and writes out a square matrix with all diagonal values equal to the value of the scalar. The dimensions of the square matrix are determined by the value of the nrows.scalar argument.

If x1 is a vector and the nrows.scalar is set as k, the vector will be used repeatedly to fill up the diagonal. For example, the vector is of length 7 and nrows.scalar = 18, a square diagonal matrix with 18 rows and 18 columns will be created.

Server function called: matrixDiagDS

Value

ds.matrixDiag returns to the server-side the square matrix diagonal. Also, two validity messages are returned indicating whether the new object has been created in each data source and if so whether 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") 
  
  #Example 1: Create a square matrix with the server-side vector as its diagonal
  #and all the other values = 0
  
  # Create a vector in the server-side 
  
  ds.rUnif(samp.size = 9,
           min = -10.5,
           max = 10.5,
           newobj = "ss.vector.9",
           seed.as.integer = 5575,
           force.output.to.k.decimal.places = 0,
           datasources = connections)
   
            
  #Calculate the diagonal of the matrix
  
  ds.matrixDiag(x1 = "ss.vector.9",
                aim = "serverside.vector.2.matrix",
                nrows.scalar = NULL,
                newobj = "matrix.diag1",
                datasources = connections)
                
  #Example 2: Create a square matrix with the server-side scalar as all diagonal values 
  and all the other values = 0
  
  #Create a scalar in the server-side
  
  ds.rUnif(samp.size = 1,
           min = -10.5,
           max = 10.5,
           newobj = "ss.scalar",
           seed.as.integer = 5575,
           force.output.to.k.decimal.places = 0,
           datasources = connections)
           
  #Calculate the diagonal of the matrix
           
 ds.matrixDiag(x1 = "ss.scalar",
               aim = "serverside.scalar.2.matrix",
               nrows.scalar = 4,
               newobj = "matrix.diag2",
               datasources = connections)
               
 #Example 3: Create a vector that contains the server-side matrix diagonal values
 
 #Create a matrix in the server-side
 
 ds.matrix(mdata = 10,
           from = "clientside.scalar",
           nrows.scalar = 3,
           ncols.scalar = 8,
           newobj = "ss.matrix",
           datasources = connections)
           
 #Extract the diagonal of the matrix
     
 ds.matrixDiag(x1 = "ss.matrix",
               aim = "serverside.matrix.2.vector",
               nrows.scalar = NULL,
               newobj = "vector.diag3",
               datasources = connections)
                   
 #Example 4: Create a square matrix with the client-side vector as a diagonal
 and all the other values = 0
 
 ds.matrixDiag(x1 = c(2,6,9,10),
               aim = "clientside.vector.2.matrix",
               nrows.scalar = NULL,
               newobj = "matrix.diag4",
               datasources = connections)
               
 #Example 5: Create a square matrix with the client-side scalar as all diagonal values 
 and all the other values = 0
 
 ds.matrixDiag(x1 = 4,
               aim = "clientside.scalar.2.matrix",
               nrows.scalar = 5,
               newobj = "matrix.diag5",
               datasources = connections)
  
  
  # clear the Datashield R sessions and logout
  datashield.logout(connections)

## End(Not run)

datashield/dsBaseClient documentation built on May 16, 2023, 10:19 p.m.