Type: Package
Version: 2.0.9
Title: 'DataSHIELD' Client for 'MOLGENIS Armadillo'
Description: 'DataSHIELD' is an infrastructure and series of R packages that enables the remote and 'non-disclosive' analysis of sensitive research data. This package is the 'DataSHIELD' interface implementation to analyze data shared on a 'MOLGENIS Armadillo' server. 'MOLGENIS Armadillo' is a light-weight 'DataSHIELD' server using a file store and an 'RServe' server.
Maintainer: Mariska Slofstra <m.k.slofstra@umcg.nl>
Depends: R (≥ 3.6), DSI (≥ 1.3.0), MolgenisAuth (≥ 0.0.25),
Imports: methods, httr, stringr, utils, base64enc, urltools, dplyr, jsonlite
Suggests: dsBaseClient (≥ 6.0), knitr, mockery, testthat (≥ 2.1.0), tibble, rmarkdown, metafor
License: LGPL-2.1 | LGPL-3 [expanded from: LGPL (≥ 2.1)]
URL: https://github.com/molgenis/molgenis-r-datashield/, https://molgenis.github.io/molgenis-r-datashield/
BugReports: https://github.com/molgenis/molgenis-r-datashield/issues/
RoxygenNote: 7.3.1
VignetteBuilder: knitr
Encoding: UTF-8
Collate: 'ArmadilloDriver.R' 'ArmadilloConnection.R' 'ArmadilloOAuth.R' 'ArmadilloResult.R' 'DSMolgenisArmadillo-package.R' 'utils.R'
Additional_repositories: https://cran.obiba.org/
NeedsCompilation: no
Packaged: 2024-07-05 13:43:57 UTC; root
Author: Mariska Slofstra ORCID iD [aut, cre], Sido Haakma ORCID iD [aut], Tommy de Boer ORCID iD [aut], Fleur Kelpin ORCID iD [aut], MOLGENIS org [cph, fnd]
Repository: CRAN
Date/Publication: 2024-07-09 07:50:08 UTC

DSMolgenisArmadillo: 'DataSHIELD' Client for 'MOLGENIS Armadillo'

Description

'DataSHIELD' is an infrastructure and series of R packages that enables the remote and 'non-disclosive' analysis of sensitive research data. This package is the 'DataSHIELD' interface implementation to analyze data shared on a 'MOLGENIS Armadillo' server. 'MOLGENIS Armadillo' is a light-weight 'DataSHIELD' server using a file store and an 'RServe' server.

Author(s)

Maintainer: Mariska Slofstra m.k.slofstra@umcg.nl (ORCID)

Authors:

Other contributors:

See Also

Useful links:

Class ArmadilloConnection.

Description

An Armadillo connection implementing the DataSHIELD Interface (DSI) DSConnection-class.

Slots

name

The name of the connection

handle

The handle used to connect with the server

user

The username used to authenticate

cookies

The cookies set by the server

token

An optional authentication token (JWT)

Class ArmadilloDriver with constructor armadillo

Description

An Armadillo DataSHIELD Service Driver implementing the DataSHIELD Interface (DSI) DSDriver-class. This class should always be initialized with the armadillo function. It returns a singleton that allows you to connect to Armadillo

Class ArmadilloResult.

Description

An Armadillo result implementing the DataSHIELD Interface (DSI) DSResult-class.

Slots

conn

The connection used to create this result

rval

The result

Create an Armadillo DataSHIELD Service driver

Description

Convenience function for creating a [ArmadilloDriver] object.

Usage

armadillo()

Get ID Token

Description

Get an ID token to log in on an Armadillo server

Usage

armadillo.get_token(server)

Arguments

server

the URL of the Armadillo server

Value

The ID token string

Aggregate data

Description

Aggregate some data from the DataSHIELD R session using a valid R expression. The aggregation expression must satisfy the data repository's DataSHIELD configuration.

Usage

## S4 method for signature 'ArmadilloConnection'
dsAggregate(conn, expr, async = TRUE)

Arguments

conn

ArmadilloConnection-class object.

expr

Expression to evaluate.

async

Whether the result of the call should be retrieved asynchronously. When TRUE (default) the calls are parallelized over the connections, when the connection supports that feature, with an extra overhead of requests.

Assign the result of an expression

Description

Assign a result of the execution of an expression in the DataSHIELD R session.

Usage

## S4 method for signature 'ArmadilloConnection'
dsAssignExpr(conn, symbol, expr, async = TRUE)

Arguments

conn

ArmadilloConnection-class object.

symbol

Name of the R symbol.

