Type:	Package
Title:	'DataSHIELD' Implementation for 'Opal'
Version:	1.4.0
Depends:	R (≥ 3.5), opalr (≥ 3.0), DSI (≥ 1.5), methods
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 for 'Opal', which is the data integration application for biobanks by 'OBiBa'. Participant data, once collected from any data source, must be integrated and stored in a central data repository under a uniform model. 'Opal' is such a central repository. It can import, process, validate, query, analyze, report, and export data. 'Opal' is the reference implementation of the 'DataSHIELD' infrastructure.
License:	LGPL-2.1 | LGPL-3 [expanded from: LGPL (≥ 2.1)]
URL:	https://github.com/datashield/DSOpal/, https://datashield.github.io/DSOpal/, https://www.obiba.org, https://www.obiba.org/pages/products/opal/, https://www.datashield.org, https://academic.oup.com/ije/article/43/6/1929/707730, https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008880
BugReports:	https://github.com/datashield/DSOpal/issues/
RoxygenNote:	7.2.1
Encoding:	UTF-8
Collate:	'DSOpal-package.R' 'OpalDriver.R' 'OpalConnection.R' 'OpalResult.R' 'datashield.aggregate.r' 'datashield.assign.r' 'datashield.command.r' 'datashield.method.r' 'datashield.symbol.r' 'datashield.workspace.r' 'logindata.R' 'utils.R'
NeedsCompilation:	no
Packaged:	2022-10-06 09:05:19 UTC; yannick
Author:	Yannick Marcon [aut, cre], Becca Wilson [ctb], OBiBa group [cph]
Maintainer:	Yannick Marcon <yannick.marcon@obiba.org>
Repository:	CRAN
Date/Publication:	2022-10-06 09:30:02 UTC

DSOpal: 'DataSHIELD' Implementation for 'Opal'

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 for 'Opal', which is the data integration application for biobanks by 'OBiBa'. Participant data, once collected from any data source, must be integrated and stored in a central data repository under a uniform model. 'Opal' is such a central repository. It can import, process, validate, query, analyze, report, and export data. 'Opal' is the reference implementation of the 'DataSHIELD' infrastructure.

Author(s)

Maintainer: Yannick Marcon yannick.marcon@obiba.org (ORCID)

Other contributors:

• Becca Wilson (ORCID) [contributor]

• OBiBa group info@obiba.org [copyright holder]

See Also

Useful links:

• https://github.com/datashield/DSOpal/

• https://datashield.github.io/DSOpal/

• https://www.obiba.org

• https://www.obiba.org/pages/products/opal/

• https://www.datashield.org

• https://academic.oup.com/ije/article/43/6/1929/707730

• https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008880

• Report bugs at https://github.com/datashield/DSOpal/issues/

Data aggregation

Description

Aggregates the expression result using the specified aggregation method in the current Datashield session. This operation is asynchronous and non blocking.

Usage

.datashield.aggregate(opal, expr, async = TRUE)

Arguments

Value

The R command ID to be used to retrieve the command result (when async) or the agregated value.

Data assignment

Description

Assign a Opal value to a R symbol in the current Datashield session. This operation is asynchronous and non blocking.

Usage

.datashield.assign.expr(opal, symbol, value, async = TRUE)

Arguments

Value

The R command ID if the async flag is TRUE and if the wait flag is FALSE and if Opal version is at least 2.1, NULL otherwise.

Resource data assignment

Description

Assign a Opal value to a R symbol in the current Datashield session. This operation is asynchronous and non blocking.

Usage

.datashield.assign.resource(opal, symbol, value, async = TRUE)

Arguments

Value

The R command ID if the async flag is TRUE and if the wait flag is FALSE and if Opal version is at least 2.1, NULL otherwise.

Table data assignment

Description

Assign a Opal value to a R symbol in the current Datashield session. This operation is asynchronous and non blocking.

Usage

.datashield.assign.table(
  opal,
  symbol,
  value,
  variables = NULL,
  missings = FALSE,
  identifiers = NULL,
  id.name = NULL,
  tibble = FALSE,
  async = TRUE
)

Arguments

Value

The R command ID if the async flag is TRUE and if the wait flag is FALSE and if Opal version is at least 2.1, NULL otherwise.

Get an asynchronous command

Description

Get an asynchronous R commands in the remote Datashield session.

Usage

.datashield.command(opal, id, wait = FALSE)

Arguments

Get result of an asynchronous command

Description

Get the result of an asynchronous R commands in the remote Datashield session. The command is removed from the remote Datashield session after this call.

Usage

.datashield.command_result(opal, id, wait = FALSE)

Arguments

Remove an asynchronous command

Description

Remove an asynchronous R commands in the remote Datashield session.

Usage

.datashield.command_rm(opal, id)

Arguments

List the asynchronous commands

