Title:	'DataSHIELD' Server Site Base Functions
Description:	Base 'DataSHIELD' functions for the server side. 'DataSHIELD' is a software package which allows you to do non-disclosive federated analysis on sensitive data. 'DataSHIELD' analytic functions have been designed to only share non disclosive summary statistics, with built in automated output checking based on statistical disclosure control. With data sites setting the threshold values for the automated output checks. For more details, see 'citation("dsBase")'.
Version:	6.3.3
License:	GPL-3
Depends:	R (≥ 4.0.0)
Imports:	RANN, stringr, lme4, dplyr, reshape2, polycor (≥ 0.8), splines, gamlss, gamlss.dist, mice, childsds
Suggests:	testthat
RoxygenNote:	7.3.2
Encoding:	UTF-8
NeedsCompilation:	no
Packaged:	2025-07-16 14:47:27 UTC; swheater
Author:	Paul Burton [aut], Rebecca Wilson [aut], Olly Butters [aut], Patricia Ryser-Welch [aut], Alex Westerberg [aut], Leire Abarrategui [aut], Roberto Villegas-Diaz [aut], Demetris Avraam [aut], Yannick Marcon [aut], Stuart Wheater [aut, cre]
Maintainer:	Stuart Wheater <stuart.wheater@arjuna.com>
Repository:	CRAN
Date/Publication:	2025-07-19 09:10:07 UTC

BooleDS

Description

Converts the individual elements of a vector or other object into Boolean indicators.

Usage

BooleDS(
  V1.name = NULL,
  V2.name = NULL,
  Boolean.operator.n = NULL,
  na.assign.text,
  numeric.output = TRUE
)

Arguments

Details

The function converts the input vector into Boolean indicators.

Value

the levels of the input variable.

Author(s)

DataSHIELD Development Team

Computes the absolute values of the input variable

Description

This function is similar to R function abs.

Usage

absDS(x)

Arguments

Details

The function computes the absolute values of an input numeric or integer vector.

Value

the object specified by the newobj argument of ds.abs (or default name abs.newobj) which is written to the serverside. The output object is of class numeric or integer.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Coerces an R object into class character

Description

this function is based on the native R function as.character

Usage

asCharacterDS(x.name)

Arguments

Details

See help for function as.character in native R

Value

the object specified by the newobj argument (or its default name "ascharacter.newobj") which is written to the serverside. For further details see help on the clientside function ds.asCharacter

Author(s)

Amadou Gaye, Paul Burton, Demetris Avraam for DataSHIELD Development Team

asDataMatrixDS a serverside assign function called by ds.asDataMatrix

Description

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

Usage

asDataMatrixDS(x.name)

Arguments

Details

This assign function is based on the native R function data.matrix If applied to a data.frame, the native R function as.matrix coverts all columns into character class. In contrast, if applied to a data.frame the native R function data.matrix converts the data.frame to a matrix but maintains all data columns in their original class

Value

the object specified by the <newobj> argument (or its default name "asdatamatrix.newobj") which is written to the serverside. For further details see help on the clientside function ds.asDataMatrix

Author(s)

Paul Burton for DataSHIELD Development Team

Determines the levels of the input variable in each single study

Description

This function is an aggregate DataSHIELD function that returns the levels of the input variable from each single study to the client-side function.

Usage

asFactorDS1(input.var.name = NULL)

Arguments

Details

The function encodes the input vector as factor and returns its levels in ascending order if the levels are numerical or in alphabetical order if the levels are of type character.

Value

the levels of the input variable.

Converts a numeric vector into a factor

Description

This function is an assign DataSHIELD function that converts a numeric vector into a factor type that presented as a vector or as a matrix with dummy variables.

Usage

asFactorDS2(
  input.var.name = NULL,
  all.unique.levels.transmit = NULL,
  fixed.dummy.vars = NULL,
  baseline.level = NULL
)

Arguments

Details

The functions converts the input variable into a factor which is presented as a vector if the fixed.dummy.vars is set to FALSE or as a matrix with dummy variables if the fixed.dummy.vars is set to TRUE (see the help file of ds.asFactor.b for more details).

Value

an object of class factor

Converts a numeric vector into a factor

Description

This function is an assign DataSHIELD function that coerces a numeric or character vector into a factor

Usage

asFactorSimpleDS(input.var.name = NULL)

Arguments

Details

The functions 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 factor in each study. 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. In addition, 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 object of class factor

Coerces an R object into class integer

Description

This function is based on the native R function as.integer.

Usage

asIntegerDS(x.name)

Arguments

Details

See help for function as.integer in native R, and details section in the help file of the clientside function ds.asInteger.

Value

the object specified by the <newobj> argument (or its default name "asinteger.newobj") which is written to the serverside. For further details see help on the clientside function ds.asInteger.

Author(s)

Amadou Gaye, Paul Burton, Demetris Avraam, for DataSHIELD Development Team

asListDS a serverside aggregate function called by ds.asList

Description

Coerces an R object into a list

Usage

asListDS(x.name, newobj)

Arguments

Details

Unlike most other class coercing functions this is an aggregate function rather than an assign function. This is because the datashield.assign function in the data repository deals specially with a created object (newobj) if it is of class list. Reconfiguring the function as an aggregate function works around this problem. This aggregate function is based on the native R function as.list and so additional information can be found in the help for as.list

Value

the object specified by the <newobj> argument (or its default name <x.name>.mat) which is written to the serverside. In addition, two validity messages are returned. The first confirms an output object has been created, the second states its class. The way that as.list coerces objects to list depends on the class of the object, but in general the class of the output object should usually be 'list'

Author(s)

Amadou Gaye, Paul Burton for DataSHIELD Development Team

Coerces an R object into class numeric

Description

this function is based on the native R function as.numeric

Usage

asLogicalDS(x.name)

Arguments

Details

See help for function as.logical in native R

Value

the object specified by the <newobj> argument (or its default name <x.name>.logic) which is written to the serverside. For further details see help on the clientside function ds.asLogical

Author(s)

Amadou Gaye, Paul Burton for DataSHIELD Development Team

Coerces an R object into a matrix

Description

this function is based on the native R function as.matrix

Usage

asMatrixDS(x.name)

Arguments

Details

See help for function as.matrix in native R

Value

the object specified by the <newobj> argument (or its default name <x.name>.mat) which is written to the serverside. For further details see help on the clientside function ds.asMatrix

Author(s)

Amadou Gaye, Paul Burton for DataSHIELD Development Team

Coerces an R object into class numeric

Description

This function is based on the native R function as.numeric.

Usage

asNumericDS(x.name)

Arguments

Details

See help for function as.numeric in native R, and details section in the help file of the clientside function ds.asNumeric.

Value

the object specified by the <newobj> argument (or its default name <x.name>.num) which is written to the serverside. For further details see help on the clientside function ds.asNumeric.

Author(s)

Amadou Gaye, Paul Burton, Demetris Avraam, for DataSHIELD Development Team

aucDS an aggregate function called by ds.auc

Description

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

Usage

aucDS(pred = pred, y = y)

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

Secure ranking of "V2BR" (vector to be ranked) across all sources

Description

The first key serverside function that sets up the V2BR for ranking in the client.

Usage

blackBoxDS(input.var.name = NULL, shared.seedval, synth.real.ratio, NA.manage)

Arguments

Details

Severside assign function called by ds.ranksSecure. Creates pseudo-data by using the real distribution of values in V2BR to create a large number of synthetic data with a similar distribution to the values in V2BR but with a slightly broader distribution at both ends to ensure that any extreme values in the "combined real+pseudo data vector" are all pseudo-data. Also ensures that the number of decimal places of the values in the V2BR is reflected by the number of decimal places in the pseudodata. Finally, takes the "combined real+pseudo data vector" through seven rounds of rank consistent encryption that involves algorithms themselves generated by a pseudorandom process that selects which transformation to apply and with what parameters. The encryption algorithms are the same in each study ensuring that ranks also remain consistent between studies. After encryption the encrypted "combined real+pseudo data vector" is written to the serverside as a dataframe also including other key component vectors from the first stage of the ranking procedure. 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". Also see the header file for ds.ranksSecure

Value

writes a data frame object entitled blackbox.output.df to the serverside. In each study this contains the encrypted "combined real+pseudo data vector" and a range of other key components from the first stage of the ranking procedure. For more details see the associated document entitled "secure.global.ranking.docx"

Author(s)

Paul Burton 9th November, 2021

Secure ranking of "V2BR" (vector to be ranked) across all sources

Description

The second key serverside function that prepares the global ranks of the the real data only generated in the first stage of the ranking procedure and encrypts them in preparation for generating global ranks that correspond 1 to 1 with only the real data in V2BR.

Usage

blackBoxRanksDS(input.var.name = NULL, shared.seedval)

Arguments

Details