expr

A R expression with allowed assign functions calls.

async

Whether the result of the call should be retrieved asynchronously. When TRUE (default) the calls are parallelized over the connections, when the connection supports that feature, with an extra overhead of requests.

Value

A ArmadilloResult-class object.

Assign a resource

Description

Assign a resource in the DataSHIELD R session.

Usage

## S4 method for signature 'ArmadilloConnection'
dsAssignResource(conn, symbol, resource, async = TRUE)

Arguments

conn

An object that inherits from DSConnection-class.

symbol

Name of the R symbol.

resource

Fully qualified name of a resource reference in the data repository.

async

Whether the result of the call should be retrieved asynchronously.

Value

A ArmadilloResult-class object.

Assign a table

Description

Assign a R-data.frame in the DataSHIELD R session.

Usage

## S4 method for signature 'ArmadilloConnection'
dsAssignTable(
  conn,
  symbol,
  table,
  variables = NULL,
  missings = FALSE,
  identifiers = NULL,
  id.name = NULL,
  async = TRUE
)

Arguments

conn

ArmadilloConnection-class object.

symbol

Name of the R symbol.

table

Fully qualified name of the table.

variables

The variables to load.

missings

Not supported

identifiers

Not supported

id.name

Not supported

async

When set, do not wait for the result.

Value

A ArmadilloResult-class object.

Connect to an Armadillo DataSHIELD service

Description

Connect to an Armadillo DataSHIELD service, with provided credentials.

Usage

## S4 method for signature 'ArmadilloDriver'
dsConnect(
  drv,
  name,
  restore = NULL,
  username = "",
  password = "",
  token = "",
  url,
  profile = "default",
  opts = list(),
  ...
)

Arguments

drv

ArmadilloDriver-class class object.

name

Name of the connection, which must be unique among all the DataSHIELD connections.

restore

Workspace name to be restored in the newly created DataSHIELD R session.

username

The username to authenticate with.

password

The password to authenticate with.

token

The ID token to authenticate with.

url

URL of the server.

profile

the profile to select, default "default"

opts

Curl options as described by httr (call httr::httr_options() for details). Can be provided by "Armadillo.opts" option.

...

Unused, needed for compatibility with generic.

Value

A ArmadilloConnection-class object.

Disconnect from an Armadillo DataSHIELD Service

Description

Disconnect from an Armadillo DataSHIELD Service and release all R resources. If a workspace ID is provided, the DataSHIELD R session will be saved before being destroyed.

Usage

## S4 method for signature 'ArmadilloConnection'
dsDisconnect(conn, save = NULL)

Arguments

conn

ArmadilloConnection-class class object

save

Save the DataSHIELD R session with provided ID (must be a character string).

See Also

dsDisconnect

Fetch the result

Description

Fetch the DataSHIELD operation result.

Usage

## S4 method for signature 'ArmadilloResult'
dsFetch(res)

Arguments

res

ArmadilloResult-class object.

Value

TRUE if table exists.

Get connection info

Description

Get information about a connection.

Usage

## S4 method for signature 'ArmadilloConnection'
dsGetInfo(dsObj, ...)

Arguments

dsObj

ArmadilloConnection-class class object

...

Unused, needed for compatibility with generic.

Value

The connection information. This should report the version of the data repository application ('repo.version') and its name ('repo.name'), the database name ('dbname'), username, ('username'), host ('host'), port ('port'), etc. It MAY also include any other arguments related to the connection (e.g., thread id, socket or TCP connection type). It MUST NOT include the password.

Get driver info

Description

Get information about a driver.

Usage

## S4 method for signature 'ArmadilloDriver'
dsGetInfo(dsObj, ...)

Arguments

dsObj

ArmadilloDriver-class class object

...

Unused, needed for compatibility with generic.

Value

The connection information. This returns the version of the package ('driver.version'). There is no underlying client library.

Get result info

Description

Await completion and get the information about a command (if still available).

Usage

## S4 method for signature 'ArmadilloResult'
dsGetInfo(dsObj, ...)

Arguments

dsObj

ArmadilloResult-class class object

...

Unused, needed for compatibility with generic.

Value

The result information. This should include the R expression being executed ('expression') and if the query is complete ('{ "status" = "COMPLETED" }').

Verify resource exists.

Description

Verify resource exists.

Usage

## S4 method for signature 'ArmadilloConnection'
dsHasResource(conn, resource)

Arguments

conn

ArmadilloConnection-class class object.

resource

The identifier of the resource

Value

TRUE if resource exists.

Verify table exist and can be accessible for performing DataSHIELD operations.

