Package 'DSOpal'

Title: '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.
Authors: Yannick Marcon [aut, cre] , Becca Wilson [ctb] , OBiBa group [cph]
Maintainer: Yannick Marcon <[email protected]>
License: LGPL (>= 2.1)
Version: 1.5.0
Built: 2025-02-09 04:44:54 UTC
Source: https://github.com/datashield/dsopal

Help Index

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

conn

OpalConnection-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.

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

conn

OpalConnection-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 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

conn

OpalConnection-class object.
symbol

Name of the R symbol.
resource

Fully qualified name of a resource in Opal.
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 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

conn

OpalConnection-class object.
symbol

Name of the R symbol.
table

Fully qualified name of a table in Opal.
variables

List of variable names or Javascript expression that selects the variables of a table (ignored if value does not refere to a table). See javascript documentation: https://opaldoc.obiba.org/en/latest/magma-user-guide/methods.html
missings

If TRUE, missing values will be pushed from Opal to R, default is FALSE. Ignored if value is an R expression.
identifiers

Name of the identifiers mapping to use when assigning entities to R (from Opal 2.0).
id.name

Name of the column that will contain the entity identifiers. If not specified, the identifiers will be the data frame row names. When specified this column can be used to perform joins between data frames.
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 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

drv

OpalDriver-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

User name in opal(s).
password

User password in opal(s).
token

Personal access token (since opal 2.15, ignored if username is specified).
url

Opal url or list of opal urls. Can be provided by "opal.url" option.
opts

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

The DataSHIELD R server profile (affects the R packages available and the applied configuration). If not provided or not supported, default profile will be applied.
...

Unused, needed for compatibility with generic.

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

conn

OpalConnection-class class object
save

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

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

res

OpalResult-class object.

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

dsObj

OpalResult-class class object
...

Unused, needed for compatibility with generic.

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

conn

OpalConnection-class class object.
resource

The fully qualified name of the resource.

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

conn

OpalConnection-class class object.
table

The fully qualified name of the table.

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

conn

OpalConnection-class class object

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

res

OpalResult-class object.

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

conn

OpalConnection-class class object

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

conn

OpalConnection-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.

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

conn

OpalConnection-class class object

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

conn

OpalConnection-class class object

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

conn

OpalConnection-class class object

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

conn

OpalConnection-class class object

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

conn

OpalConnection-class class object

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

conn

OpalConnection-class class object

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

conn

OpalConnection-class class object
name

Name of the workspace.

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

conn

OpalConnection-class class object
symbol

Name of the R symbol.

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

conn

OpalConnection-class class object
name

Name of the workspace.

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

conn

OpalConnection-class class object
name

Name of the workspace.

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

Field Description Type Note
server Server/study name char
url Server/study URL char Opal demo URL
user User name char
password User password char
table Table unique name char CNSIM tables
driver Connection driver char OpalDriver

References

https://opal-demo.obiba.org

Create a Opal driver

Description

Convenient function for creating a OpalDriver object.

Usage

Opal()