Severside assign function called by ds.ranksSecure. It takes the global ranks currently held in sR5.df which reflect the global ranks based on the "combined real+pseudo data vector" as encrypted by blackBoxDS but with all pseudo-data stripped out. It then uses these global ranks (of the real data) as if they were a new variable to be ranked. This is then equivalent to blackBoxDS with the primary difference that no pseudo-data are needed. This is because the global ranks are fundamentally non-disclosive and so can be transferred to the clientside with no risk of disclosure. However, in order to ensure that the client cannot compare the list of global.ranks in sR4.df (after initial global ranking based on ranking of real and pseudo-data combined) with the global.ranks to be generated by blackBoxRanksDS (based solely on the real data they are processed through seven more rounds of encryption as before in blackBoxDS. In consequence the client remains unable to determine which of the original global ranks corresponded to real data and which to pseudo-data. In addition, blackBoxRanksDS does not need to determine the number of decimal places in the data because it is only applied to ranks which are assumed to be integers. 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". Also see the header file for ds.ranksSecure and the header file for blackBoxDS

Value

writes a data frame object entitled blackbox.ranks.df to the serverside. In each study this contains the encrypted global ranks and a range of other key components from the second stage (ranking of global ranks for real observations only) of the ranking procedure. For more details see the associated document entitled "secure.global.ranking.docx"

Author(s)

Paul Burton 9th November, 2021

Create the identity stats and necessary data to draw a plot on the client

Description

In order to create a non disclosive box plot, the data that is passed to the client is purely geometrical aspects of the plot, as a ggplot object contains all the data inside, only the graphical parameters are passed. There are three different cases depending if there are grouping variables. The outliers are also removed from the graphical parameters.

Usage

boxPlotGGDS(data_table, group = NULL, group2 = NULL)

Arguments

Value

list with:
-data frame Geometrical parameters (identity stats of ggplot)
-character Type of plot (single_group, double_group or no_group)

Arrange data frame to pass it to the boxplot function

Description

Arrange data frame to pass it to the boxplot function

Usage

boxPlotGG_data_TreatmentDS(table, variables, group = NULL, group2 = NULL)

Arguments

Value

data frame with the following structure:

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

Arrange vector to pass it to the boxplot function

Description

Arrange vector to pass it to the boxplot function

Usage

boxPlotGG_data_Treatment_numericDS(vector)

Arguments

Value

data frame with the following structure:

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

Calculates Blood pressure z-scores

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

bp_standardsDS(
  sex = sex,
  age = age,
  height = height,
  bp = bp,
  systolic = systolic
)

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.

Note

The z-scores of height based on CDC growth charts are calculated by the sds function from the childsds R package.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Concatenates objects into a vector or list

Description

This function is similar to the R base function 'c'.

Usage

cDS(objs)

Arguments

Details

Unlike the R base function 'c' on vector or list of certain length are allowed as output

Value

a vector or list

Author(s)

Gaye, A.

cbindDS called by ds.cbind

Description

serverside assign function that takes a sequence of vector, matrix or data-frame arguments and combines them by column to produce a data-frame.

Usage

cbindDS(x.names.transmit = NULL, colnames.transmit = NULL)

Arguments

Details

A sequence of vector, matrix or data-frame arguments is combined column by column to produce a data-frame which is written to the serverside. A critical requirement is that the length of all component variables, and the number of rows of the component data.frames or matrices must all be the same. The output data.frame will then have this same number of rows. For more details see help for ds.cbind and the native R function cbind.

Value

the object specified by the newobj argument of ds.cbind (or default name cbind.newobj) which is written to the serverside. The output object is of class data.frame.

Author(s)

Paul Burton and Demetris Avraam for DataSHIELD Development Team

Changes a reference level of a factor

Description

This function is similar to R function relevel,

Usage

changeRefGroupDS(xvect, ref = NULL, reorderByRef = NULL)

Arguments

Details

In addition to what the R function does, this function allows for the user to re-order the vector, putting the reference group first. 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.

Value

a factor of the same length as xvect

Author(s)

Isaeva, J., Gaye, A.

Checks if a numeric variable has negative values

Description

this function is only called by the client function ds.glm.

Usage

checkNegValueDS(weights)

Arguments

Details

if a user sets the parameter 'weights' on the client site function ds.glm this server side function is called to verify that the 'weights' vector does not have negative values because no negative are allowed in weights.

Value

a boolean; TRUE if the vector has one or more negative values and FALSE otherwise

Author(s)

Gaye, A.

checkPermissivePrivacyControlLevel

Description

This server-side function check that the server is running in "permissive" privacy control level.

Usage

checkPermissivePrivacyControlLevel(privacyControlLevels)

Arguments

Details

Tests whether the R option "datashield.privacyControlLevel" is set to "permissive", if it isn't will cause a call to stop() with the message "BLOCKED: The server is running in 'non-permissive' mode which has caused this method to be blocked".

Value

No return value, called for side effects

Author(s)

Wheater, Dr SM., DataSHIELD Development Team.

Returns the class of an object

Description

This function is similar to R function class.

Usage

classDS(x)

Arguments

Details

The function returns the class of an object

Value

the class of the input object

Author(s)

Stuart Wheater, for DataSHIELD Development Team

Returns the column names of a data frame or matrix

Description

This function is similar to R function colnames.

Usage

colnamesDS(x)

Arguments

Details

The function returns the column names of the input dataframe or matrix

Value

the column names of the input object

Author(s)

Demetris Avraam, for DataSHIELD Development Team

completeCasesDS: an assign function called by ds.completeCases

Description

Identifies and strips out all rows of a data.frame, matrix or vector that contain NAs.

Usage

completeCasesDS(x1.transmit)

Arguments

Details

In the case of a data.frame or matrix, completeCasesDS identifies all rows containing one or more NAs and deletes those rows altogether. Any one variable with NA in a given row will lead to deletion of the whole row. In the case of a vector, completeCasesDS acts in an equivalent manner but there is no equivalent to a 'row' and so it simply strips out all observations recorded as NA. ds.completeCASES is analogous to the complete.cases function in native R. Limited additional information can therefore be found under help("complete.cases") in native R.

Value

a modified data.frame, matrix or vector from which all rows containing at least one NA have been deleted. This modified object is written to the serverside in each source. 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.completeCases also returns any studysideMessages that can help 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

Computes the sum of each variable and the sum of products for each pair of variables

Description

This function computes the sum of each vector of variable and the sum of the products of each two variables (i.e. the scalar product of each two vectors).

Usage

corDS(x = NULL, y = NULL)

Arguments

Details

computes the sum of each vector of variable and the sum of the products of each two variables

Value

a list that includes a matrix with elements the sum of products between each two variables, a matrix with elements the sum of the values of each variable, a matrix with elements the number of complete cases in each pair of variables, a list with the number of missing values in each variable separately (columnwise) and the number of missing values casewise, and a vector with elements the sum of squares of each variable. 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)

Paul Burton, and Demetris Avraam for DataSHIELD Development Team

Tests for correlation between paired samples

Description

This function is similar to R function cor.test.

Usage

corTestDS(x, y, method, exact, conf.level)

Arguments

Details

The function runs a two-sided correlation test

Value

the results of the correlation test.

Author(s)

Demetris Avraam, for DataSHIELD Development Team

Computes the sum of each variable and the sum of products for each pair of variables

Description

This function computes the sum of each vector of variable and the sum of the products of each two variables (i.e. the scalar product of each two vectors).

Usage

covDS(x = NULL, y = NULL, use = NULL)

Arguments

Details

computes the sum of each vector of variable and the sum of the products of each two variables

Value

a list that includes a matrix with elements the sum of products between each two variables, a matrix with elements the sum of the values of each variable, a matrix with elements the number of complete cases in each pair of variables, a list with the number of missing values in each variable separately (columnwise) and the number of missing values casewise or pairwise depending on the argument use, 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.

Author(s)

Amadou Gaye, Paul Burton, and Demetris Avraam for DataSHIELD Development Team

dataFrameDS called by ds.dataFrame

Description

The serverside function that creates a data frame from its elemental components. That is: pre-existing data frames; single variables; and/or matrices

Usage

dataFrameDS(
  vectors = NULL,
  r.names = NULL,
  ch.rows = FALSE,
  ch.names = TRUE,
  clnames = NULL,
  strAsFactors = TRUE,
  completeCases = FALSE
)

Arguments

Details

A data frame is a list of variables all with the same number of rows with unique row names, which is of class 'data.frame'. ds.dataFrame will create a data frame by combining a series of elemental components which may be pre-existing data.frames, matrices or variables. A critical requirement is that the length of all component variables, and the number of rows of the component data.frames or matrices must all be the same. The output data.frame will then have this same number of rows. The serverside function dataFrameDS() calls the native R function data.frame() and several of its arguments are precisely the same as for data.frame(). In consequence, additional information can be sought from the help() for data.frame().

Value

a dataframe composed of the specified elemental components will be created on the serverside and named according to the <newobj> argument of the clientside function ds.dataFrame()

Author(s)

DataSHIELD Development Team

dataFrameFillDS

Description

An assign function called by the clientside ds.dataFrameFill function.

Usage

dataFrameFillDS(
  df.name,
  allNames.transmit,
  class.vect.transmit,
  levels.vec.transmit
)

Arguments

Details

This function checks if each study has all the variables compared to the other studies in the analysis. If 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. Then, the "complete" in terms of the columns dataframe is saved in each server with a name specified by the argument newobj on the clientside.

Value

Nothing is returned to the client. The generated object is written to the serverside.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Sorting and reordering data frames, vectors or matrices

Description

Sorts a data frame using a specified alphanumeric or numeric sort key

Usage

dataFrameSortDS(
  df.name = NULL,
  sort.key.name = NULL,
  sort.descending,
  sort.method
)

Arguments

Details

Serverside assign function dataFrameSortDS is called by clientside function ds.dataFrameSort. A vector or a matrix can be added to, or coerced into, a data frame (using function [ds.dataFrame]) and this means that they too can be sorted/reordered using ds.dataFrameSort. Fundamentally, the function [ds.dataFrameSort] will sort a specified data frame on the serverside using a sort key also on the serverside. For more details see help for the clientside function: [ds.dataFrameShort]

Value

the appropriately re-sorted data.frame will be written to the serverside R environment as a data.frame named according to the <newobj> argument(or with default name 'dataframesort.newobj') if no name is specified

Author(s)

Paul Burton, with critical error identification by Leire Abarrategui-Martinez, for DataSHIELD Development Team, 2/4/2020

dataFrameSubsetDS1 an aggregate function called by ds.dataFrameSubset

Description

First serverside function for subsetting a data frame by row or by column.

Usage

dataFrameSubsetDS1(
  df.name = NULL,
  V1.name = NULL,
  V2.name = NULL,
  Boolean.operator.n = NULL,
  keep.cols = NULL,
  rm.cols = NULL,
  keep.NAs = NULL
)

Arguments

Details

A data frame is a list of variables all with the same number of rows, which is of class 'data.frame'. For all details see the help header for ds.dataFrameSubset

Value

This first serverside function called by ds.dataFrameSubset provides first level traps for a comprehensive series of disclosure risks which can be returned directly to the clientside because dataFrameSubsetDS1 is an aggregate function. The second serverside function called by ds.dataFrameSubset (dataFrameSubsetDS2) carries out most of the same disclosure tests, but it is an assign function because it writes the subsetted data.frame to the serverside. In consequence, it records error messages as studysideMessages which can only be retrieved using ds.message

Author(s)

Paul Burton

dataFrameSubsetDS2 an assign function called by ds.dataFrameSubset

Description

Second serverside function for subsetting a data frame by row or by column.

Usage

dataFrameSubsetDS2(
  df.name = NULL,
  V1.name = NULL,
  V2.name = NULL,
  Boolean.operator.n = NULL,
  keep.cols = NULL,
  rm.cols = NULL,
  keep.NAs = NULL
)

Arguments

Details

A data frame is a list of variables all with the same number of rows, which is of class 'data.frame'. For all details see the help header for ds.dataFrameSubset

Value

the object specified by the <newobj> argument (or default name '<df.name>_subset') initially specified in calling ds.dataFrameSubset. The output object (the required subsetted data.frame called <newobj> is written to the serverside. In addition, two validity messages are returned via ds.dataFrameSubset 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 - dataFrameSubsetDS2 (via ds.dataFrame()) 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)

DataSHIELD Development Team

Generates a density grid with or without a priori defined limits

Description

Generates a density grid that can then be used for heatmap or countour plots.

Usage

densityGridDS(
  xvect,
  yvect,
  limits = FALSE,
  x.min = NULL,
  x.max = NULL,
  y.min = NULL,
  y.max = NULL,
  numints = 20
)

Arguments

Details

Invalid cells (cells with count < to the set filter value for the minimum allowed counts in table cells) are turn to 0.

Value

a grid density matrix

Author(s)

Julia Isaeva, Amadou Gaye, Demetris Avraam for DataSHIELD Development Team

Returns the dimension of a data frame or matrix

Description

This function is similar to R function dim.

Usage

dimDS(x)

Arguments

Details

The function returns the dimension of the input dataframe or matrix

Value

the dimension of the input object

Author(s)

Demetris Avraam, for DataSHIELD Development Team

Copy a clientside data.frame, matrix or tibble (DMT) to the serverside.

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

dmtC2SDS(
  dfdata.mat.transmit,
  inout.object.transmit,
  from,
  nrows.transmit,
  ncols.transmit,
  colnames.transmit,
  colclass.transmit,
  byrow
)

Arguments

Details

dmtC2SDS is a serverside assign function called by ds.dmtC2S. For more information about how it works see help for ds.dmtC2S

Value

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

Author(s)

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

Basis for a piecewise linear spline with meaningful coefficients

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