Description

Get the list of asynchronous R commands in the remote Datashield session.

Usage

.datashield.commands(opal)

Arguments

Remove all asynchronous commands

Description

Remove all asynchronous R commands in the remote Datashield session.

Usage

.datashield.commands_rm(opal)

Arguments

List Datashield methods

Description

Get available Datashield methods of a given type.

Usage

.datashield.methods(opal, type = "aggregate")

Arguments

List Datashield profiles

Description

Get available Datashield profiles.

Usage

.datashield.profiles(opal)

Arguments

Remove a R symbol

Description

Remove a symbol from the current Datashield session.

Usage

.datashield.rm(opal, symbol)

Arguments

List R symbols

Description

Get the R symbols available after the datashield.assign calls in the current Datashield session.

Usage

.datashield.symbols(opal)

Arguments

Restore a saved workspace in the current DataSHIELD session.

Description

Restore a saved workspace in the current DataSHIELD session.

Usage

.datashield.workspace_restore(opal, ws)

Arguments

Remove a DataSHIELD workspace from a opal.

Description

Remove a DataSHIELD workspace from a opal.

Usage

.datashield.workspace_rm(opal, ws)

Arguments

Save current session in a DataSHIELD workspace.

Description

Save current session in a DataSHIELD workspace.

Usage

.datashield.workspace_save(opal, ws)

Arguments

Get the DataSHIELD workspaces.

Description

Get the DataSHIELD workspaces.

Usage

.datashield.workspaces(opal)

Arguments

Turn expression into character strings.

Description

Turn expression into character strings.

Usage

.deparse(expr)

Extract R session Id from opal object, create a new Datashield R session if not found.

Description

Extract R session Id from opal object, create a new Datashield R session if not found.

Usage

.getDatashieldSessionId(opal)

Extract absolute path to the pem file

Description

Extract absolute path to the pem file

Usage

.getPEMFilePath(pem, directory = "~/.ssh")

Create a new Datashield R session in Opal.

Description

Create a new Datashield R session in Opal.

Usage

.newDatashieldSession(opal, restore = NULL)

Remove a Datashield R session in Opal.

Description

Remove a Datashield R session in Opal.

Usage

.rmDatashieldSession(opal, save = NULL)

Create a Opal driver

Description

Convenient function for creating a OpalDriver object.

Usage

Opal()

Class OpalConnection.

Description

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

Class OpalDriver with constructor Opal.

Description

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

Class OpalResult.

Description

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

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 'OpalConnection'
dsAggregate(conn, expr, async = TRUE)

Arguments

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "username", "password", "https://opal.example.org")
dsAssignTable(con, "D", "test.CNSIM")
dsAggregate(con, as.symbol("meanDS(D$WEIGHT)"))
dsDisconnect(con)

## End(Not run)

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 'OpalConnection'
dsAssignExpr(conn, symbol, expr, async = TRUE)

Arguments

Value

A OpalResult-class object.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsAssignExpr(con, "C", as.symbol("c(1, 2, 3)"))
dsDisconnect(con)

## End(Not run)

Assign a resource

Description

Assign a Opal resource in the DataSHIELD R session.

Usage

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

Arguments

Value

A OpalResult-class object.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsAssignResource(con, "D", "test.CNSIM")
dsDisconnect(con)

## End(Not run)

Assign a table

Description

Assign a Opal table in the DataSHIELD R session.

Usage

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

Arguments

Value

A OpalResult-class object.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsAssignTable(con, "D", "test.CNSIM")
dsDisconnect(con)

## End(Not run)

Connect to a Opal server

Description

Connect to a Opal server, with provided credentials. Does not create a DataSHIELD R session, only retrieves user profile.

Usage

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

Arguments

Value

A OpalConnection-class object.

Examples

## Not run: 
con <- dsConnect(DSOpal::Opal(), "server1", "username", "password", "https://opal.example.org")
con
dsDisconnect(con)

## End(Not run)

Disconnect from a Opal server

Description

Disconnect from a Opal server 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 'OpalConnection'
dsDisconnect(conn, save = NULL)

Arguments

Examples

## Not run: 
con <- dsConnect(DSOpal::Opal(), "server1", "username", "password", "https://opal.example.org")
con
dsDisconnect(con)

## End(Not run)

Fetch the result

Description

Fetch the DataSHIELD operation result.

Usage

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

Arguments

Value

TRUE if table exists.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsAssignExpr(con, "C", as.symbol("c(1, 2, 3)"))
res <- dsAggregate(con, as.symbol("length(C)"))
length <- dsFetch(res)
dsDisconnect(con)

## End(Not run)

Get result info

Description

Get the information about a command (if still available).

Usage

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

Arguments

Value

