ds.matrix {dsBaseClient}R Documentation

ds.matrix calling assign function matrixDS

Description

Creates a matrix A on the serverside

Usage

ds.matrix(mdata = NA, from = "clientside.scalar",
  nrows.scalar = NULL, ncols.scalar = NULL, byrow = FALSE,
  dimnames = NULL, newobj = NULL, datasources = NULL)

Arguments

mdata

specifies the elements of the matrix to be created. If it is a vector it should usually be the same length as the total number of elements in the matrix and these will fill the matrix column by column or row by row depending whether the argument <byrow> is FALSE (default) or TRUE. If the mdata vector is not the same length as the total number of elements in the matrix to be created, the values in mdata will be used repeatedly until all elements in the matrix are full. If mdata is a scalar, all elements in the matrix will take that value. The <mdata> argument can be specified either as a character string specifying the name of a serverside scalar or vector, or a numeric value (or numeric object) representing a scalar specified from the clientside. Zeros, negative values and NAs are all allowed.

from

a character string specifying the source and nature of <mdata>. Can only take values "serverside.vector", "serverside.scalar" or "clientside.scalar" This argument must be specified - NULL values not permitted. Defaults to "clientside.scalar"

nrows.scalar

specifies the number of rows in the matrix to be created. It can be a character string specifying the name of a serverside scalar: e.g. if a serverside scalar named "ss.scalar" exists and holds the value 23, then by specifying nrows.scalar="ss.scalar", the matrix to be created will have 23 rows. Alternatively it can be specified as a numeric value (or numeric object) representing a scalar specified from the clientside: e.g. nrows.scalar=14 or equivalently scalar.value<- 14; nrows.scalar=scalar.value. This will create a matrix with 14 rows. A zero, negative, NULL or missing value is not permitted

ncols.scalar

specifies the number of columns in the matrix to be created. It can be a character string specifying the name of a serverside scalar: e.g. if a serverside scalar named "ss.scalar" exists and holds the value 23, then by specifying ncols.scalar="ss.scalar", the matrix to be created will have 23 columns. Alternatively it can be specified as a numeric value (or numeric object) representing a scalar specified from the clientside: e.g. ncols.scalar=14 or equivalently scalar.value<- 14; ncols.scalar=scalar.value. This will create a matrix with 14 columns. A zero, negative, NULL or missing value is not permitted

byrow

a logical value specifying whether, when <mdata> is a vector, the matrix created should be filled row by row (byrow=TRUE) i.e. starting at the first element of first row, filling that row and then moving to the first element of the second row and filling that row etc until all elements of the matrix are full or column by column (byrow=FALSE). Default = FALSE.

dimnames

A dimnames attribute for the matrix: NULL or a list of length 2 giving the row and column names respectively. An empty list is treated as NULL, and a list of length one as row names only.

newobj

A character string specifying the name of the matrix to which the output is to be written. If no <newobj> argument is specified or it is NULL the output matrix names defaults to "new_matrix"

datasources

specifies the particular opal object(s) to use. If the <datasources> argument is not specified the default set of opals will be used. The default opals are called default.opals and the default can be set using the function ds.setDefaultOpals. If the <datasources> is to be specified, it should be set without inverted commas: e.g. datasources=opals.em or datasources=default.opals. If you wish to apply the function solely to e.g. the second opal server in a set of three, the argument can be specified as: e.g. datasources=opals.em[2]. If you wish to specify the first and third opal servers in a set you specify: e.g. datasources=opals.em[c(1,3)]

Details

Similar to the matrix() function in native R. Creates a matrix with dimensions specified by <nrows.scalar> and <ncols.scalar> arguments and assigns the values of all its elements based on the <mdata> argument

Value

the object specified by the <newobj> argument (or default name "new_matrix") which is written to the serverside. In addition, two validity messages are returned indicating whether <newobj> has been created in each data source and if so whether it is in a valid form. If its form is not valid in at least one study - e.g. because a disclosure trap was tripped and creation of the full output object was blocked - ds.matrix also returns any studysideMessages that can explain the error in creating the full output object. As well as appearing on the screen at run time,if you wish to see the relevant studysideMessages at a later date you can use the ds.message function. If you type ds.message("newobj") it will print out the relevant studysideMessage from any datasource in which there was an error in creating <newobj> and a studysideMessage was saved. If there was no error and <newobj> was created without problems no studysideMessage will have been saved and ds.message("newobj") will return the message: "ALL OK: there are no studysideMessage(s) on this datasource".