elsplineDS(x = x, n = n, marginal = FALSE, names = 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

Secure ranking of "V2BR" (vector to be ranked) across all sources and use of these ranks to estimate global quantiles across all studies

Description

identify the global values of V2BR (i.e. the values across all studies) that relate to a set of quantiles to be evaluated.

Usage

extractQuantilesDS1(extract.quantiles, extract.summary.output.ranks.df)

Arguments

Details

Severside aggregate function called by ds.extractQuantiles via ds.ranksSecure. As well as estimating the key values of V2BR that correspond to the selected quantiles, this function also implements a disclosure control trap. If the ratio of the total number of all observations across all studies divided by the number of quantile values to be estimated is less than or equal to nfilter.subset (which specifies the minimum size of a subset) the process stops and an error message is returned suggesting that you might try selecting a narrower range of quantiles with less quantile values to be estimated as specified by the argument <quantiles.for.estimation> of the function ds.ranksSecure. 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"

Value

as a first step in creating the vector of values of values of V2BR that correspond to each quantile value, extractQuantilesDS1 identifies the two closest quantile values across all studies that span each key quantile value. These are saved as the data frame "closest.bounds.df" on the clientside and then saved on the serverside by ds.dmtC2S into the data frame "global.bounds.df". Also if the number of observations across all studies is too small, and a disclosure risk exists if the final.quantile.vector is made available via the client, this function stops the processing and returns a warning/error message.

Author(s)

Paul Burton 11th November, 2021

Secure ranking of "V2BR" (vector to be ranked) across all sources and use of these ranks to estimate global quantiles across all studies

Description

identify the global values of V2BR (i.e. the values across all studies) that relate to a set of quantiles to be evaluated.

Usage

extractQuantilesDS2(extract.summary.output.ranks.df)

Arguments

Details

Severside aggregate function called by ds.extractQuantiles via ds.ranksSecure. This takes the "global.bounds.df" data frame saved on the serverside following construction by extractQuantilesDS1. This data frame includes the two quantile values that most closely span each quartile value to be estimated. If either of the values had been the correct value for a given quantile, both the bounding values would have taken that value in global.bounds.df. This is because the upper bound was defined as the lowest value that was equal to or greater than the true value for that quantile while the lower bound was defined as the highest value that was equal to or lower than the true value. Next, the function extractQuantileDS2 goes round study by study to identify the values of V2BR that actually correspond to each of the spanning values around each quantile. Then the function goes quantile by quantile and estimates the mean of the two values of V2BR that correspond to the the spanning quantiles. If these two values are the same it means that that value of V2BR is the "true" value and the mean of two (or potentially several) instances of that value is inevitably also equal to that true value. If the upper and lower bounding values of V2BR differ, neither can be the precisely correct single value of V2BR for that quantile (see above for explanation) and so the mean of the two is a reasonable interpolated summary.

Value

the single value of V2BR which best corresponds to each key quantile value to be estimated as specified by the argument <quantiles.for.estimation> A data frame (final.quantile.df)summarising the results of this analysis is written to the clientside. This data frame consists of two vectors. The first is named "evaluation.quantiles". It lists the full set of quantiles you have requested for evaluation as specified by the argument "quantiles.for.estimation" The second vector which is called "final.quantile.vector" details the values of V2BR that correspond to the the key quantiles listed in vector 1.

Author(s)

Paul Burton 11th November, 2021

gamlssDS an aggregate function called by ds.galmss

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

gamlssDS(
  formula = formula,
  sigma.formula = sigma.formula,
  nu.formula = nu.formula,
  tau.formula = tau.formula,
  family = family,
  data = data,
  method = method,
  mu.fix = mu.fix,
  sigma.fix = sigma.fix,
  nu.fix = nu.fix,
  tau.fix = tau.fix,
  control = control,
  i.control = i.control,
  centiles = centiles,
  xvar = xvar,
  newobj = newobj
)

Arguments

Details

For additional details see the help header of gamlss and centiles functions in native R gamlss package.

Value

a gamlss object with all components as in the native R gamlss function. Individual-level information like the components y (the response response) and residuals (the normalised quantile residuals of the model) are not disclosed to the client-side.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Computes the WHO Growth Reference z-scores of anthropometric data

Description

Calculate WHO Growth Reference z-score for a given anthropometric measurement This function is similar to R function getWGSR from the zscorer package.

Usage

getWGSRDS(sex, firstPart, secondPart, index, standing = NA, thirdPart = NA)

Arguments

Details

The function computes the WHO Growth Reference z-scores of anthropometric data for weight, height or length, MUAC, head circumference, sub-scapular skinfold and triceps skinfold. Note that the function might fail or return NAs when the variables are outside the ranges given in the WGS (WHO Child Growth Standards) reference (i.e. 45 to 120 cm for height and 0 to 60 months for age). It is up to the user to check the ranges and the units of their data.

Value

ds.getWGSR assigns a numeric vector that includes the z-scores for the specified index.

Author(s)

Demetris Avraam for DataSHIELD Development Team

glmDS1 called by ds.glm

Description

This is the first server-side aggregate function called by ds.glm

Usage

glmDS1(formula, family, weights, offset, data)

Arguments

Details

It is an aggregation function that sets up the model structure and creates the starting beta.vector that feeds, via ds.glm, into glmDS2 to enable iterative fitting of the generalized linear model that has been been specified. For more details please see the extensive header for ds.glm.

Value

List with values from GLM model.

Author(s)

Burton PR for DataSHIELD Development Team

glmDS2 called by ds.glm

Description

This is the second server-side aggregate function called by ds.glm.

Usage

glmDS2(formula, family, beta.vect, offset, weights, dataName)

Arguments

Details

It is an aggregate function that uses the model structure and starting beta.vector constructed by glmDS1 to iteratively fit the generalized linear model that has been specified. The function glmDS2 also carries out a series of disclosure checks and if the arguments or data fail any of those tests, model construction is blocked and an appropriate serverside error message is created and returned to ds.glm on the clientside. For more details please see the extensive header for ds.glm.

Value

List with values from GLM model

Author(s)

Paul Burton, for DataSHIELD Development Team

predict regression responses from a glm object

Description

identify and return key components/summaries of a serverside glm_predict object that can safely be returned to the clientside without disclosure risk

Usage

glmPredictDS.ag(
  glmname.transmit,
  newdataname.transmit,
  output.type,
  se.fit,
  dispersion,
  terms.transmit,
  na.action
)

Arguments

Details

Serverside aggregate function called by ds.glmPredict. It is called immediately after the assign function glmPredict.as has created a predict_glm object on the serverside by applying the equivalent of predict.glm() in native R to a glm object on the serverside. The aggregate function, glmPredict.ag, then identifies and returns components of that predict_glm object that can safely be returned to the clientside without a risk of disclosure. For further details see DataSHIELD help for ds.glmPredict and glmPredict.as and help in native R for predict.glm

Value

components/summarising statistics of a serverside predict_glm object that can safely be transmitted to the clientside without a risk of disclosure. For further details see DataSHIELD help for ds.glmPredict and glmPredict.as and help in native R for predict.glm predict.glm in native R

Author(s)

Paul Burton for DataSHIELD Development Team (20/7/20)

predict regression responses from a glm object

Description

create a predict_glm object on the serverside by applying the equivalent of predict.glm() in native R to a glm object on the serverside. Identify and return components of the predict_glm object that can safely be sent to the clientside without a risk of disclosure

Usage

glmPredictDS.as(
  glmname.transmit,
  newdataname.transmit,
  output.type,
  se.fit,
  dispersion,
  terms.transmit,
  na.action
)

Arguments

Details

Serverside assign function called by ds.glmPredict makes predictions of regression responses based on a serverside glm object that has already been created on the serverside by ds.glmSLMA and and writes the predict_glm object to the serverside. For further details see help for ds.glmPredict and help in native R for predict.glm

Value

glmPredict.as writes a new object to the serverside containing output precisely equivalent to the output from predict.glm in native R. For more details see DataSHIELD help for ds.glmPredict and help for predict.glm in native R

Author(s)

Paul Burton for DataSHIELD Development Team (20/7/20)

Fit a Generalized Linear Model (GLM) with pooling via Study Level Meta-Analysis (SLMA)

Description

Fits a generalized linear model (GLM) on data from single or multiple sources with pooled co-analysis across studies being based on SLMA (Study Level Meta Analysis).

Usage

glmSLMADS.assign(formula, family, offsetName, weightsName, dataName)

Arguments

Details

glmSLMADS.assign is an assign function called by clientside function ds.glmSLMA. ds.glmSLMA also calls two aggregate functions glmSLMADS1 and glmSLMADS2. For more detailed information see help for ds.glmSLMA.

Value

writes glm object summarising the fitted model to the serverside. For more detailed information see help for ds.glmSLMA.

Author(s)

Paul Burton for DataSHIELD Development Team (14/7/20)

Fit a Generalized Linear Model (GLM) with pooling via Study Level Meta-Analysis (SLMA)

Description

Fits a generalized linear model (GLM) on data from single or multiple sources with pooled co-analysis across studies being based on SLMA (Study Level Meta Analysis).

Usage

glmSLMADS1(formula, family, weights, offset, data)

Arguments

Details

glmSLMADS.assign is an aggregate function called by clientside function ds.glmSLMA. ds.glmSLMA also calls another aggregate function glmSLMADS2 and an assign function glmSLMADS.assign For more detailed information see help for ds.glmSLMA.

Value

assesses and returns information about failure to pass disclosure traps such as test of model complexity (saturation). For more detailed information see help for ds.glmSLMA.

Author(s)

Paul Burton for DataSHIELD Development Team (14/7/20)

Fit a Generalized Linear Model (GLM) with pooling via Study Level Meta-Analysis (SLMA)

Description

Fits a generalized linear model (GLM) on data from single or multiple sources with pooled co-analysis across studies being based on SLMA (Study Level Meta Analysis).

Usage

glmSLMADS2(formula, family, offset, weights, newobj, dataName)

Arguments

Details

glmSLMADS.assign is an aggregate function called by clientside function ds.glmSLMA. ds.glmSLMA also calls another aggregate function glmSLMADS2 and an assign function glmSLMADS.assign For more detailed information see help for ds.glmSLMA.

Value

All quantitative, Boolean, and character objects required to enable the SLMA pooling of the separate glm models fitted to each study - in particular including the study-specific regression coefficients and their corresponding standard errors.

Author(s)

Paul Burton for DataSHIELD Development Team (14/7/20)

summarize a glm object on the serverside

Description

returns the non-disclosive elements to the clientside of a glm object and the corresponding object holding the output of summary(glm object) on the serverside.

Usage

glmSummaryDS.ag(x.transmit)

Arguments

Details

Serverside aggregate function called by ds.glmSummary. ds.glmSummary first calls glmSummaryDS.ag to create a glm_summary object on the serverside based on applying native R's summary.glm() to a serverside glm object previously created by ds.glmSLMA. Then it calls glmSummaryDS.ag to return to the clientside all of the non-disclosive elements (and only the non-disclosive elements) of the serverside glm and its corresponding summary_glm object.

Value

returns to the clientside all of the non-disclosive elements (and only the non-disclosive elements) of a specified serverside glm and its corresponding summary_glm object.

Author(s)

Paul Burton for DataSHIELD Development Team (20/7/20)

summarize a glm object on the serverside

Description

summarize a glm object on the serverside to create a summary_glm object. Also identify and return components of both the glm object and the summary_glm object that can safely be sent to the clientside without a risk of disclosure

Usage

glmSummaryDS.as(x.transmit)

Arguments

Details

Serverside assign function called by ds.glmSummary summarises a glm object that has already been created on the serverside by fitting ds.glmSLMA and writes the summary_glm object to the serverside. For further details see help for ds.glmSLMA and help in native R for glm() and summary.glm

Value

writes object to serverside which is precisely equivalent to summary(glm object) in native R

Author(s)

Paul Burton for DataSHIELD Development Team (20/7/20)

Fitting generalized linear mixed effect models - serverside function

Description

glmerSLMADS.assign is the same as glmerSLMADS2 which fits a generalized linear mixed effects model (glme) per study and saves the outcomes in each study

Usage

glmerSLMADS.assign(
  formula,
  offset,
  weights,
  dataName,
  family,
  control_type = NULL,
  control_value.transmit = NULL,
  nAGQ = 1L,
  verbose = 0,
  theta = NULL,
  fixef = NULL
)

Arguments

Details

glmerSLMADS.assign is a serverside function called by ds.glmerSLMA on the clientside. The analytic work engine is the glmer function in R which sits in the lme4 package. glmerSLMADS.assign fits a generalized linear mixed effects model (glme) - e.g. a logistic or Poisson regression model including both fixed and random effects - on data from each single data source and saves the regression outcomes on the serveside.

Value

writes glmerMod object summarising the fitted model to the serverside. For more detailed information see help for ds.glmerSLMA.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Fitting generalized linear mixed effect models - serverside function

Description

glmerSLMADS2 fits a generalized linear mixed effects model (glme) - e.g. a logistic or Poisson regression model including both fixed and random effects - on data from one or multiple sources with pooling via SLMA (study level meta-analysis)

Usage

glmerSLMADS2(
  formula,
  offset,
  weights,
  dataName,
  family,
  control_type = NULL,
  control_value.transmit = NULL,
  nAGQ = 1L,
  verbose = 0,
  theta = NULL,
  fixef = NULL
)

Arguments

Details

glmerSLMADS2 is a serverside function called by ds.glmerSLMA on the clientside. The analytic work engine is the glmer function in R which sits in the lme4 package. ds.glmerSLMA fits a generalized linear mixed effects model (glme) - e.g. a logistic or Poisson regression model including both fixed and random effects - on data from a single or multiple sources. When there are multiple data sources, the glme is fitted to convergence in each data source independently and the estimates and standard errors returned to the client thereby enabling cross-study pooling using study level meta-analysis (SLMA). By default the SLMA is undertaken using the metafor package, but as the SLMA occurs on the clientside which, as far as the user is concerned is just a standard R environment, the user can choose to use any approach to meta-analysis they choose. Additional information about fitting glmes using the glmer engine can be obtained using R help for glmer and the lme4 package

Value

all key model components see help for ds.glmerSLMA

Author(s)

Tom Bishop, with some additions by Paul Burton

Calculates the coordinates of the centroid of each n nearest neighbours

Description

This function calculates the coordinates of the centroids for each n nearest neighbours.

Usage

heatmapPlotDS(x, y, k, noise, method.indicator)

Arguments

Details

The function finds the n-1 nearest neighbours of each data point in a 2-dimensional space. The nearest neighbours are the data points with the minimum Euclidean distances from the point of interest. Each point of interest and its n-1 nearest neighbours are then used for the calculation of the coordinates of the centroid of those n points. Centroid here is referred to the centre of mass, i.e. the x-coordinate of the centroid is the average value of the x-coordinates of the n nearest neighbours and the y-coordinate of the centroid is the average of the y-coordinates of the n nearest neighbours. The coordinates of the centroids return to the client side function and can be used for the plot of non-disclosive graphs (e.g. scatter plots, heatmap plots, contour plots, etc).

Value

a list with the x and y coordinates of the centroids if the deterministic method is used or the x and y coordinated of the noisy data if the probabilistic method is used.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Heterogeneous Correlation Matrix

Description

This function is based on the hetcor function from the R package polycor.

Usage

hetcorDS(data, ML, std.err, bins, pd, use)

Arguments

Details

Computes a heterogenous correlation matrix, consisting of Pearson product-moment correlations between numeric variables, polyserial correlations between numeric and ordinal variables, and polychoric correlations between ordinal variables.

Value

Returns an object of class "hetcor" with the following components: the correlation matrix; the type of each correlation: "Pearson", "Polychoric", or "Polyserial"; the standard errors of the correlations, if requested; the number (or numbers) of observations on which the correlations are based; p-values for tests of bivariate normality for each pair of variables; the method by which any missing data were handled: "complete.obs" or "pairwise.complete.obs"; TRUE for ML estimates, FALSE for two-step estimates.

Author(s)

Demetris Avraam for DataSHIELD Development Team

returns the minimum and the maximum of the input numeric vector

Description

this function returns the minimum and maximum of the input numeric vector which depends on the argument method.indicator. If the method.indicator is set to 1 (i.e. the 'smallCellsRule' is used) the computed minimum and maximum values are multiplied by a very small random number. If the method.indicator is set to 2 (i.e. the 'deterministic' method is used) the function returns the minimum and maximum values of the vector with the scaled centroids. If the method.indicator is set to 3 (i.e. the 'probabilistic' method is used) the function returns the minimum and maximum values of the generated 'noisy' vector.

Usage

histogramDS1(xvect, method.indicator, k, noise)

Arguments

Value

a numeric vector which contains the minimum and the maximum values of the vector

Author(s)

Amadou Gaye, Demetris Avraam for DataSHIELD Development Team

Computes a histogram of the input variable without plotting.

Description

This function produces the information required to plot a histogram. This is done without allowing for bins (cells) with number of counts less than the pre-specified disclosure control set for the minimum cell size of a table. If a bin has less counts than this threshold then their counts and its density are replaced by a 0 value.

Usage

histogramDS2(xvect, num.breaks, min, max, method.indicator, k, noise)

Arguments

Details

Please find more details in the documentation of the clientside ds.histogram function.

Value

a list with an object of class histogram and the number of invalid cells

Author(s)

Amadou Gaye, Demetris Avraam for DataSHIELD Development Team

Converts birth measurements to intergrowth z-scores/centiles

Description

Converts birth measurements to INTERGROWTH z-scores/centiles (generic)

Usage

igb_standardsDS(
  gagebrth = gagebrth,
  z = z,
  p = p,
  val = val,
  var = var,
  sex = sex,
  fun = fun
)

Arguments

Value

assigns the converted measurement as a new object on the server-side

Note

For gestational ages between 24 and 33 weeks, the INTERGROWTH very early preterm standard is used.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Checks if a vector is empty

Description

this function is similar to R function is.na but instead of a vector of booleans it returns just one boolean to tell if all the element are missing values.

Usage

isNaDS(xvect)

Arguments

Value

the integer '1' if the vector contains on NAs and '0' otherwise

Author(s)

Gaye, A.

Checks if an input is valid

Description

Tells if an object on the server side is valid.

Usage

isValidDS(obj)

Arguments

Details

This function checks if an object is valid.

Value

a boolean, TRUE if input is valid or FALSE if not.

Author(s)

Gaye, A.

Calculates the kurtosis of a numeric variable

Description

This function calculates the kurtosis of a numeric variable for each study separately.

Usage

kurtosisDS1(x, method)

Arguments

Details

The function calculates the kurtosis of an input variable x with three different methods. The method is specified by the argument method in the client-side ds.kurtosis function.

Value

a list including the kurtosis of the input numeric variable, the number of valid observations and the study-side validity message.

Author(s)

Demetris Avraam, for DataSHIELD Development Team

Calculates the kurtosis of a numeric variable

Description

This function calculates summary statistics that are returned to the client-side and used for the estimation of the combined kurtosis of a numeric variable across all studies.

Usage

kurtosisDS2(x, global.mean)

Arguments

Details

The function calculates the sum of squared differences between the values of x and the global mean of x across all studies, the sum of quatric differences between the values of x and the global mean of x across all studies and the number of valid observations of the input variable x.

Value

a list including the sum of quartic differences between the values of x and the global mean of x across all studies, the sum of squared differences between the values of x and the global mean of x across all studies, the number of valid observations (i.e. the length of x after excluding missing values), and a validity message indicating indicating a valid analysis if the number of valid observations are above the protection filter nfilter.tab or invalid analysis otherwise.

Author(s)

Demetris Avraam, for DataSHIELD Development Team

Returns the length of a vector or list

Description

This function is similar to R function length.

Usage

lengthDS(x)

Arguments

Details

The function returns the length of the input vector or list.

Value

a numeric, the number of elements of the input vector or list.

Author(s)

Demetris Avraam, for DataSHIELD Development Team

Returns the levels of a factor vector

Description

This function is similar to R function levels.

Usage

levelsDS(x)

Arguments

Details

The function returns the levels of the input vector or list.

Value

a list, the factor levels present in the vector

Author(s)

Alex Westerberg, for DataSHIELD Development Team

lexisDS1

Description

The first server-side function called by ds.lexis.

Usage

lexisDS1(exitCol = NULL)

Arguments

Details

This is an aggregate function. For more details see the extensive header for ds.lexis.

Value

List with 'max.time'

Author(s)

Burton PR

lexisDS2

Description

The second serverside function called by ds.lexis.

Usage

lexisDS2(
  datatext = NULL,
  intervalWidth,
  maxmaxtime,
  idCol,
  entryCol,
  exitCol,
  statusCol,
  vartext = NULL
)

Arguments

Details

This is the assign function which actually creates the expanded dataframe containing surival data for a piecewise exponential regression. lexisDS2 also carries out a series of disclosure checks and if the arguments or data fail any of those tests, creation of the expanded dataframe is blocked and an appropriate serverside error message is stored. For more details see the extensive header for ds.lexis.

Value

List with 'expanded.table'

Author(s)

Burton PR

@title lexisDS3

Description

The third serverside function called by ds.lexis.

Usage

lexisDS3()

Details

This is an assign function that simplifies the returned output from ds.lexis. Specifically, without lexisDS3 the output consists of a table within a list, but lexisDS3 converts this directly into a dataframe. For more details see the extensive header for ds.lexis.

Value

Data frame with 'messageobj' object

Coerce objects into a list

Description

this function is similar to R function 'list'

Usage

listDS(input = NULL, eltnames = NULL)

Arguments

Details

Unlike the R function 'list' it takes also a vector of characters, the names of the elements in the output list.

Value

a list

Author(s)

Gaye, A.

listDisclosureSettingsDS

Description

This serverside function is an aggregate function that is called by the ds.listDisclosureSettings

Usage

listDisclosureSettingsDS()

Details

For more details see the extensive header for ds.listDisclosureSettings

Value

List with DataSHIELD disclosure settings

Author(s)

Paul Burton, Demetris Avraam for DataSHIELD Development Team

Fitting linear mixed effect models - serverside function

Description

lmerSLMADS.assing is the same as lmerSLMADS2 which fits a linear mixed effects model (lme) per study and saves the outcomes in each study

Usage

lmerSLMADS.assign(
  formula,
  offset,
  weights,
  dataName,
  REML = TRUE,
  control_type,
  control_value.transmit,
  optimizer,
  verbose = 0
)

Arguments

Details

lmerSLMADS.assign is a serverside function called by ds.lmerSLMA on the clientside. The analytic work engine is the lmer function in R which sits in the lme4 package. lmerSLMADS.assign fits a linear mixed effects model (lme) including both fixed and random effects - on data from each single data source and saves the regression outcomes on the serveside.

Value

writes lmerMod object summarising the fitted model to the serverside. For more detailed information see help for ds.lmerSLMA.

Author(s)

TDemetris Avraam for DataSHIELD Development Team

Fitting linear mixed effect models - serverside function

Description

lmerSLMADS2 is a serverside function which fits a linear mixed effects model (lme) - i.e. can include both fixed and random effects - on data from one or multiple sources with pooling via SLMA (study level meta-analysis)

Usage

lmerSLMADS2(
  formula,
  offset,
  weights,
  dataName,
  REML = TRUE,
  control_type,
  control_value.transmit,
  optimizer,
  verbose = 0
)

Arguments

Details

lmerSLMADS2 is a serverside function called by ds.lmerSLMA on the clientside. The analytic work engine is the lmer function in R which sits in the lme4 package. ds.lmerSLMA fits a linear mixed effects model (lme) - can include both fixed and random effects - on data from a single or multiple sources. When there are multiple data sources, the lme is fitted to convergence in each data source independently and the estimates and standard errors returned to the client thereby enabling cross-study pooling using study level meta-analysis (SLMA). By default the SLMA is undertaken using the metafor package, but as the SLMA occurs on the clientside which, as far as the user is concerned is just a standard R environment, the user can choose to use any approach to meta-analysis they choose. For more detailed help about any aspect of lmerSLMDS2 please see the extensive help for ds.lmerSLMA. Additional information about fitting lmes using the lmer engine can be obtained using R help for lmer and the lme4 package

Value

all key model components see help for ds.lmerSLMA

Author(s)

Tom Bishop, with some additions by Paul Burton

lists all objects on a serverside environment

Description

creates a list of the names of all of the objects in a specified serverside environment

Usage

lsDS(search.filter = NULL, env.to.search)

Arguments

Details

Serverside aggregate function lsDS called by clientside function ds.ls. When running analyses one may want to know the objects already generated. This request is not disclosive as it only returns the names of the objects and not their contents. By default, objects in the current 'active analytic environment' (".GlobalEnv") will be displayed. This is the environment that contains all of the objects that serverside DataSHIELD is using for the main analysis or has written out to the serverside during the process of managing or undertaking the analysis (variables, scalars, matrices, data.frames etc). For further details see help for ds.ls function and for native R function ls

Value

a list containing: (1) the name/details of the serverside R environment which ds.ls has searched; (2) a vector of character strings giving the names of all objects meeting the naming criteria specified by the argument <search.filter> in this specified R serverside environment; (3) the nature of the search filter string as it was actually applied

Author(s)

Gaye, A (2015). Updated and extended by Paul Burton (2020).

Basis for a piecewise linear spline with meaningful coefficients

Description

This function is based on the native R function lspline 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

lsplineDS(x = x, knots = NULL, marginal = FALSE, names = 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.

Value

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

Author(s)

Demetris Avraam for DataSHIELD Development Team

matrixDS assign function called by ds.matrix

Description

Creates a matrix A on the serverside

Usage

matrixDS(mdata.transmit, from, nrows.transmit, ncols.transmit, byrow, dimnames)

Arguments

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

Output is the matrix A written to the serverside. For more details see help for ds.matrix

Author(s)

Paul Burton for DataSHIELD Development Team

matrixDetDS aggregate function called by ds.matrixDet.report

Description

Calculates the determinant of a square matrix A and returns the output to the clientside

Usage

matrixDetDS1(M1.name = NULL, logarithm)

Arguments

Details

Calculates the determinant of a square matrix (for additional information see help for det function in native R). This operation is only possible if the number of columns and rows of A are the same.

Value

Output is the determinant of the matrix identified by argument <M1> which is returned to the clientside. For more details see help for ds.matrixDet

Author(s)

Paul Burton for DataSHIELD Development Team

matrixDetDS assign function called by ds.matrixDet

Description

Calculates the determinant of a square matrix A and writes the output to the serverside

Usage

matrixDetDS2(M1.name = NULL, logarithm)

Arguments

Details

Calculates the determinant of a square matrix (for additional information see help for det function in native R). This operation is only possible if the number of columns and rows of A are the same.

Value

Output is the determinant of the matrix identified by argument <M1> which is written to the serverside. For more details see help for ds.matrixDet

Author(s)

Paul Burton for DataSHIELD Development Team

matrixDiagDS assign function called by ds.matrixDiag

Description

Extracts the diagonal vector from a square matrix A or creates a diagonal matrix A based on a vector or a scalar value and writes the output to the serverside

Usage

matrixDiagDS(x1.transmit, aim, nrows.transmit)

Arguments

Details

For details see help for function ds.matrixDiag.

Value

Output is the matrix or vector specified by the <newobj> argument (or default name diag_<x1>) which is written to the serverside. For more details see help for ds.matrixDiag.

Author(s)

Paul Burton for DataSHIELD Development Team

matrixDimnamesDS assign function called by ds.matrixDimnames

Description

Adds dimnames (row names, column names or both) to a matrix on the serverside.

Usage

matrixDimnamesDS(M1.name = NULL, dimnames)

Arguments

Details

Adds dimnames (row names, column names or both) to a matrix on the serverside. Similar to the dimnames function in native R. For more details see help for function ds.matrixDimnames

Value

Output is the serverside matrix specified by the <newobj> argument (or default name diag_<x1>) with specified dimnames (row and column names) which is written to the serverside.

Author(s)

Paul Burton for DataSHIELD Development Team

matrixInvertDS serverside assign function called by ds.matrixInvert

Description

Inverts a square matrix A and writes the output to the serverside

Usage

matrixInvertDS(M1.name = NULL)

Arguments

Details

Undertakes standard matrix inversion. This operation is only possible if the number of columns and rows of A are the same and the matrix is non-singular - positive definite (eg there is no row or column that is all zeros)

Value

Output is the matrix representing the inverse of A which is written to the serverside. For more details see help for ds.matrixInvert

Author(s)

Paul Burton for DataSHIELD Development Team

matrixMultDS serverside assign function called by ds.matrixMult

Description

Calculates the matrix product of two matrices and writes output to serverside

Usage

matrixMultDS(M1.name = NULL, M2.name = NULL)

Arguments

Details

Undertakes standard matrix multiplication where with input matrices A and B with dimensions A: mxn and B: nxp the output C has dimensions mxp and each element C[i,j] has value equal to the dot product of row i of A and column j of B where the dot product is obtained as sum(A[i,1]*B[1,j] + A[i,2]*B[2,j] + .... + A[i,n]*B[n,j]). This calculation is only valid if the number of columns of A is the same as the number of rows of B

Value

Output is the matrix representing the product of M1 and M2 which is written to the serverside. For more details see help for ds.matrixMult

Author(s)

Paul Burton for DataSHIELD Development Team

matrixTransposeDS serverside assign function called by ds.matrixTranspose

Description

Transposes a matrix A and writes the output to the serverside

Usage

matrixTransposeDS(M1.name = NULL)

Arguments

Details

Undertakes standard matrix transposition. This operation converts matrix A to matrix C where element C[i,j] of matrix C equals element A[j,i] of matrix A. Matrix A therefore has the same number of rows as matrix C has columns and vice versa.

Value

Output is the matrix representing the transpose of A which is written to the serverside. For more details see help for ds.matrixTranspose

Author(s)

Paul Burton for DataSHIELD Development Team

Computes statistical mean of a vectores

Description

Calculates the mean value.

Usage

meanDS(xvect)

Arguments

Details

if the length of input vector is less than the set filter a missing value is returned.

Value

a numeric, the statistical mean

Author(s)

Gaye A, Burton PR

MeanSdGpDS

Description

Server-side function called by ds.meanSdGp

Usage

meanSdGpDS(X, INDEX)

Arguments

Details

Computes the mean and standard deviation across groups defined by one factor

Value

List with results from the group statistics

Author(s)

Burton PR

mergeDS (assign function) called by ds.merge

Description

merges (links) two data.frames together based on common values in defined vectors in each data.frame

Usage

mergeDS(
  x.name,
  y.name,
  by.x.names.transmit,
  by.y.names.transmit,
  all.x,
  all.y,
  sort,
  suffixes.transmit,
  no.dups,
  incomparables
)

Arguments

Details

For further information see details of the native R function merge and the DataSHIELD clientside function ds.merge.

Value

the merged data.frame specified by the <newobj> argument of ds.merge (or by default 'x.name_y.name' if the <newobj> argument is NULL) which is written to the serverside. In addition, two validity messages are returned to the clientside 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 there may be a studysideMessage 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, Demetris Avraam, for DataSHIELD Development Team

messageDS

Description

This function allows for error messages arising from the running of a server-side assign function to be returned to the client-side

Usage

messageDS(message.object.name)

Arguments

Details

Errors arising from aggregate server-side functions can be returned directly to the client-side. But this is not possible for server-side assign functions because they are designed specifically to write objects to the server-side and to return no meaningful information to the client-side. Otherwise, users may be able to use assign functions to return disclosive output to the client-side. ds.message calls messageDS which looks specifically for an object called $serversideMessage in a designated list on the server-side. Server-side functions from which error messages are to be made available, are designed to be able to write the designated error message to the $serversideMessage object into the list that is saved on the server-side as the primary output of that function. So only valid server-side functions of DataSHIELD can write a $studysideMessage, and as additional protection against unexpected ways that someone may try to get round this limitation, a $studysideMessage is a string that cannot exceed a length of nfilter.string a default of 80 characters.

Value

a list object from each study, containing whatever message has been written by DataSHIELD into $studysideMessage.

Author(s)

Burton PR

Returns the metadata, if any, about the specified variable

Description

This function returns metadata, if any, about specified variable.

Usage

metadataDS(x)

Arguments

Details

The function returns the metadata, obtained from attributes function.

Value

a list containing the metadata. The elements of the list will depend on the meatadata available.

Author(s)

Stuart Wheater, for DataSHIELD Development Team

Aggregate function called by ds.mice

Description

This function is a wrapper function of the mice from the mice R package. The function creates multiple imputations (replacement values) for multivariate missing data. The method is based on Fully Conditional Specification, where each incomplete variable is imputed by a separate model. The MICE algorithm can impute mixes of continuous, binary, unordered categorical and ordered categorical data. In addition, MICE can impute continuous two-level data, and maintain consistency between imputations by means of passive imputation.

Usage

miceDS(
  data = data,
  m = m,
  maxit = maxit,
  method = method,
  post = post,
  seed = seed,
  predictorMatrix = predictorMatrix,
  ncol.pred.mat = ncol.pred.mat,
  newobj_mids = newobj_mids,
  newobj_df = newobj_df
)

Arguments

Details

For additional details see the help header of mice function in native R mice package.

Value

a list with three elements: the method, the predictorMatrix and the post. The function also saves in each server the mids object and all completed datasets as dataframes.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Secure ranking of "V2BR" (vector to be ranked) across all sources

Description

Creates a minimum value that is more negative, and less positive than any real value in V2BR and a maximum value that is more positive and less negative than any value of V2BR.

Usage

minMaxRandDS(input.var.name)

Arguments

Details

Severside aggregate function called by ds.ranksSecure. The minimum and maximum values it creates are used to replace missing values (NAs) in V2BR if the argument <NA.manag>e is set to "NA.low" or "NA.hi" respectively. 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". Also see the header file for ds.ranksSecure

Value

the data frame objects containing the global ranks and quantiles. For more details see the associated document entitled "secure.global.ranking.docx"

Author(s)

Paul Burton 9th November, 2021

Return the names of a list object

Description

Returns the names of a designated server-side list

Usage

namesDS(xname.transmit)

Arguments

Details

namesDS is an aggregate function called by ds.names. This function is similar to the native R function names but it does not subsume all functionality, for example, it only works to extract names that already exist, not to create new names for objects. The function is restricted to objects of type list, but this includes objects that have a primary class other than list but which return TRUE to the native R function is.list. As an example, this includes the multi-component object created by fitting a generalized linear model using ds.glmSLMA. The resultant object saved on each separate server is formally of double class "glm" and "ls" but responds TRUE to is.list(),

Value

namesDS returns to the client-side the names of a list object stored on the server-side.

Author(s)

Amadou Gaye, updated by Paul Burton 25/06/2020

Generate a Basis Matrix for Natural Cubic Splines

Description

This function is based on the native R function ns from the splines package. This function generate the B-spline basis matrix for a natural cubic spline.

Usage

nsDS(x, df, knots, intercept, Boundary.knots)

Arguments

Details

ns is native R is based on the function splineDesign. It generates a basis matrix for representing the family of piecewise-cubic splines with the specified sequence of interior knots, and the natural boundary conditions. These enforce the constraint that the function is linear beyond the boundary knots, which can either be supplied or default to the extremes of the data. A primary use is in modeling formula to directly specify a natural spline term in a model.

Value

A matrix of dimension length(x) * df where either df was supplied or if knots were supplied, df = length(knots) + 1 + intercept. Attributes are returned that correspond to the arguments to ns, and explicitly give the knots, Boundary.knots etc for use by predict.ns(). The object is assigned at each serverside.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Counts the number of missing values

Description

this function just counts the number of missing entries in a vector.

Usage

numNaDS(xvect)

Arguments

Value

an integer, the number of missing values

Author(s)

Gaye, A.

Basis for a piecewise linear spline with meaningful coefficients

Description

This function is based on the native R function qlspline 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

qlsplineDS(x = x, q = q, na.rm = TRUE, marginal = FALSE, names = 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 qlspline wraps lspline and calculates the knot positions to be at quantiles of x. If q is a numerical scalar greater or equal to 2, the quantiles are computed at seq(0, 1, length.out = q + 1)[-c(1, q+1)], i.e. knots are at q-tiles of the distribution of x. Alternatively, q can be a vector of values in [0; 1] specifying the quantile probabilities directly (the vector is passed to argument probs of quantile).

Value

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

Author(s)

Demetris Avraam for DataSHIELD Development Team

Generates quantiles and mean information without maximum and minimum

Description

the probabilities 5 are used to compute the corresponding quantiles.

Usage

quantileMeanDS(xvect)

Arguments

Value

a numeric vector that represents the sample quantiles

Author(s)

Burton, P.; Gaye, A.

rBinomDS serverside assign function

Description

primary serverside assign function called by ds.rBinom

Usage

rBinomDS(n, size = 1, prob = 0.5)

Arguments

Details

Generates the vector of pseudorandom numbers from a binomial distribution in each data source as specified by the arguments of ds.rBinom. This serverside function is effectively the same as the function rbinom() in native R and its arguments are the same.

Value

Writes the pseudorandom number vector with the characteristics specified in the function call as a new serverside vector on the data source on which it has been called. Also returns key information to the clientside: the random seed as specified by you in each source + (if requested) the full 626 length random seed vector this generated in each source (see info for the argument <return.full.seed.as.set>). It also returns a vector reporting the length of the pseudorandom vector created in each source.

Author(s)

Paul Burton for DataSHIELD Development Team

rNormDS serverside assign function

Description

primary serverside assign function called by ds.rNorm

Usage

rNormDS(n, mean = 0, sd = 1, force.output.to.k.decimal.places = 9)

Arguments

Details

Generates the vector of pseudorandom numbers from a normal distribution in each data source as specified by the arguments of ds.rNorm. This serverside function is effectively the same as the function rnorm() in native R and its arguments are the same.

Value

Writes the pseudorandom number vector with the characteristics specified in the function call as a new serverside vector on the data source on which it has been called. Also returns key information to the clientside: the random seed as specified by you in each source + (if requested) the full 626 length random seed vector this generated in each source (see info for the argument <return.full.seed.as.set>). It also returns a vector reporting the length of the pseudorandom vector created in each source.

Author(s)

Paul Burton for DataSHIELD Development Team

rPoisDS serverside assign function

Description

primary serverside assign function called by ds.rPois

Usage

rPoisDS(n, lambda = 1)

Arguments

Details

Generates the vector of pseudorandom numbers (non-negative integers) from a Poisson distribution in each data source as specified by the arguments of ds.rPois. This serverside function is effectively the same as the function rpois() in native R and its arguments are the same.

Value

Writes the pseudorandom number vector with the characteristics specified in the function call as a new serverside vector on the data source on which it has been called. Also returns key information to the clientside: the random seed as specified by you in each source + (if requested) the full 626 length random seed vector this generated in each source (see info for the argument <return.full.seed.as.set>). It also returns a vector reporting the length of the pseudorandom vector created in each source.

Author(s)

Paul Burton for DataSHIELD Development Team

rUnifDS serverside assign function

Description

primary serverside assign function called by ds.rUnif

Usage

rUnifDS(n, min = 0, max = 1, force.output.to.k.decimal.places = 9)

Arguments

Details

Generates the vector of pseudorandom numbers from a uniform distribution in each data source as specified by the arguments of ds.rUnif. This serverside function is effectively the same as the function runif() in native R and its arguments are the same.

Value

Writes the pseudorandom number vector with the characteristics specified in the function call as a new serverside vector on the data source on which it has been called. Also returns key information to the clientside: the random seed as specified by you in each source + (if requested) the full 626 length random seed vector this generated in each source (see info for the argument <return.full.seed.as.set>). It also returns a vector reporting the length of the pseudorandom vector created in each source.

Author(s)

Paul Burton for DataSHIELD Development Team

returns the minimum and maximum of a numeric vector

Description

this function is similar to R function range but instead to not return the real minimum and maximum, the computed values are multiplied by a very small random number.

Usage

rangeDS(xvect)

Arguments

Value

a numeric vector which contains the minimum and the maximum values of the vector

Author(s)

Amadou Gaye, Demetris Avraam for DataSHIELD Development Team

Secure ranking of "V2BR" (vector to be ranked) across all sources

Description

takes key non-disclosive components of the serverside data frame blackbox.output.df over to the clientside to enable global ranking.

Usage

ranksSecureDS1()

Details

Severside aggregate function called by ds.ranksSecure. The non-disclosive components of blackbox.output.df that are transmitted to the clientside are: (1) final values of the "combined real+pseudo data vector" after all seven rounds of encryption have been completed; (2) a set of sequential IDs allocated after sorting the "combined real+pseudo data vector" by value (in ascending order). This allows later re-linkage of values back on the serverside and confirmation that that linkage is correct. 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". Also see the header file for ds.ranksSecure

Value

the non-disclosive elements of blackbox.output.df (see details) on the serverside as a data frame object (called blackbox.output) on the clientside. After processing to create the global ranks across all studies, this is returned to the serverside as the data frame sR4.df using the clientside function ds.dmtC2S

Author(s)

Paul Burton 9th November, 2021

Secure ranking of "V2BR" (vector to be ranked) across all sources

Description

Checks that the data frame produced in creating the initial global ranks (ranks based on real and pseudo-data after the running of blackBoxDS)has the correct dimensions and order as the serverside data frames to which it will now be appended. If either the number of rows or the order of the rows are inconsistent with the pre-existing data frames on the serverside an error message is returned and the processing stops. Then strips out the pseudo-data leaving solely the global ranks based just on the real data

Usage

ranksSecureDS2()

Details

Severside assign function called by ds.ranksSecure. It works on the on the output created by serverside function ranksSecureDS1 and saved on the serverside in data frame sR4.df by ds.dmtC2S. Having checked QA it strips out all rows corresponding to pseudo-data. The resultant data frame contains the following vectors: (1) the fully encrypted V2BR (after application of blackBoxDS);(2) "ID.by.val" the sequential ID associated with the "combined real+pseudo data vector" sorted by value (ascending); (3) "studyid", a vector consisting solely of value n in the nth study; (4) "global.rank" the vector containing global ranks created by the clientside code in ds.ranksSecure after ranksSecureDS1 is called and up to the point where ds.dmtC2S sends sR4.df to the serverside. 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". Also see the header file for ds.ranksSecure

Value

creates a new data frame sR5.df on the serverside containing solely the real data and including key elements needed for next stage of the ranking process. Most crucially these include "global.rank" and "ID.by.val" sorted in ascending order of the magnitude of V2BR

Author(s)

Paul Burton 9th November, 2021

Secure ranking of "V2BR" (vector to be ranked) across all sources

Description

takes key non-disclosive components of the serverside data frame blackbox.ranks.df over to the clientside to enable global re-ranking of the global ranks just applying to the real data (not the pseudo-data).

Usage

ranksSecureDS3()

Details

Severside aggregate function called by ds.ranksSecure. The non-disclosive components of blackbox.ranks.df that are transmitted to the clientside are: (1) final values of the encrypted global ranks vector after all seven rounds of encryption have been completed; (2) a set of sequential IDs allocated to the global ranks vector in each study in their current order based on increasing value of V2BR. This allows later re-linkage of values back on the serverside and confirmation that that linkage is correct. (3) a studyid vector with all values n in the nth study. This facilitates data management on the serverside during the global ranking of global ranks. 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". Also see the header file for ds.ranksSecure

Value

the non-disclosive elements of blackbox.output.df (see details) on the serverside as a data frame object (called sR6.df) on the clientside. After processing within ds.ranksSecure to create the global ranks and global quantiles (of real data only) across all studies, this is returned to the serverside as data frame "global.ranks.quantiles.df" using the clientside function ds.dmtC2S. To illustrate the difference between ranks and quantiles, if there are a total of 1000 original real observations across all studies and one particular observation has the rank 250, it will have quantile value 0.25 (i.e. 25 increasing value). Both ranks and quantiles can have ties. 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". Also see the header file for ds.ranksSecure

Author(s)

Paul Burton 9th November, 2021

Secure ranking of "V2BR" (vector to be ranked) across all sources

Description

Creates a data frame "sR8.df" by cbinding the data frame "blackBox.ranks.df" with the global ranks and global quantiles vectors in "global.ranks.quantiles.df". Performs QA on this matrix and orders the sR8.df data frame according to the argument <ranks.sort.by> in ds.ranksSecure

Usage

ranksSecureDS4(ranks.sort.by)

Arguments

Details

Severside assign function called by ds.ranksSecure. Creates a data frame "sR8.df" by cbinding the data frame "blackBox.ranks.df" with the global ranks and global quantiles vectors in "global.ranks.quantiles.df". Checks that all components of sR8.df have the correct dimensions and are consistent in their ordering. If either the number of rows or the order of the rows are inconsistent with those in "blackBox.ranks.df" an error message is returned and the processing stops. If sR8.df passes all QA tests it is written to the serverside as a data frame with its name identified by the argument <output.ranks.df> in ds.ranksSecure. If that argument is NULL or unspecified the data frame is called "main.ranks.df". The ranksSecureDS4 function also orders the combined data frame (<output.ranks.df>) in one of two ways: if the argument <ranks.sort.by> in ds.ranksSecure is set to "ID.orig" the combined data frame is ordered in the same way as the original V2BR vector; if the argument <ranks.sort.by> is set to vals.orig" the combined data frame is ordered by the magnitude of the values of V2BR (ascending). Having created the data frame (<output.ranks.df>) in this manner it can now be directly cbinded to either the V2BR vector itself or to a data frame, tibble or matrix containing V2BR (assuming they are also in the order corresponding to the argument <ranks.sort.by>) and this combined object can be used as the basis of analysis based on the global ranks or quantiles including a range of types of non-parametric analysis.

Value

Creates the data frame identified by the name given by the argument (<output.ranks.df>) of the ds.ranksSecure function and writes it to the serverside. If the argument <output.ranks.df> is NULL or unspecified the output data frame is called "main.ranks.df". The data frame is ordered according to the argument <ranks.sort.by> in ds.ranksSecure.

Author(s)

Paul Burton 9th November, 2021

Secure ranking of "V2BR" (vector to be ranked) across all sources

Description

Summarises the serverside data frame written by ranksSecureDS4 which is identified by the name given by the argument (<output.ranks.df>) of the ds.ranksSecure function to produce a new output data frame containing only 5 key variables.

Usage

ranksSecureDS5(output.ranks.df)

Arguments

Details

Serverside assign function called by clientside function ds.ranksSecure. Takes the serverside data frame written by ranksSecureDS4 which is identified by the name given by the argument (<output.ranks.df>) of the ds.ranksSecure function. This holds 11 vectors including the final global ranks across all studies and final global quantiles. The data frame is ordered according to the argument <ranks.sort.by> in ds.ranksSecure. The ranksSecureDS5 function then extracts 5 key vectors from the larger data frame to produce a summary data frame that is given a name specified by the argument (<summary.output.ranks.df>) the ds.ranksSecure function. This data frame includes the following components: (1) The values of a sequential ID variable (ID.seq.real.orig) created to lie alongside the original V2BR vector in the same order as that vector was itself ordered. These ID values therefore reflect which row in the original data corresponds to a given row in the output. If the argument <ranks.sort.by> in ds.ranksSecure is set to "ID.orig" the values of the ID.seq.real.orig vector in the output data frame simply run sequentially from 1 to N where N is the number of individuals in the corresponding study. If <ranks.sort.by> is set to "vals.orig" the values of the ID.seq.real.orig vector will be determined by the magnitude of the corresponding V2BR value and will appear to be ordered in a haphazard manner; (2) the original values of V2BR; (3) the global ranks corresponding to the original values in V2BR, with ties reflected appropriately; (4) the global quantiles corresponding to the original values in V2BR, with ties reflected appropriately; (5) a studyid vector in which all elements take the value n in the nth study.

Value

extracts 5 key vectors from the larger data frame created by ranksSecureDS4 to produce a summary data frame that is written to the serverside. It is given a name specified by the argument.

Author(s)

Paul Burton 9th November, 2021

rbindDS called by ds.rbind

Description

serverside assign function that takes a sequence of vector, matrix or data-frame arguments and combines them by row to produce a matrix.

Usage

rbindDS(x.names.transmit = NULL, colnames.transmit = NULL)

Arguments

Details

A sequence of vector, matrix or data-frame arguments is combined row by row to produce a matrix which is written to the serverside. For more details see help for ds.rbind and the native R function rbind.

Value

the object specified by the <newobj> argument of ds.rbind(or default name <rbind.out>) which is written to the serverside. As well as writing the output object as <newobj> on the serverside, 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.cbind() 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

reShapeDS (assign function) called by ds.reShape

Description

Reshapes a data frame containing longitudinal or otherwise grouped data from 'wide' to 'long' format or vice-versa

Usage

reShapeDS(
  data.name,
  varying.transmit,
  v.names.transmit,
  timevar.name,
  idvar.name,
  drop.transmit,
  direction,
  sep
)

Arguments

Details

This function is based on the native R function reshape. It reshapes a data frame containing longitudinal or otherwise grouped data between 'wide' format with repeated measurements in separate columns of the same record and 'long' format with the repeated measurements in separate records. The reshaping can be in either direction

Value

a reshaped data.frame converted from long to wide format or from wide to long format which is written to the serverside and given the name provided as the <newobj> argument of ds.reShape or 'newObject' if no name is specified. In addition, two validity messages are returned to the clientside indicating whether <newobj> has been created in each data source and if so whether it is in a valid form (see header for ds.reShape.

Author(s)

Demetris Avraam, Paul Burton for DataSHIELD Development Team

Recodes the levels of a categorical variables

Description

The functions uses the input factor and generates a new factor with new levels.

Usage

recodeLevelsDS(x = NULL, classes = NULL)

Arguments

Value

a factor vector with the new levels

Author(s)

Gaye, A.

recodeValuesDS an assign function called by ds.recodeValues

Description

This function recodes specified values of elements in a vector into a matched set of alternative specified values.

Usage

recodeValuesDS(
  var.name.text = NULL,
  values2replace.text = NULL,
  new.values.text = NULL,
  missing = NULL
)

Arguments

Details

For all details see the help header for ds.recodeValues

Value

the object specified by the <newobj> argument (or default name '<var.name>_recoded') initially specified in calling ds.recodeValues. The output object (the required recoded variable called <newobj> is written to the serverside.

Author(s)

Paul Burton, Demetris Avraam for DataSHIELD Development Team

repDS called by ds.rep

Description

An assign function which creates a repetitive sequence by repeating an identified scalar, or specified elements of a vector or list. This is analogous to the rep function in native R. The sequence is written as a new object to the serverside

Usage

repDS(
  x1.transmit,
  times.transmit,
  length.out.transmit,
  each.transmit,
  x1.includes.characters,
  source.x1,
  source.times,
  source.length.out,
  source.each
)

Arguments

Details

Further details can be found in the help details for on ds.rep and the following aspects of the help for the function rep in native R also apply (as explained in more detail with exceptions identified in help for ds.rep):

In addition a Details from R help for <rep>:

The default behaviour is as if the call was rep(x, times = 1, length.out = NA, each = 1) Normally just one of the additional arguments is specified, but if 'each' is specified with either of the other two, its replication is performed first, and then that is followed by the replication implied by times or length.out.

If times consists of a single integer, the result consists of the whole input repeated this many times. If times is a vector of the same length as x (after replication by each), the result consists of x[1] repeated times[1] times, x[2] repeated times[2] times and so on. ***Note exception 1 above.

length.out may be given in place of times, in which case x is repeated as many times as is necessary to create a vector of this length. If both are given, length.out takes priority and times is ignored. ***Note exception 3 above.

Non-integer values of times will be truncated towards zero. If times is a computed quantity it is prudent to add a small fuzz or use round. And analogously for each.

Value

the vector containing the specified repetitive sequence and write to the output object defined by the <newobj> argument (or default name seq.vect) which is written to the serverside in each source. 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.matrixDiag 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, 14/10/2019

Replaces the missing values in a vector

Description

This function identifies missing values and replaces them by a value or values specified by the analyst.

Usage

replaceNaDS(xvect, replacements)

Arguments

Details

This function is used when the analyst prefer or requires complete vectors. It is then possible the specify one value for each missing value by first returning the number of missing values using the function numNaDS but in most cases it might be more sensible to replace all missing values by one specific value e.g. replace all missing values in a vector by the mean or median value. Once the missing values have been replaced a new vector is created.

Value

a new vector without missing values

Author(s)

Amadou Gaye, Demetris Avraam for DataSHIELD Development Team

rmDS an aggregate function called by ds.rm

Description

deletes an R object on the serverside

Usage

rmDS(x.names.transmit)

Arguments

Details

this is a serverside function based on the rm() function in native R. It is an aggregate function which may be surprising because it modifies an object on the serverside, and would therefore be expected to be an assign function. However, as an assign function the last step in running it would be to write the modified object as newobj. But this would fail because the effect of the function is to delete the object and so it would be impossible to write it anywhere.

Value

the specified object is deleted from the serverside. If this is successful the message "Object <x.names> successfully deleted" is returned to the clientside (where x.names are the names of the object to be deleted). If the objects to be deleted is already absent on a given source, that source will return the message: "Object to be deleted, i.e. <x.names>, does not exist so does not need deleting".

Author(s)

Paul Burton for DataSHIELD Development Team

Computes sums and means of rows or columns of numeric arrays

Description

The function is similar to R base functions 'rowSums', 'colSums', 'rowMeans' and 'colMeans'.

Usage

rowColCalcDS(dataset, operation)

Arguments

Details

the output is returned to the user only the number of entries in the output vector is greater or equal to the allowed size.

Value

a numeric vector

Author(s)

Gaye, A.

random sampling and permuting of vectors, dataframes and matrices

Description

draws a pseudorandom sample from a vector, dataframe or matrix on the serverside or - as a special case - randomly permutes a vector, dataframe or matrix.

Usage

sampleDS(
  x.transmit,
  size.transmit,
  replace.transmit = NULL,
  prob.transmit = NULL
)

Arguments

Details

Serverside assign function sampleDS called by clientside function ds.sample. Based on the native R function sample() but deals slightly differently with data.frames and matrices. For further details see help for ds.sample and native R help for sample().

Value

the object specified by the <newobj> argument (or default name 'newobj.sample') which is written to the serverside. For further details see help for ds.sample and native R help for sample().

Author(s)

Paul Burton, for DataSHIELD Development Team, 15/4/2020

Calculates the coordinates of the data to be plot

Description

This function uses two disclosure control methods to generate non-disclosive coordinates that are returned to the client that generates the non-disclosive scatter plots.

Usage

scatterPlotDS(x, y, method.indicator, k, noise)

Arguments

Details

If the user chooses the deterministic approach, the function finds the k-1 nearest neighbours of each data point in a 2-dimensional space. The nearest neighbours are the data points with the minimum Euclidean distances from the point of interest. Each point of interest and its k-1 nearest neighbours are then used for the calculation of the coordinates of the centroid of those k points. Centroid here is referred to the centre of mass, i.e. the x-coordinate of the centroid is the average value of the x-coordinates of the k nearest neighbours and the y-coordinate of the centroid is the average of the y-coordinates of the k nearest neighbours. If the user chooses the probabilistic approach, the function adds random noise to $x$ and $y$ separately. Each random noise follows a normal distribution with zero mean and variance equal to 10 disclosure we fix the random number generator in a value that is specified by the input variables. Thus the function returns always the same noisy data for a given pair of variables.

Value

a list with the x and y coordinates of the data to be plot

Author(s)

Demetris Avraam for DataSHIELD Development Team

seqDS a serverside assign function called by ds.seq

Description

assign function seqDS called by ds.seq

Usage

seqDS(
  FROM.value.char,
  TO.value.char,
  BY.value.char,
  LENGTH.OUT.value.char,
  ALONG.WITH.name
)

Arguments

Details

An assign function that uses the native R function seq() to create any one of a flexible range of sequence vectors that can then be used to help manage and analyse data. As it is an assign function the resultant vector is written as a new object into all of the specified data source servers. Please see "details" for ds.seq for more information about allowable combinations of arguments etc.

Value

the object specified by the <newobj> argument of ds.seq (or its default name newObj) which is written to the serverside. As well as writing the output object as <newobj> on the serverside, 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.seq() 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, 17/9/2019

setSeedDs called by ds.setSeed, ds.rNorm, ds.rUnif, ds.rPois and ds.rBinom

Description

An aggregate serverside function that primes the pseudorandom number generator in a data source

Usage

setSeedDS(seedtext = NULL, kind = NULL, normal.kind = NULL)

Arguments

Details

setSeedDS is effectively equivalent to the native R function set.seed() and so the help for that function can provide many additional details. The only very minor difference is that the first argument of setSeedDS, <seedtext> takes the integer priming seed in character format. However, for the user that integer is still specified directly as an integer as the <seed.as.integer> argument of one of the clientside functions ds.setSeed, ds.rNorm ..... Each of these clientside functions coerces the integer to character format calls setSeedDS and the first active line of code in setSeedDS converts the character string back to an integer and treats it as the first argument <seed> of the native R function set.seed(). The two other arguments of set.seed() in native R, <kind> and <normal.kind> are both defaulted by specifying them as NULL. This defaulting is hard wired into the setSeedDS function and as this cannot be changed by the analyst it means that setSeedDS is much less flexible than native R's set.seed() function. If any DataSHIELD user requires some aspect of this flexibility returned the development team can be approached, but unless you are actually doing theoretical work with random number generators it is likely that the

Value

Sets the values of the vector of integers of length 626 known as .Random.seed on each data source that is the true current state of the random seed in each source.

Author(s)

Paul Burton for DataSHIELD Development Team

Calculates the skewness of a numeric variable

Description

This function calculates the skewness of a numeric variable for each study separately.

Usage

skewnessDS1(x, method)

Arguments

Details

The function calculates the skewness of an input variable x with three different methods. The method is specified by the argument method in the client-side ds.skewness function.

Value

a list including the skewness of the input numeric variable, the number of valid observations and the study-side validity message.

Author(s)

Demetris Avraam, for DataSHIELD Development Team

Calculates the skewness of a numeric variable

Description

This function calculates summary statistics that are returned to the client-side and used for the estimation of the combined skewness of a numeric variable across all studies.

Usage

skewnessDS2(x, global.mean)

Arguments

Details

The function calculates the sum of squared differences between the values of x and the global mean of x across all studies, the sum of cubed differences between the values of x and the global mean of x across all studies and the number of valid observations of the input variable x.

Value

a list including the sum of cubed differences between the values of x and the global mean of x across all studies, the sum of squared differences between the values of x and the global mean of x across all studies, the number of valid observations (i.e. the length of x after excluding missing values), and a validity message indicating indicating a valid analysis if the number of valid observations are above the protection filter nfilter.tab or invalid analysis otherwise.

Author(s)

Demetris Avraam, for DataSHIELD Development Team

Computes the square root values of the input variable

Description

This function is similar to R function sqrt.

Usage

sqrtDS(x)

Arguments

Details

The function computes the square root values of an input numeric or integer vector.

Value

the object specified by the newobj argument of ds.sqrt (or default name sqrt.newobj) which is written to the server-side. The output object is of class numeric or integer.

Author(s)

Demetris Avraam for DataSHIELD Development Team

Breaks down a dataframe or a factor into its sub-classes

Description

The function takes a categorical vector or dataframe as input and generates subset(s) vectors or dataframes for each category. Subsets are considered invalid if they hold between 1 and 4 observations.

Usage

subsetByClassDS(data = NULL, variables = NULL)

Arguments

Details

If the input data object is a dataframe it is possible to specify the variables to subset on. If a subset is not 'valid' all its the values are reported as missing (i.e. NA), the name of the subsets is labelled as '_INVALID'. If no variables are specified to subset on, the dataframe will be subset on each of its factor variables. And if none of the columns holds a factor variable a message is issued as output. A message is also issued as output if the input vector is not of type factor.

Value

a list which contains the subsetted datasets

Author(s)

Gaye, A.

Generates a valid subset of a table or a vector

Description

The function uses the R classical subsetting with squared brackets '[]' and allows also to subset using a logical operator and a threshold. The object to subset from must be a vector (factor, numeric or character) or a table (data.frame or matrix).

Usage

subsetDS(
  dt = NULL,
  complt = NULL,
  rs = NULL,
  cs = NULL,
  lg = NULL,
  th = NULL,
  varname = NULL
)

Arguments

Details

If the input data is a table: The user specifies the rows and/or columns to include in the subset if the input object is a table; the columns can be referred to by their names. The name of a vector (i.e. a variable) can also be provided with a logical operator and a threshold (see example 3). If the input data is a vector: when the parameters 'rows', 'logical' and 'threshold' are all provided the last two are ignored ( 'rows' has precedence over the other two parameters then). If the requested subset is not valid (i.e. contains less than the allowed number of observations), the subset is not generated, rather a table or a vector of missing values is generated to allow for any subsequent process using the output of the function to proceed after informing the user via a message.

Value

a subset of the vector, matrix or dataframe as specified is stored on the server side

Author(s)

Gaye, A.

Creates 1-dimensional contingency tables

Description

This function generates a 1-dimensional table where potentially disclosive cells. (based on the set threshold) are replaced by a missing value ('NA').

Usage

table1DDS(xvect)

Arguments

Details

It generates a 1-dimensional tables where valid (non-disclosive) 1-dimensional tables are defined as data from sources where no table cells have counts between 1 and the set threshold. When the output table is invalid all cells but the total count are replaced by missing values. Only the total count is visible on the table returned to the client site. A message is also returned with the 1-dimensional; the message says "invalid table - invalid counts present" if the table is invalid and 'valid table' otherwise.

Value

a list which contains two elements: 'table', the 1-dimensional table and 'message' a message which informs about the validity of the table.

Author(s)

Gaye A.

table2DDS (aggregate function) called by ds.table2D

Description

This function generates a 2-dimensional contingency table where potentially disclosive cells (based on a set threshold) are replaced by a missing value ('NA').

Usage

table2DDS(xvect, yvect)

Arguments

Details

It generates 2-dimensional contingency tables where valid (non-disclosive) tables are defined as those where none of their cells have counts between 1 and the set threshold "nfilter.tab". When the output table is invalid all cells except the total counts are replaced by missing values. Only the total counts are visible on the table returned to the client side. A message is also returned with the 2-dimensional table; the message says "invalid table - invalid counts present" if the table is invalid and 'valid table' otherwise.

Value

a list which contains two elements: 'table', the 2-dimensional table and 'message' a message which informs about the validity of the table.

Author(s)

Amadou Gaye, Paul Burton, Demetris Avraam for DataSHIELD Development Team

tableDS is the first of two serverside aggregate functions called by ds.table

Description

creates 1-dimensional, 2-dimensional and 3-dimensional tables using the table function in native R.

Usage

tableDS(
  rvar.transmit,
  cvar.transmit,
  stvar.transmit,
  rvar.all.unique.levels.transmit,
  cvar.all.unique.levels.transmit,
  stvar.all.unique.levels.transmit,
  exclude.transmit,
  useNA.transmit,
  force.nfilter.transmit
)

Arguments

Details

this serverside function is the workhorse of ds.table - creating the table requested in the format specified by ds.table. For more information see help for ds.table in DataSHIELD and the table function in native R.

Value

For information see help for ds.table

Author(s)

Paul Burton for DataSHIELD Development Team, 13/11/2019

tableDS.assign is the serverside assign function called by ds.table

Description

helps creates 1-dimensional, 2-dimensional and 3-dimensional tables using the table function in native R.

Usage

tableDS.assign(
  rvar.transmit,
  cvar.transmit,
  stvar.transmit,
  rvar.all.unique.levels.transmit,
  cvar.all.unique.levels.transmit,
  stvar.all.unique.levels.transmit,
  exclude.transmit,
  useNA.transmit
)

Arguments

Details

If the <table.assign> argument of ds.table is set to TRUE, this assign function writes the the table requested in the format specified by ds.table function as an object named by the <newobj> argument of ds.table. For more information see help for ds.table in DataSHIELD and the table function in native R.

Value

For information see help for ds.table

Author(s)

Paul Burton for DataSHIELD Development Team, 13/11/2019

tableDS is the second of two serverside aggregate functions called by ds.table

Description

Helps creates 1-dimensional, 2-dimensional and 3-dimensional tables using the table function in native R.

Usage

tableDS2(newobj, rvar.transmit, cvar.transmit, stvar.transmit)

Arguments

Details

If the <table.assign> argument of ds.table is set to TRUE, this aggregate function returns non-disclosive information about the table object written to the serverside by tableDS.assign. For more information see help for ds.table, tableDS.assign and tableDS in DataSHIELD and the table function in native R.

Value

For information see help for ds.table

Author(s)

Paul Burton for DataSHIELD Development Team, 13/11/2019

tapplyDS called by ds.tapply

Description

Apply one of a selected range of functions to summarize an outcome variable over one or more indexing factors and write the resultant summary to the clientside

Usage

tapplyDS(X.name, INDEX.names.transmit, FUN.name)

Arguments

Details

see details for ds.tapply function

Value

an array of the summarized values created by the tapplyDS function. This array is returned to the clientside. It has the same number of dimensions as INDEX.

Author(s)

Paul Burton, Demetris Avraam for DataSHIELD Development Team

tapplyDS.assign called by ds.tapply.assign

Description

Apply one of a selected range of functions to summarize an outcome variable over one or more indexing factors and write the resultant summary as a newobj on the serverside

Usage

tapplyDS.assign(X.name, INDEX.names.transmit, FUN.name)

Arguments

Details

see details for ds.tapply.assign function

Value

an array of the summarized values created by the tapplyDS.assign function. This array is written as a newobj on the serverside. It has the same number of dimensions as INDEX.

Author(s)

Paul Burton, Demetris Avraam for DataSHIELD Development Team

testObjExistsDS

Description

The server-side function called by ds.testObjExists

Usage

testObjExistsDS(test.obj.name = NULL)

Arguments

Details

Tests whether a given object exists in all sources. It is called at the end of all recently written assign functions to check the new (assigned) object has been created in all sources

Value

List with 'test.obj.exists' and 'test.obj.class'

Author(s)

Burton PR

unListDS a serverside assign function called by ds.unList

Description

this function is based on the native R function unlist which coerces an object of list class back to the class it was when it was coerced into a list

Usage

unListDS(x.name)

Arguments

Details

See details of the native R function unlist. This function represents a substantive restructuring of an earlier version created by Amadou Gaye. For further details of its working please see 'details' in the help for ds.unList.

Value

the object specified by the newobj argument of the ds.unList function (or by default "unlist.newobj" if the newobj argument is NULL). This is written to the serverside. As well as writing the output object as newobj on the serverside, 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.seq 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. Because the outcome object from ds.unList is typically a list object with no names, if there are no errors in creating it the message returned from ds.message("<newobj>") in each study will read "Outcome object is a list without names. So a studysideMessage may be hidden. Please check output is OK". This suggests that - in the case of this specific function - one should check as far as one can the nature of the output from a call to ds.unList - e.g. ds.class, ds.length etc

Author(s)

Amadou Gaye (2016), Paul Burton (19/09/2019) for DataSHIELD Development Team

Applies the unique method to a server-side variable.

Description

This function is similar to R function unique.

Usage

uniqueDS(x.name.transmit = NULL)

Arguments

Details

The function computes the uniques values of a variable.

Value

the object specified by the newobj argument which is written to the server-side.

Author(s)

Stuart Wheater for DataSHIELD Development Team

Computes the variance of vector

Description

Calculates the variance.

Usage

varDS(xvect)

Arguments

Details

if the length of input vector is less than the set filter a missing value is returned.

Value

a list, with the sum of the input variable, the sum of squares of the input variable, the number of missing values, the number of valid values, the number of total length of the variable, and a study message indicating whether the number of valid is less than the disclosure threshold

Author(s)

Amadou Gaye, Demetris Avraam, for DataSHIELD Development Team

Creates a vector on the server-side.

Description

This function is similar to R function c.

Usage

vectorDS(...)

Arguments

Details

The function computes the vectors values.

Value

the object specified by the newobj argument which is written to the server-side.

Author(s)

Stuart Wheater for DataSHIELD Development Team