The result information, including its status.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsAssignExpr(con, "C", as.symbol("c(1, 2, 3)"))
res <- dsAggregate(con, as.symbol("length(C)"))
dsGetInfo(res)
dsDisconnect(con)

## End(Not run)

Verify Opal resource

Description

Verify Opal resource exist and can be accessible for performing DataSHIELD operations.

Usage

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

Arguments

Value

TRUE if the resource exists.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsHasResource(con, "test.CNSIM")
dsDisconnect(con)

## End(Not run)

Verify Opal table

Description

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

Usage

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

Arguments

Value

TRUE if table exists.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsHasTable(con, "test.CNSIM")
dsDisconnect(con)

## End(Not run)

Opal asynchronous support

Description

List that Opal supports asynchronicity on all DataSHIELD operations.

Usage

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

Arguments

Value

The named list of logicals detailing the asynchronicity support.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsIsAsync(con)
dsDisconnect(con)

## End(Not run)

Get whether the operation is completed

Description

Get the information about a command (if still available) and return TRUE if the command was completed successfully or not. Always TRUE for synchronous operations.

Usage

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

Arguments

Value

A logical indicating the command completion.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsAssignExpr(con, "C", as.symbol("c(1, 2, 3)"))
res <- dsAggregate(con, as.symbol("length(C)"))
dsIsCompleted(res)
dsDisconnect(con)

## End(Not run)

Keep connection with a Opal server alive

Description

Makes a dummy web service request.

Usage

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

Arguments

Examples

## Not run: 
con <- dsConnect(DSOpal::Opal(), "server1", "username", "password", "https://opal.example.org")
dsKeepAlive(con)
dsDisconnect(con)

## End(Not run)

List methods

Description

List methods defined in the DataSHIELD configuration.

Usage

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

Arguments

Value

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

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsListMethods(con)
dsDisconnect(con)

## End(Not run)

List packages

Description

List packages defined in the DataSHIELD configuration.

Usage

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

Arguments

Value

A data frame with columns: name, version.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsListPackages(con)
dsDisconnect(con)

## End(Not run)

List profiles

Description

List profiles defined in the DataSHIELD configuration.

Usage

## S4 method for signature 'OpalConnection'
dsListProfiles(conn)

Arguments

Value

A list containing the "available" character vector of profile names and the "current" profile (in case a default one was assigned).

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsListProfiles(con)
dsDisconnect(con)

## End(Not run)

List Opal resources

Description

List Opal resources that may be accessible for performing DataSHIELD operations.

Usage

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

Arguments

Value

The fully qualified names of the resources.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsListResources(con)
dsDisconnect(con)

## End(Not run)

List R symbols

Description

List symbols living in the DataSHIELD R session.

Usage

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

Arguments

Value

A character vector.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsAssignTable(con, "D", "test.CNSIM")
dsListSymbols(con)
dsDisconnect(con)

## End(Not run)

List Opal tables

Description

List Opal tables that may be accessible for performing DataSHIELD operations.

Usage

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

Arguments

Value

The fully qualified names of the tables.

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsListTables(con)
dsDisconnect(con)

## End(Not run)

List workspaces

Description

List workspaces saved in the data repository.

Usage

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

Arguments

Value

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

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsListWorkspaces(con)
dsDisconnect(con)

## End(Not run)

Restore workspace

Description

Restore workspace from the data repository.

Usage

## S4 method for signature 'OpalConnection'
dsRestoreWorkspace(conn, name)

Arguments

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsListWorkspaces(con)
dsRestoreWorkspace(con, "foo")
dsDisconnect(con)

## End(Not run)

Remove a R symbol

Description

Remoe a symbol living in the DataSHIELD R session.

Usage

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

Arguments

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsAssignTable(con, "D", "test.CNSIM")
dsRmSymbol(con, "D")
dsDisconnect(con)

## End(Not run)

Remove a workspace

Description

Remove a workspace on the data repository.

Usage

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

Arguments

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsSaveWorkspace(con, "foo")
dsListWorkspaces(con)
dsRmWorkspace(con, "foo")
dsListWorkspaces(con)
dsDisconnect(con)

## End(Not run)

Save workspace

Description

Save workspace on the data repository.

Usage

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

Arguments

Examples

## Not run: 
con <- dbConnect(DSOpal::Opal(), "server1",
  "username", "password", "https://opal.example.org")
dsSaveWorkspace(con, "foo")
dsListWorkspaces(con)
dsDisconnect(con)

## End(Not run)

DataSHIELD login data file

Description

DataSHIELD login data file based on Opal demo server, with CNSIM simulated data. The CNSIM datasets contain synthetic data based on a model derived from the participants of the 1958 Birth Cohort, as part of the obesity methodological development project. These datasets do contain some NA values. Note that the Opal demo server is rebuilt every day and is possibly not accessible.

Details

References

https://opal-demo.obiba.org