Description

Verify table exist and can be accessible for performing DataSHIELD operations.

Usage

## S4 method for signature 'ArmadilloConnection'
dsHasTable(conn, table)

Arguments

conn

ArmadilloConnection-class class object.

table

The identifier of the table

Value

TRUE if table exists.

Armadillo DataShield Service asynchronous support

Description

List of DataSHIELD operations on which Armadillo DataSHIELD Service supports asynchronicity.

Usage

## S4 method for signature 'ArmadilloConnection'
dsIsAsync(conn)

Arguments

conn

ArmadilloConnection-class class object

Details

When a DSResult-class object is returned on aggregation or assignment operation, the raw result can be accessed asynchronously, allowing parallelization of DataSHIELD calls over multpile servers. The returned named list of logicals will specify if asynchronicity is supported for: aggregation operation ('aggregate'), table assignment operation ('assignTable'), resource assignment operation ('assignResource') and expression assignment operation ('assignExpr').

Value

The named list of logicals detailing the asynchronicity support.

Get whether the operation is completed

Description

Get whether the result from a previous assignment or aggregation operation was completed, either with a successful status or a failed one. This call must not wait for the completion, immediate response is expected. Once the result is identified as being completed, the raw result the operation can be got directly.

Usage

## S4 method for signature 'ArmadilloResult'
dsIsCompleted(res)

Arguments

res

ArmadilloResult-class object.

Value

TRUE if operation is completed.

Keep a connection alive

Description

As the DataSHIELD sessions are working in parallel, this function helps at keeping idle connections alive while others are working. Any communication failure must be silently processed.

Usage

## S4 method for signature 'ArmadilloConnection'
dsKeepAlive(conn)

Arguments

conn

ArmadilloConnection-class class object

Value

NULL, invisibly

List methods

Description

List methods defined in the DataSHIELD configuration.

Usage

## S4 method for signature 'ArmadilloConnection'
dsListMethods(conn, type = "aggregate")

Arguments

conn

ArmadilloConnection-class class object

type

Type of the method: "aggregate" (default) or "assign".

Value

A data.frame with columns: name, type ('aggregate' or 'assign'), class ('function' or 'script'), value, package, version.

List packages

Description

List packages with their versions defined in the DataSHIELD configuration.

Usage

## S4 method for signature 'ArmadilloConnection'
dsListPackages(conn)

Arguments

conn

ArmadilloConnection-class class object

Value

A data.frame with columns: name, version.

List Armadillo DataSHIELD Service resources

Description

List Armadillo DataSHIELD Service resources that may be accessible for performing DataSHIELD operations.

Usage

## S4 method for signature 'ArmadilloConnection'
dsListResources(conn)

Arguments

conn

ArmadilloConnection-class class object

Value

The fully qualified names of the resources.

See Also

dsListResources

List R symbols

Description

List symbols living in the DataSHIELD R session.

Usage

## S4 method for signature 'ArmadilloConnection'
dsListSymbols(conn)

Arguments

conn

ArmadilloConnection-class class object

Value

A character vector.

List Armadillo DataSHIELD Service tables

Description

List Armadillo DataSHIELD Service tables that may be accessible for performing DataSHIELD operations.

Usage

## S4 method for signature 'ArmadilloConnection'
dsListTables(conn)

Arguments

conn

ArmadilloConnection-class class object

Value

The fully qualified names of the tables.

See Also

dsListTables

List workspaces

Description

List workspaces saved in the data repository.

Usage

## S4 method for signature 'ArmadilloConnection'
dsListWorkspaces(conn)

Arguments

conn

ArmadilloConnection-class class object

Value

A data.frame with columns: name, lastAccessDate, size, user.

Remove an R symbol

Description

Remove a symbol living in the DataSHIELD R session. After removal, the data identified by the symbol will not be accessible in the DataSHIELD R session on the server side.

Usage

## S4 method for signature 'ArmadilloConnection'
dsRmSymbol(conn, symbol)

Arguments

conn

ArmadilloConnection-class class object

symbol

Name of the R symbol.

Remove a workspace

Description

Remove a workspace on the data repository.

Usage

## S4 method for signature 'ArmadilloConnection'
dsRmWorkspace(conn, name)

Arguments

conn

ArmadilloConnection-class class object

name

Name of the workspace.

Save workspace

Description

Save workspace on the data repository.

Usage

## S4 method for signature 'ArmadilloConnection'
dsSaveWorkspace(conn, name)

Arguments

conn

ArmadilloConnection-class class object

name

Name of the workspace.