Opal is the reference implementation of the DataSHIELD infrastructure. All the DataSHIELD administration tasks can be performed programmatically using functions starting with
See also the Opal DataSHIELD Administration documentation to learn how to administrate DataSHIELD using the graphical user interface.
Setup the connection with Opal:
Opal can handle clusters of R servers. R packages are handled at the cluster level (because all the R servers in a cluster are expected to be identical). See Opal and R server documentation.
List installed DataSHIELD R packages:
Install a DataSHIELD R package from the configured CRAN repositories (most likely the DataSHIELD repo):
R packages which source code is one GitHub can be installed directly:
When developing a new DataSHIELD R package, it can be built and installed as follow (from the root of the R package source directory):
To remove a DataSHIELD R package:
Note that removing a package does not update the DataSHIELD settings of the associated profiles. See the following sections to administrate the profiles and their settings.
A DataSHIELD profile is based on a R servers cluster. In the most simple setup, there is only one cluster of one R server and this cluster is called
default, and the profile is named the same.
It is possible to define several profiles based on the same cluster. The benefit of doing this is to:
To list the DataSHIELD profiles:
To create a new DataSHIELD profile, to initialize it the DataSHIELD settings as declared by the installed packages and to enable it, use the following.
# ensure the profile does not exist if (dsadmin.profile_exists(o, "demo")) dsadmin.profile_delete(o, "demo") # create a profile, disabled dsadmin.profile_create(o, "demo", cluster = "default") # make only dsBase and resourcer packages visible dsadmin.profile_init(o, "demo", packages = c("dsBase", "resourcer")) # ready to be used dsadmin.profile_enable(o, "demo")
When a DataSHIELD R package is installed but should be used only by a restricted group of users, proceed as follow:
The DataSHIELD settings are defined per profile (DataSHIELD Profiles section). The settings can be minimally initialized by reading the declared settings from the installed DataSHIELD R packages. They can also be amended afterwards.
The DataSHIELD methods define the allowed function calls and their mapping to a server side function call.
To list the aggregation functions:
Fully custom settings can be defined (useful for developers).
A simple test of our custom
hello() function would be:
library(DSOpal) builder <- DSI::newDSLoginBuilder() builder$append(server = "study1", url = "https://opal-demo.obiba.org", user = "administrator", password = "password", profile = "demo") logindata <- builder$build() conns <- DSI::datashield.login(logins = logindata) # call the hello() function on the R server datashield.aggregate(conns, expr = quote(hello('friends'))) datashield.logout(conns)
The DataSHIELD R options affects the behaviour of some methods.
To modify an R option:
An advanced setting, mostly for backward compatibility issues, is the possibility to chose which R parser should be used by Opal when validating the submitted R code (remember that only a subset of the R language is allowed). See datashield4j library documentation for possible values.
To set the legacy R parser:
The DataSHIELD requires permissions: permissions to access the data (whether these are in a table or a resource) and permission to use the DataSHIELD service.
To facilitate permissions maintenance, create users in appropriate group(s). Groups can represent data access and DataSHIELD service access.
To set some DataSHIELD-compatible permissions (view without accessing individual-level data) to each tables of a project, use the following:
Similarly, permissions to use all the resources of a project in a DataSHIELD context is even simpler:
Then grant permission to use the DataSHIELD service to a group of users:
Note that it is also possible to grant permission to access a specific DataSHIELD profile (see Profiles section).
Good practice is to free server resources by sending a logout request: