21 Tips and tricks

The user can see in this link how to create and install an Opal server. Next we illustrate how to deal with some of the basics for setting up a server to be used within DataSHIELD environment.

In order to do that, we are using our Opal demo server available here: https://opal-demo.obiba.org/

This is the how an Opal looks like once the user enters the credentials:

  • username: administrator
  • password: password

Opal demo main page

21.1 How to create a new project into OPAL

21.1.1 Manually

The tab Projects (top-left) goes to the projects available in the Opal demo

Opal demo projects

A new project can be created by clicking on +Add Project tab. Then this information must be filled in

Adding a new project to Opal

21.1.2 Using R

A project can be created using the following R code:

library(opalr)
o <- opal.login(username="administrator", password="password",
                url="https://opal-demo.obiba.org")

# A general purpose project, with a data storage
opal.project_create(o, "projectName", database="dbName")

# A project that can hold only resources and views (no persisted data)
opal.project_create(o, "projectName")

opal.logout(o)

See also the other opal.project_* functions.

21.2 How to upload a new resource into OPAL

21.2.1 Manually

Once a new project has been created, a new resource can be uploaded by clicking on project’s name. In this case, let us assume that we are working on RSRC project that has been created to illustrate the main examples in this bookdown. After clicking on that project this window will appear

Tables, variables and resources from an Opal project

Here we can observe that this project contains 16 resources a no tables or variables. We can add a new resource by clicking on the “link tab” (see red circle)

Going to the resources of a given project

Then a new resource can be added by clicking on the +Add Resource tab

Adding a resource of a given project

Then this window will appear and information for your resource must be filled in

Adding a resource of a given project

The different types of resources have been described Chapter 7

21.2.2 Using R

A resource can be added to a project by a simple function call, assuming that you know how to express the URL to the resource:

library(opalr)
o <- opal.login("administrator","password", 
                url="https://opal-demo.obiba.org")

opal.resource_create(o, "RSRC", "CNSIM3", 
  url = "opal+https://opal-demo.obiba.org/ws/files/projects/RSRC/CNSIM3.zip", 
  format = "csv", secret = "EeTtQGIob6haio5bx6FUfVvIGkeZJfGq")

# to test the resource assignment
opal.assign.resource(o, "client", "RSRC.CNSIM3")
opal.execute(o, "class(client)")

opal.logout(o)

See also the other opal.resource_*functions.

21.3 How to install DataSHIELD packages into OPAL server

21.3.1 Manually

Administration tab at Opal

The tab Administration (red circle in the previous figure) allows the user access to the administration page

Administration tab at Opal

The DataSHIELD tab goes to the DataSHIELD administration details

Managing DataSHIELD packages in Opal

The tab +Add Package allow the user to install a DataSHIELD package either from the DataSHIELD repository or any other GitHub site

Install DataSHIELD packages in Opal

21.3.2 Using R

The user can install DataSHIELD R packages from CRAN or GitHub using the following R code:

library(opalr)
o <- opal.login(username="administrator", password="password",
                url="https://opal-demo.obiba.org")

# CRAN
dsadmin.install_package(o, "dsBase")
# GitHub
dsadmin.install_github_package(o, "packageName", username="orgOrUserName")

opal.logout(o)

When developing a new DataSHIELD package, it can be convenient to directly upload the built package archive for being installed on the R server side. This can be done as follow:

library(opalr)
o <- opal.login(username="administrator", password="password",
                url="https://opal-demo.obiba.org")

# build and install the package archive
packageArchivePath <- devtools::build(pkg="/path/to/the/packageName")
dsadmin.install_local_package(o, path=packageArchivePath)

opal.logout(o)

21.4 How to install R packages into OPAL server

21.4.1 Manually

All the dependencies in a DataSHIELD package are automatically installed when installing it on the Opal Server. If necessary the user can also use the +Install button from the Administration/R tab

Install DataSHIELD packages in Opal

21.4.2 Using R

The user can install R packages from CRAN, Bioconductor or GitHub using the following R code:

library(opalr)
o <- opal.login(username="administrator", password="password",
                url="https://opal-demo.obiba.org")

# CRAN
oadmin.install_package(o, "cranPackageName")
# Bioconductor
oadmin.install_bioconductor_package(o, "biocPackageName")
# GitHub
oadmin.install_github_package(o, "packageName", username="orgOrUserName", ref = "branchOrTagName")

opal.logout(o)