Author(s)

Paul Burton for DataSHIELD Development Team

Examples

## Not run: 

ds.matrix(mdata=-13,from="clientside.scalar", nrows.scalar=3,ncols.scalar=8,newobj="cs.block")

ds.matrix(NA,from="clientside.scalar", nrows.scalar=4,ncols.scalar=5,newobj="cs.block.NA")

clientside.input.scalar<-837
ds.matrix(clientside.input.scalar,from="clientside.scalar", nrows.scalar=7,ncols.scalar=3,
          newobj="cs.block.input")

clientside.input.nrows.scalar<-11
ds.matrix(clientside.input.scalar,from="clientside.scalar",
          nrows.scalar=clientside.input.nrows.scalar,ncols.scalar=3,
          newobj="cs.block.input.nrows")

ds.rUnif(samp.size=1,min=0.5,max=10.5,newobj="block.scalar",seed.as.integer=761728,
           force.output.to.k.decimal.places = 0)

ds.matrix("block.scalar",from="serverside.scalar", nrows.scalar=9,ncols.scalar=7,
          newobj="ss.block")

ds.make("log(block.scalar*(-1))","block.scalar.NA")

ds.matrix("block.scalar.NA",from="serverside.scalar", nrows.scalar=9,ncols.scalar=7,
          newobj="ss.block.NA")

ds.matrix("block.scalar",from="serverside.scalar", nrows.scalar="block.scalar",
          ncols.scalar="block.scalar",newobj="ss.block.square")

ds.rUnif(samp.size=45,min=-10.5,max=10.5,newobj="ss.vector",seed.as.integer=8321,
           force.output.to.k.decimal.places = 0)
ds.matrix("ss.vector",from="serverside.vector", nrows.scalar=5,ncols.scalar=9,
          newobj="sv.block")

ds.rUnif(samp.size=5,min=-10.5,max=10.5,newobj="ss.vector.5",seed.as.integer=551625,
           force.output.to.k.decimal.places = 0)
ds.matrix("ss.vector.5",from="serverside.vector", nrows.scalar=5,ncols.scalar=9,
          newobj="sv.block.5")

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)
ds.matrix("ss.vector.9",from="serverside.vector", nrows.scalar=5,ncols.scalar=9,byrow=TRUE,
          newobj="sv.block.9")

ds.matrix("ss.vector.9",from="serverside.vector", nrows.scalar=5,ncols.scalar=9,
          newobj="sv.block.9.ragged")

ds.rUnif(samp.size=12,min=-10.5,max=10.5,newobj="ss.vector.12",seed.as.integer=778172,
           force.output.to.k.decimal.places = 0)

ds.matrix("ss.vector.12",from="serverside.vector", nrows.scalar=5,ncols.scalar=9,
          newobj="sv.block.12.ragged")

ds.recodeValues("ss.vector", c(-10),c(NA),newobj="ss.vector.NA")
ds.matrix("ss.vector.NA",from="serverside.vector", nrows.scalar=5,ncols.scalar=9,
          newobj="sv.block.NA")

ds.matrix("ss.vector.NA",from="serverside.vector", nrows.scalar=5,ncols.scalar=9,
          byrow=TRUE,newobj="sv.byrow.block")

ds.matrix(NA, nrows.scalar=7,ncols.scalar=6,newobj="empty.matrix")

ds.matrix("ss.vector.9",from="serverside.vector", nrows.scalar=5,ncols.scalar=9,byrow=TRUE,
dimnames=list(c("a","b","c","d","e")),newobj="sv.block.9.dimnames1")

ds.matrix("ss.vector.9",from="serverside.vector", nrows.scalar=5,ncols.scalar=9,byrow=TRUE,
dimnames=list(c("a","b","c","d","e"),c(10*(9:1))),newobj="sv.block.9.dimnames12")

#No specification of newobj
ds.matrix("ss.vector.9",from="serverside.vector", nrows.scalar=5,ncols.scalar=9,byrow=TRUE,
dimnames=list(c("a","b","c","d","e"),c(10*(9:1))))

## End(Not run)


[Package dsBaseClient version 5.0.0 ]