Help for package opalr

Version:

3.4.2

Title:

'Opal' Data Repository Client and 'DataSHIELD' Utils

Depends:

R (≥ 3.1), httr

Imports:

jsonlite, readr, mime, progress, labelled, tibble

Suggests:

e1071, knitr, knitrBootstrap, rmarkdown, testthat

Description:

Data integration Web application for biobanks by 'OBiBa'. 'Opal' is the core database application for biobanks. 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 typically used in a research center to analyze the data acquired at assessment centres. Its ultimate purpose is to achieve seamless data-sharing among biobanks. This 'Opal' client allows to interact with 'Opal' web services and to perform operations on the R server side. 'DataSHIELD' administration tools are also provided.

License:

GPL-3

URL:

https://github.com/obiba/opalr/, https://www.obiba.org/opalr/, https://www.obiba.org/pages/products/opal/, https://doi.org/10.1093/ije/dyx180, https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008880, https://datashield.org/

BugReports:

https://github.com/obiba/opalr/issues/

RoxygenNote:

7.3.1

VignetteBuilder:

knitr

Encoding:

UTF-8

NeedsCompilation:

Packaged:

2024-09-18 06:56:32 UTC; yannick

Author:

Yannick Marcon

[aut, cre], Amadou Gaye

[ctb], OBiBa group [cph]

Maintainer:

Yannick Marcon <yannick.marcon@obiba.org>

Repository:

CRAN

Date/Publication:

2024-09-18 07:20:02 UTC

opalr: 'Opal' Data Repository Client and 'DataSHIELD' Utils

Description

Author(s)

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

Other contributors:

Amadou Gaye (ORCID) [contributor]
OBiBa group info@obiba.org [copyright holder]

Permsissions (ACLs) into a data frame.

Description

Permsissions (ACLs) into a data frame.

Usage

.aclsToDataFrame(perms, acls)

Turns a value into 0/1 numeric.

Description

Turns a value into 0/1 numeric.

Usage

.as.zeroOne(value)

Constructs the value for the Authorization header

Description

Constructs the value for the Authorization header

Usage

.authorizationHeader(username, password)

Turn expression into character strings.

Description

Turn expression into character strings.

Usage

.deparse(expr)

Extract JSON

Description

Extract JSON

Usage

.extractJsonField(json, fields = NULL, isArray = TRUE)

Extract label for locale. If not found, fallback to undefined language label (if any).

Description

Extract label for locale. If not found, fallback to undefined language label (if any).

Usage

.extractLabel(
  locale = "en",
  labels = list(),
  localeKey = "locale",
  valueKey = "value"
)

Extract opalsid from cookie data frame.

Description

Extract opalsid from cookie data frame.

Usage

.extractOpalSessionId(cookies)

Wrapper of httr::content()

Description

Wrapper of httr::content()

Usage

.getContent(opal, response)

Extract absolute path to the pem file

Description

Extract absolute path to the pem file

Usage

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

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

Description

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

Usage

.getRSessionId(opal)

Get all R session in Opal.

Description

Get all R session in Opal.

Usage

.getSessions(opal)

Handle error response

Description

Handle error response

Usage

.handleError(opal, response)

Default request response handler.

Description

Default request response handler.

Usage

.handleResponse(opal, response)

Default request response Location handler.

Description

Default request response Location handler.

Usage

.handleResponseLocation(opal, response)

Process response with default handler or the provided one

Description

Process response with default handler or the provided one

Usage

.handleResponseOrCallback(opal, response, callback = NULL)

Verbose option

Description

Verbose option

Usage

.is.verbose()

Check if response content is empty.

Description

Check if response content is empty.

Usage

.isContentEmpty(content)

Simple transformation function of a list into a JSON object/array.

Description

Simple transformation function of a list into a JSON object/array.

Usage

.listToJson(l)

Create a new progress instance with default settings.

Description

Create a new progress instance with default settings.

Usage

.newProgress(
  format = "  :what [:bar] :percent /:elapsed",
  clear = getOption("opal.progress.clear", FALSE),
  total,
  width = 100
)

Create a new R session in Opal.

Description

Create a new R session in Opal.

Usage

.newSession(opal, restore = NULL, profile = NULL)

Description

Create the opal object

Usage

.opal.login(
  username,
  password,
  token,
  url,
  opts = list(),
  profile = profile,
  restore = NULL
)

Remove a Opal session (logout)

Description

Remove a Opal session (logout)

Usage

.rmOpalSession(opal)

Remove a R session from Opal.

Description

Remove a R session from Opal.

Usage

.rmRSession(opal, save = FALSE)

Returns a list r such that r[[i]] == l[[i]][field] for all i:length(l)

Description

Returns a list r such that r[[i]] == l[[i]][field] for all i:length(l)

Usage

.select(l, field)

Output the progress status if option "datashield.progress" is allows to.

Description

Output the progress status if option "datashield.progress" is allows to.

Usage

.tickProgress(progress, tokens = list())

Constructs the value for the X-Opal-Auth header

Description

Constructs the value for the X-Opal-Auth header

Usage

.tokenHeader(token)

Utility method to build urls. Concatenates all arguments and adds a '/' separator between each element

Description

Utility method to build urls. Concatenates all arguments and adds a '/' separator between each element

Usage

.url(opal, ...)

Verbose flag

Description

Verbose flag

Usage

.verbose()

Set variable annotation with a taxonomy term

Description

Apply or remove an annotation from a set of variables.

Usage

dictionary.annotate(
  tibble,
  variables = NULL,
  taxonomy = "Mlstr_area",
  vocabulary,
  term
)

Arguments

tibble

Tibble to be annotated.

variables

A character vector of variable names to be annotated. If NULL or empty, all the columns of the tibble will be annotated.

taxonomy

The taxonomy to which the vocabulary belongs. If NULL, the annotation is a simple attribute (i.e. without a taxonomy reference).

vocabulary

The vocabulary to which the term belongs.

term

The term to apply. If NULL, the annotation will be deleted.

Value

The annotated tibble

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
cqx <- opal.table_get(o, "CPTP", "Cag_coreqx")
cqx <- dictionary.annotate(cqx, 
  variables = c("A_SDC_EDU_LEVEL", "A_SDC_EDU_LEVEL_AGE"), 
  taxonomy = "Mlstr_area", 
  vocabulary = "Sociodemographic_economic_characteristics", 
  term = "Education")
opal.logout(o)

## End(Not run)

Set variable annotation with Harmonization Status term

Description

Apply or remove an harmonization status annotation from a set of variables. The harmonization status is described by the "status" vocabulary in the "Mlstr_harmo" taxonomy.

Usage

dictionary.annotate.harmo_status(tibble, variables = NULL, status)

Arguments

tibble

Tibble to be annotated.

variables

A character vector of variable names to be annotated. If NULL or empty, all the columns of the tibble will be annotated.

status

The harmonization status to apply: 'complete', 'undetermined', 'impossible' or 'na'. If NULL, the annotation will be deleted.

Value

The annotated tibble

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
cqx <- opal.table_get(o, "CPTP", "Cag_coreqx")
cqx <- dictionary.annotate.harmo_status(cqx, 
  variables = c("A_SDC_EDU_LEVEL", "A_SDC_EDU_LEVEL_AGE"), 
  status = "complete")
opal.logout(o)

## End(Not run)

List the annotations

Description

List the annotations of each of the variables.

Usage

dictionary.annotations(
  tibble,
  variables = NULL,
  taxonomy = NULL,
  vocabulary = NULL
)

Arguments

tibble

Tibble to be annotated

variables

A character vector of variable names to be inspected. If NULL or empty, all the columns of the tibble will be inspected.

taxonomy

Filter by taxonomy name(s) (if provided).

vocabulary

Filter by vocabulary name(s) (if provided).

Value

A data frame in long format (one row per annotation).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
cqx <- opal.table_get(o, "CPTP", "Cag_coreqx")
annot <- dictionary.annotations(cqx, taxonomy = "Mlstr_harmo", vocabulary = "status")
opal.logout(o)

## End(Not run)

Apply the dictionary to a tibble

Description

Apply the dictionary described in a Opal Excel format as attributes of the tibble's columns.

Usage

dictionary.apply(tibble, variables, categories = NULL, merge = FALSE)

Arguments

tibble

Tibble to be decorated.

variables

A data frame with one row per variable (column name) and then one column per property/attribute.

categories

A data frame with one row per category (columns variable and name) and then column per property/attribute.

merge

Either append attributes to existing ones or replace them. Default is FALSE, for dictionary consistency.

Examples

## Not run: 
data <- tibble::as_tibble(mtcars)
variables <- tibble::tribble(
  ~name, ~valueType, ~`label:en`, ~`label:fr`,  ~`Namespace::Name`, ~unit, ~repeatable, ~index,
  "mpg", "decimal", "Mpg label", "Mpg libellé",  "Value1", "years", 0, 1,
  "cyl", "decimal", "Cyl label", "Cyl libellé",  "Value2", "kg/m2", 0, 2,
  "disp", "decimal", "Disp label", "Disp libellé", NA, NA, 1, 3
)
categories <- tibble::tribble(
  ~variable, ~name, ~missing, ~`label:en`, ~`label:fr`,
  "cyl", "4", 0, "Four", "Quatre",
  "cyl", "6", 0, "Six", "Six",
  "cyl", "8", 1, "Height", "Huit"
)
data <- dictionary.apply(data, variables, categories)

## End(Not run)

Inspect the dictionary of a tibble

Description

Inspect the data dictionary, checking for inconsistencies. Error is raised when the identifiers column cannot be found.

Usage

dictionary.inspect(tibble, id.name = "id", warn = TRUE)

Arguments

tibble

Tibble to be inspected.

id.name

The name of the column representing the entity identifiers. Default is 'id'.

warn

Print warning messages. Default is TRUE.

Value

TRUE if inspection is successful, FALSE otherwise.

Examples

## Not run: 
# prepare datasets of visits, several visits for one patient
visits <- tibble::tribble(
~id, ~patient_id, ~sex, ~visit_date,
1, 1, "M", as.Date("2020-01-01"),
2, 2, "F", as.Date("2020-01-02"),
3, 3, "M", as.Date("2020-01-03"),
4, 3, "M", as.Date("2020-01-04"))

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

# save visits dataset
opal.table_save(o, visits, "RSRC", "visits", type = "Visit", force = TRUE)

# get visit and make it a dataset of patients 
patients <- opal.table_get(o, "RSRC", "visits", id.name = "id")
# set dataset IDs
patients$visit_id <- patients$id
patients$id <- patients$patient_id
patients$patient_id <- NULL
patients

# save patients dataset, there should be a warning that some variables are not repeatable
# while there are patients with multiple data lines
opal.table_save(o, patients, "RSRC", "patients", type = "Participant", force = TRUE)

opal.logout(o)

## End(Not run)

Get DataSHIELD activity

Description

Get the recorded DataSHIELD session metrics.

Usage

dsadmin.activity(
  opal,
  user = NULL,
  profile = NULL,
  from = NULL,
  to = NULL,
  df = TRUE
)

Arguments

opal

Opal connection object.

user

Optional user name.

profile

Optional profile name.

from

Optional start date.

to

Optional end date.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# all sessions metrics
dsadmin.activity(o)
# user and profile specific session metrics
dsadmin.activity(o, user = 'dsuser', profile = 'default')
# user sessions in a time range
dsadmin.activity(o, user = "dsuser", from = "2022-07-01", to = "2023-01-01")
opal.logout(o)

## End(Not run)

Get DataSHIELD activity summary

Description

Get the recorded DataSHIELD session metrics, grouped by profile and user.

Usage

dsadmin.activity_summary(
  opal,
  user = NULL,
  profile = NULL,
  from = NULL,
  to = NULL,
  df = TRUE
)

Arguments

opal

Opal connection object.

user

Optional user name.

profile

Optional profile name.

from

Optional start date.

to

Optional end date.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# all sessions metrics
dsadmin.activity_summary(o)
# user and profile specific session metrics
dsadmin.activity_summary(o, user = 'dsuser', profile = 'default')
# user sessions in a time range
dsadmin.activity_summary(o, user = "dsuser", from = "2022-07-01", to = "2023-01-01")
opal.logout(o)

## End(Not run)

Get a DataSHIELD method

Description

Get a DataSHIELD method

Usage

dsadmin.get_method(opal, name, type = "aggregate", profile = NULL)

Arguments

opal

Opal object or list of opal objects.

name

Name of the method, as it is accessed by DataSHIELD users.

type

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

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.get_method(o, 'class')
opal.logout(o)

## End(Not run)

Get DataSHIELD methods

Description

Get DataSHIELD methods

Usage

dsadmin.get_methods(opal, type = "aggregate", profile = NULL)

Arguments

opal

Opal object or list of opal objects.

type

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

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.get_methods(o)
opal.logout(o)

## End(Not run)

Get the DataSHIELD options

Description

Get the DataSHIELD options

Usage

dsadmin.get_options(opal, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.get_options(o)
opal.logout(o)

## End(Not run)

Install a DataSHIELD package from GitHub

Description

Install a package from a DataSHIELD source repository on GitHub.

Usage

dsadmin.install_github_package(
  opal,
  pkg,
  username = "datashield",
  ref = "master",
  profile = NULL
)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

username

GitHub username/organization of the git repository. Default is 'datashield'.

ref

Desired git reference (could be a commit, tag, or branch name). Default is 'master'.

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Value

TRUE if installed

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.install_github_package(o, 'dsOmics', username='isglobal-brge')
opal.logout(o)

## End(Not run)

Install a DataSHIELD package from a local archive file

Description

Install a package from a package archive file, resulting from the build of a server-side DataSHIELD package. This will upload the archive file and run its installation in the R server.

Usage

dsadmin.install_local_package(opal, path, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

path

Path to the package archive, ending with .

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# install a pre-built local archive file
dsadmin.install_local_package(o, '~/dsExposome_1.0.0.tar.gz')
# or build archive file from local package source (in current working folder)
dsadmin.install_local_package(o, devtools::build())
opal.logout(o)

## End(Not run)

Install a DataSHIELD package

Description

Install a package from DataSHIELD public package repository or (if Git reference and GitHub username is provided) from DataSHIELD source repository on GitHub.

Usage

dsadmin.install_package(
  opal,
  pkg,
  githubusername = NULL,
  ref = NULL,
  profile = NULL
)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

githubusername

GitHub username of git repository. If NULL (default), try to install from DataSHIELD package repository.

ref

Desired git reference (could be a commit, tag, or branch name). If NULL (default), try to install from DataSHIELD package repository.

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Value

TRUE if installed

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.install_package(o, 'dsBase')
opal.logout(o)

## End(Not run)

Check DataSHIELD package

Description

Check if a DataSHIELD package is installed.

Usage

dsadmin.installed_package(opal, pkg, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Value

TRUE if installed

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.installed_package(o, 'dsBase')
opal.logout(o)

## End(Not run)

Get DataSHIELD logs

Description

The DataSHIELD log is structured as follows:

Usage

dsadmin.log(opal, all = TRUE)

Arguments

opal

Opal connection object.

all

Get all or only latest log messages.

Details

Common fields

timestamp: when action is logged
version: not used
message: human readable message
logger_name: name of the log channel
thread_name: java thread name
level: log level (TRACE, DEBUG, INFO, WARN, ERROR)
level_value: log level numeric value
ip: ip origin of the request, when available
ds_id: unique DS session ID
ds_profile: DS profile name (available after the R server session is created, can be after authentication)
username: DS user name
r_duration: time spent by the remote R server action (all except PARSE)
r_size: R result serialized object size in bytes
ds_action: DS operation (OPEN, CLOSE, PARSE, ASSIGN, AGGREGATE, LS, RM, WS_SAVE, WS_RESTORE)

DS operations fields

OPEN: DS session opened (note: happens after successful authentication as R server session creation is deferred)
CLOSE: DS session closed
PARSE: R expression parsed
- ds_map: DS function mappings used in the R parser, separated by semicolons when several functions are called
- ds_script_in: R script as sent by DS user
- ds_script_out: R script rewritten by opal, to be evaluated
ASSIGN:
- ds_symbol: assigned symbol name
- ds_table: table name that is assigned
- ds_resource: resource name that is assigned
- ds_eval: assign R expression that is evaluated
AGGREGATE:
- ds_eval: aggregate R expression that is evaluated
LS: R symbols listed
RM: R symbol removed
- ds_symbol: symbol name to remove
WS_SAVE:
- ds_ws: workspace name
WS_RESTORE:
- ds_ws: workspace name

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.log(o)
opal.logout(o)

## End(Not run)

Get DataSHIELD package description

Description

Get DataSHIELD package description

Usage

dsadmin.package_description(opal, pkg, fields = NULL, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

fields

A character vector giving the fields to extract from each package's DESCRIPTION file in addition to the default ones, or NULL (default). Unavailable fields result in NA values.

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.package_description(o, 'dsBase')
opal.logout(o)

## End(Not run)

Get DataSHIELD package descriptions

Description

Get DataSHIELD package descriptions

Usage

dsadmin.package_descriptions(opal, fields = NULL, df = TRUE, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

fields

A character vector giving the fields to extract from each package's DESCRIPTION file in addition to the default ones, or NULL (default). Unavailable fields result in NA values.

df

Return a data.frame (default is TRUE)

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Value

The DataSHIELD package descriptions as a data.frame or a list

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.package_descriptions(o)
opal.logout(o)

## End(Not run)

Get the DataSHIELD permissions

Description

Get the permissions that were applied to the DataSHIELD service.

Usage

dsadmin.perm(opal)

Arguments

opal

Opal connection object.

Value

A data.frame with columns: subject, type, permission

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.perm_add(o, c('andrei', 'valentina'), 'user', 'use')
dsadmin.perm(o)
dsadmin.perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Add or update a DataSHIELD permission

Description

Add or update a permission on the DataSHIELD service.

Usage

dsadmin.perm_add(opal, subject, type = "user", permission)

Arguments

opal

Opal connection object.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

permission

The permission to apply: use or administrate.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.perm_add(o, c('andrei', 'valentina'), 'user', 'use')
dsadmin.perm(o)
dsadmin.perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Delete a DataSHIELD permission

Description

Delete a permission that was applied to the DataSHIELD service. Silently returns when there is no such permission.

Usage

dsadmin.perm_delete(opal, subject, type = "user")

Arguments

opal

Opal connection object.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.perm_add(o, c('andrei', 'valentina'), 'user', 'use')
dsadmin.perm(o)
dsadmin.perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Get a DataSHIELD profile

Description

Note that getting a specific DataSHIELD profile details is not allowed for regular DataSHIELD users when the profile has no restricted access. This function is for profiles editors only (system administrators or DataSHIELD administrators).

Usage

dsadmin.profile(opal, name)

Arguments

opal

Opal object.

name

Name of the profile.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.profile(o, name = 'default')
opal.logout(o)

## End(Not run)

Restrict or open access to a DataSHIELD profile

Description

When access is restricted, only users (or group of users) with this profile use permissions will be allowed to use this profile. When access is not restricted, all DataSHIELD users are allowed to use this profile. See also dsadmin.profile_perm.

Usage

dsadmin.profile_access(opal, name, restricted = TRUE)

Arguments

opal

Opal object.

name

Name of the profile.

restricted

Default value is TRUE.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.profile_create(o, name = 'survival', cluster = 'demo')
dsadmin.profile_access(o, name = 'survival', restricted = TRUE)
opal.logout(o)

## End(Not run)

Create a DataSHIELD profile

Description

The created DataSHIELD profile will not be enabled and no access restrictions is applied.

Usage

dsadmin.profile_create(opal, name, cluster = "default", rParser = NULL)

Arguments

opal

Opal object.

name

Name of the profile.

cluster

Name of the R servers cluster to which the profile will be attached to. Default value is 'default'.

rParser

Version of the DataSHIELD R parser that applies to this profile. If not specified, the system's default one will be used. A valid version would be one of 'v1' or 'v2'.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.profile_create(o, name = 'survival', cluster = 'demo')
opal.logout(o)

## End(Not run)

Delete a DataSHIELD profile

Description

Delete a DataSHIELD profile

Usage

dsadmin.profile_delete(opal, name)

Arguments

opal

Opal object.

name

Name of the profile.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.profile_create(o, name = 'survival', cluster = 'demo')
dsadmin.profile_delete(o, name = 'survival')
opal.logout(o)

## End(Not run)

Enable or disable a DataSHIELD profile

Description

Enable or disable a DataSHIELD profile

Usage

dsadmin.profile_enable(opal, name, enabled = TRUE)

Arguments

opal

Opal object.

name

Name of the profile.

enabled

Default value is TRUE.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.profile_create(o, name = 'survival', cluster = 'demo')
dsadmin.profile_enable(o, name = 'survival', enabled = TRUE)
opal.logout(o)

## End(Not run)

Check a DataSHIELD profile exists

Description

Check a DataSHIELD profile exists

Usage

dsadmin.profile_exists(opal, name)

Arguments

opal

Opal object.

name

Name of the profile.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
if (!dsadmin.profile_exists(o, name = 'survival'))
  dsadmin.profile_create(o, name = 'survival', cluster = 'demo')
opal.logout(o)

## End(Not run)

Initialize a DataSHIELD profile

Description

Clean the DataSHIELD's profile settings from all methods and options (including custom ones). These settings are then repopulated with installed DataSHIELD R packages settings, optionaly filtered by the name. See also dsadmin.publish_package, dsadmin.set_package_methods or dsadmin.set_option.

Usage

dsadmin.profile_init(opal, name, packages = NULL)

Arguments

opal

Opal object.

name

Name of the profile.

packages

A list DataSHIELD R package names

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.profile_create(o, name = 'survival', cluster = 'demo')
dsadmin.profile_init(o, name = 'survival', packages = c('dsSurvival'))
opal.logout(o)

## End(Not run)

Get the permissions of a DataSHIELD profile

Description

Get the permissions of a DataSHIELD profile

Usage

dsadmin.profile_perm(opal, name)

Arguments

opal

Opal connection object.

name

Profile name.

Value

A data.frame with columns: subject, type, permission

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.profile_perm_add(o, 'default', c('andrei', 'valentina'), 'user', 'use')
dsadmin.profile_perm(o, 'default')
dsadmin.profile_perm_delete(o, 'default', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Add or update a permission on a DataSHIELD profile

Description

When adding/updating some permissions on a DataSHIELD profile, this profile is automatically set in restricted access mode.

Usage

dsadmin.profile_perm_add(
  opal,
  name,
  subject,
  type = "user",
  permission = "use"
)

Arguments

opal

Opal connection object.

name

Profile.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

permission

The permission to apply: use.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.profile_perm_add(o, 'default', c('andrei', 'valentina'), 'user', 'use')
dsadmin.profile_perm(o, 'default')
dsadmin.profile_perm_delete(o, 'default', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Delete a permission from a DataSHIELD profile

Description

Delete a permission that was applied on a DataSHIELD profile. Silently returns when there is no such permission.

Usage

dsadmin.profile_perm_delete(opal, name, subject, type = "user")

Arguments

opal

Opal connection object.

name

Profile name.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.profile_perm_add(o, 'default', c('andrei', 'valentina'), 'user', 'use')
dsadmin.profile_perm(o, 'default')
dsadmin.profile_perm_delete(o, 'default', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Set or remove the R parser version of a DataSHIELD profile

Description

Set or remove the R parser version of a DataSHIELD profile

Usage

dsadmin.profile_rparser(opal, name, rParser = NULL)

Arguments

opal

Opal object.

name

Name of the profile.

rParser

Version of the DataSHIELD R parser that applies to this profile. If not specified, the system's default one will be used. A valid version would be one of 'v1' or 'v2'.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.profile_create(o, name = 'survival', cluster = 'demo')
# apply R parser version v2
dsadmin.profile_rparser(o, name = 'survival', rParser = 'v2')
# apply system's default R parser version
dsadmin.profile_rparser(o, name = 'survival')
opal.logout(o)

## End(Not run)

Get DataSHIELD profiles

Description

Get DataSHIELD profiles

Usage

dsadmin.profiles(opal, df = TRUE)

Arguments

opal

Opal object.

df

Return a data.frame (default is TRUE)

Value

The DataSHIELD profiles as a data.frame or a list

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.package_descriptions(o)
opal.logout(o)

## End(Not run)

Publish DataSHIELD package settings

Description

Declare DataSHIELD aggregate/assign methods and options as defined by the package.

Usage

dsadmin.publish_package(opal, pkg, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Value

TRUE if successfull

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.publish_package(o, 'dsBase')
opal.logout(o)

## End(Not run)

Remove DataSHIELD package

Description

Remove a DataSHIELD package permanently.

Usage

dsadmin.remove_package(opal, pkg, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.remove_package(o, 'dsBase')
opal.logout(o)

## End(Not run)

Remove DataSHIELD method

Description

Remove DataSHIELD method

Usage

dsadmin.rm_method(opal, name, type = "aggregate", profile = NULL)

Arguments

opal

Opal object or list of opal objects.

name

Name of the method, as it is accessed by DataSHIELD users.

type

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

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.rm_method(o, 'foo')
opal.logout(o)

## End(Not run)

Remove DataSHIELD methods.

Description

Remove DataSHIELD methods.

Usage

dsadmin.rm_methods(opal, type = NULL, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

type

Type of the method: "aggregate" or "assign". Default is NULL (=all type of methods).

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.rm_methods(o)
opal.logout(o)

## End(Not run)

Remove a DataSHIELD option

Description

Remove a DataSHIELD option

Usage

dsadmin.rm_option(opal, name, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

name

Name of the option

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.rm_option(o, 'foo')
opal.logout(o)

## End(Not run)

Remove all DataSHIELD options

Description

Remove all DataSHIELD options

Usage

dsadmin.rm_options(opal, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.rm_options(o, 'foo')
opal.logout(o)

## End(Not run)

Remove DataSHIELD package methods

Description

Remove DataSHIELD aggregate and assign methods defined by the package.

Usage

dsadmin.rm_package_methods(opal, pkg, type = NULL, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

type

Type of the method: "aggregate" or "assign". Default is NULL (=all type of methods).

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.rm_package_methods(o, 'dsBase')
opal.logout(o)

## End(Not run)

Set DataSHIELD method

Description

Set DataSHIELD method

Usage

dsadmin.set_method(
  opal,
  name,
  func = NULL,
  path = NULL,
  type = "aggregate",
  profile = NULL
)

Arguments

opal

Opal object or list of opal objects.

name

Name of the method, as it will be accessed by DataSHIELD users.

func

Function name or function code.

path

Path to the R file containing the script (mutually exclusive with func).

type

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

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# as a package's function
dsadmin.set_method(o, 'foo', func = 'base::mean')
# as a custom function
dsadmin.set_method(o, 'foo', func = function(x) { base::mean(x) })
opal.logout(o)

## End(Not run)

Set DataSHIELD option

Description

Set a DataSHIELD option (add or update).

Usage

dsadmin.set_option(opal, name, value, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

name

Name of the option

value

Value of the option

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.set_option(o, 'foo', 'bar')
opal.logout(o)

## End(Not run)

Set DataSHIELD package methods

Description

Declare DataSHIELD aggregate and assign methods as defined by the package.

Usage

dsadmin.set_package_methods(opal, pkg, type = NULL, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

type

Type of the method: "aggregate" or "assign". Default is NULL (=all type of methods).

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Value

TRUE if successfull

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.set_package_methods(o, 'dsBase')
opal.logout(o)

## End(Not run)

Unpublish DataSHIELD package settings

Description

Remove DataSHIELD aggregate/assign methods and options as defined by the package from the DataSHIELD configuration.

Usage

dsadmin.unpublish_package(opal, pkg, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

profile

The DataSHIELD profile name to which operation applies. See also dsadmin.profiles.

Value

TRUE if successfull

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dsadmin.unpublish_package(o, 'dsBase')
opal.logout(o)

## End(Not run)

Get R activity

Description

Get the recorded R session metrics.

Usage

oadmin.activity(
  opal,
  user = NULL,
  profile = NULL,
  from = NULL,
  to = NULL,
  df = TRUE
)

Arguments

opal

Opal connection object.

user

Optional user name.

profile

Optional profile name.

from

Optional start date.

to

Optional end date.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# all sessions metrics
oadmin.activity(o)
# user and profile specific session metrics
oadmin.activity(o, user = 'dsuser', profile = 'default')
# user sessions in a time range
oadmin.activity(o, user = "dsuser", from = "2022-07-01", to = "2023-01-01")
opal.logout(o)

## End(Not run)

Get R activity summary

Description

Get the recorded R session metrics, grouped by profile and user.

Usage

oadmin.activity_summary(
  opal,
  user = NULL,
  profile = NULL,
  from = NULL,
  to = NULL,
  df = TRUE
)

Arguments

opal

Opal connection object.

user

Optional user name.

profile

Optional profile name.

from

Optional start date.

to

Optional end date.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# all sessions metrics
oadmin.activity_summary(o)
# user and profile specific session metrics
oadmin.activity_summary(o, user = 'dsuser', profile = 'default')
# user sessions in a time range
oadmin.activity_summary(o, user = "dsuser", from = "2022-07-01", to = "2023-01-01")
opal.logout(o)

## End(Not run)

Install a package from Bioconductor

Description

Install a package from a source repository on GitHub.

Usage

oadmin.install_bioconductor_package(opal, pkg, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

profile

The R servers profile name to which operation applies. See also opal.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.install_bioconductor_package(o, 'GWASTools')
opal.logout(o)

## End(Not run)

Install a package from CRAN

Description

Install a package from configured CRAN repositories.

Usage

oadmin.install_cran_package(opal, pkg, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

profile

The R servers profile name to which operation applies. See also opal.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.install_cran_package(o, 'opalr', 'obiba')
opal.logout(o)

## End(Not run)

Install devtools package

Description

Install devtools package if not already available.

Usage

oadmin.install_devtools(opal, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

profile

The R servers profile name to which operation applies. See also opal.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.install_devtools(o)
opal.logout(o)

## End(Not run)

Install a package from GitHub

Description

Install a package from a source repository on GitHub.

Usage

oadmin.install_github_package(
  opal,
  pkg,
  username = getOption("github.user"),
  ref = "master",
  profile = NULL
)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

username

GitHub user or organization name.

ref

Desired git reference. Could be a commit, tag, or branch name. Defaults to "master".

profile

The R servers profile name to which operation applies. See also opal.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.install_github_package(o, 'opalr', 'obiba')
opal.logout(o)

## End(Not run)

Install a package from a local archive file

Description

Install a package from a package archive file. This will upload the archive file and run its installation in the R server. The R server profile to which the operation applies is the one specified at login time.

Usage

oadmin.install_local_package(opal, path, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

path

Path to the package archive file.

profile

The R servers profile name to which operation applies. See also opal.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# install a pre-built local archive file
oadmin.install_local_package(o, '~/Rserve_1.8-7.tar.gz')
# or build archive file from local package source (in current working folder)
oadmin.install_local_package(o, devtools::build())
opal.logout(o)

## End(Not run)

Install CRAN package

Description

Install package from CRAN repos. To install the latest version of a package, it has to be removed first.

Usage

oadmin.install_package(opal, pkg, repos = NULL, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

repos

Character vector, the base URLs of the repositories to use.

profile

The R servers profile name to which operation applies. See also opal.profiles.

Value

TRUE if successfully installed

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.install_package(o, 'xxx')
opal.logout(o)

## End(Not run)

Check devtools package

Description

Check if devtools package is installed.

Usage

oadmin.installed_devtools(opal, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

profile

The R servers profile name to which operation applies. See also opal.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.installed_devtools(o)
opal.logout(o)

## End(Not run)

Check package is installed

Description

Check package is installed

Usage

oadmin.installed_package(opal, pkg, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

profile

The R servers profile name to which operation applies. See also opal.profiles.

Value

TRUE if installed

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.installed_package(o, 'xxx')
oadmin.installed_package(o, 'stats')
opal.logout(o)

## End(Not run)

List installed packages

Description

Get the installed packages from all the R servers in the cluster described by the profile.

Usage

oadmin.installed_packages(opal, profile = NULL)

Arguments

opal

Opal object.

profile

The R servers profile name to which operation applies. See also opal.profiles.

Value

The result of the installed.packages() call

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.installed_packages(o)
opal.logout(o)

## End(Not run)

Get Opal main logs

Description

Get Opal main logs

Usage

oadmin.log(opal, all = TRUE)

Arguments

opal

Opal connection object.

all

Get all or only latest log messages.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.log(o)
opal.logout(o)

## End(Not run)

Get Opal REST API logs

Description

Get Opal REST API logs

Usage

oadmin.log_rest(opal, all = TRUE)

Arguments

opal

Opal connection object.

all

Get all or only latest log messages.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.log_rest(o)
opal.logout(o)

## End(Not run)

Get Opal SQL API logs

Description

Get Opal SQL API logs

Usage

oadmin.log_sql(opal, all = TRUE)

Arguments

opal

Opal connection object.

all

Get all or only latest log messages.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.log_sql(o)
opal.logout(o)

## End(Not run)

Get package description

Description

Get package description

Usage

oadmin.package_description(opal, pkg, fields = NULL, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

fields

A character vector giving the fields to extract from each package's DESCRIPTION file in addition to the default ones, or NULL (default). Unavailable fields result in NA values.

profile

The R servers profile name to which operation applies. See also opal.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.package_description(o, 'stats')
opal.logout(o)

## End(Not run)

Get the R permissions (deprecated)

Description

Deprecated, use oadmin.r_perm.

Usage

oadmin.perm(opal)

Arguments

opal

Opal connection object.

Value

A data.frame with columns: subject, type, permission

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.r_perm_add(o, c('andrei', 'valentina'), 'user', 'use')
oadmin.r_perm(o)
oadmin.r_perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Add or update a R permission (deprecated)

Description

Deprecated, use oadmin.r_perm_add.

Usage

oadmin.perm_add(opal, subject, type = "user", permission)

Arguments

opal

Opal connection object.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

permission

The permission to apply: use.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.r_perm_add(o, c('andrei', 'valentina'), 'user', 'use')
oadmin.r_perm(o)
oadmin.r_perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Delete a R permission (deprecated)

Description

Deprecated, use oadmin.r_perm_delete.

Usage

oadmin.perm_delete(opal, subject, type = "user")

Arguments

opal

Opal connection object.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.r_perm_add(o, c('andrei', 'valentina'), 'user', 'use')
oadmin.r_perm(o)
oadmin.r_perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Get the R permissions

Description

Get the permissions that were applied to the R service.

Usage

oadmin.r_perm(opal)

Arguments

opal

Opal connection object.

Value

A data.frame with columns: subject, type, permission

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.r_perm_add(o, c('andrei', 'valentina'), 'user', 'use')
oadmin.r_perm(o)
oadmin.r_perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Add or update a R permission

Description

Add or update a permission on the R service.

Usage

oadmin.r_perm_add(opal, subject, type = "user", permission = "use")

Arguments

opal

Opal connection object.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

permission

The permission to apply: use.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.r_perm_add(o, c('andrei', 'valentina'), 'user', 'use')
oadmin.r_perm(o)
oadmin.r_perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Delete a R permission

Description

Delete a permission that was applied to the R service. Silently returns when there is no such permission.

Usage

oadmin.r_perm_delete(opal, subject, type = "user")

Arguments

opal

Opal connection object.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.r_perm_add(o, c('andrei', 'valentina'), 'user', 'use')
oadmin.r_perm(o)
oadmin.r_perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Remove package

Description

Remove package permanently.

Usage

oadmin.remove_package(opal, pkg, profile = NULL)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

profile

The R servers profile name to which operation applies. See also opal.profiles.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.remove_package(o, 'xxx')
opal.logout(o)

## End(Not run)

Get system metrics

Description

Get some metrics about the Opal system status. The following information are returned: 'timestamp' (the EPOC time at which the metrics were collected), 'uptime' (the running time in millis), 'heapMemory' (the memory currently used), 'nonHeapMemory' (the memory that can be used), 'threads' (the current (count) and maximum (peak) numbers of threads), 'gcs' (the garbage collectors activity).

Usage

oadmin.system_metrics(opal)

Arguments

opal

Opal connection object.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.system_metrics(o)
opal.logout(o)

## End(Not run)

Get the System permissions

Description

Get the permissions that were applied to the whole system.

Usage

oadmin.system_perm(opal)

Arguments

opal

Opal connection object.

Value

A data.frame with columns: subject, type, permission

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.system_perm_add(o, c('andrei', 'valentina'), 'user', 'project_add')
oadmin.system_perm(o)
oadmin.system_perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Add or update a System permission

Description

Add or update a permission on the whole system.

Usage

oadmin.system_perm_add(opal, subject, type = "user", permission)

Arguments

opal

Opal connection object.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

permission

The permission to apply: project_add or administrate.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.system_perm_add(o, c('andrei', 'valentina'), 'user', 'project_add')
oadmin.system_perm(o)
oadmin.system_perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Delete a System permission

Description

Delete a permission that was applied to the whole system. Silently returns when there is no such permission.

Usage

oadmin.system_perm_delete(opal, subject, type = "user")

Arguments

opal

Opal connection object.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.system_perm_add(o, c('andrei', 'valentina'), 'user', 'project_add')
oadmin.system_perm(o)
oadmin.system_perm_delete(o, c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Add a user

Description

Add a user in Opal internal users registry.

Usage

oadmin.user_add(opal, name, groups = NULL, password = NULL)

Arguments

opal

Opal object.

name

User name

groups

User groups

password

User password. If not provided, a password will be generated and returned.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
pwd <- oadmin.user_add(o, "foo", groups = c("datashield", "CNSIM"))
opal.logout(o)

## End(Not run)

Delete a user

Description

Delete a user from Opal internal users registry. Fails silently if user does not exist.

Usage

oadmin.user_delete(opal, name)

Arguments

opal

Opal object.

name

User name

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
pwd <- oadmin.user_add(o, "foo", groups = c("datashield", "CNSIM"))
oadmin.user_delete(o, "foo")
opal.logout(o)

## End(Not run)

Enable a user

Description

Enable or disable a user from Opal internal users registry.

Usage

oadmin.user_enable(opal, name, enabled = TRUE)

Arguments

opal

Opal object.

name

User name

enabled

Logical to enable a user.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
pwd <- oadmin.user_add(o, "foo", groups = c("datashield", "CNSIM"))
oadmin.user_enable(o, "foo", enabled = FALSE)
opal.logout(o)

## End(Not run)

Check user exists

Description

Check whether a user exists, either in the internal user registry (see oadmin.users) or as an external user that already logged in (see oadmin.user_profiles).

Usage

oadmin.user_exists(opal, name)

Arguments

opal

Opal object.

name

User name

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
if (!oadmin.user_exists(o, "foo"))
  oadmin.user_add(o, "foo", password = "bar123")
opal.logout(o)

## End(Not run)

Delete a user profile

Description

Delete a user profile without deleting user if this one is defined in the Opal internal users registry. Fails silently if user profile does not exist. A user profile is the footprint of a user, created at first login. It keeps track of its activity, the realm from which he/she was authenticated, its groups at time of the last login and more.

Usage

oadmin.user_profile_delete(opal, name)

Arguments

opal

Opal object.

name

User name

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
pwd <- oadmin.user_add(o, "foo", groups = c("datashield", "CNSIM"))
oadmin.user_profile_delete(o, "foo")
opal.logout(o)

## End(Not run)

Get user profiles

Description

When a user has logged in Opal, he/she has a profile representing its activity. The user can be defined in the Opal internal user registry, or in an external realm.

Usage

oadmin.user_profiles(opal, df = TRUE)

Arguments

opal

Opal object.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.user_profiles(o)
opal.logout(o)

## End(Not run)

Reset user password

Description

Reset the password of a user from Opal internal users registry.

Usage

oadmin.user_reset_password(opal, name, password = NULL)

Arguments

opal

Opal object.

name

User name

password

User password. If not provided, a password will be generated and returned.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
pwd <- oadmin.user_add(o, "foo", groups = c("datashield", "CNSIM"))
oadmin.user_reset_password(o, "foo", password = "password1234")
oadmin.user_rm(o, "foo")
opal.logout(o)

## End(Not run)

Get the users

Description

Get the users from the Opal internal users registry.

Usage

oadmin.users(opal, df = TRUE)

Arguments

opal

Opal object.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
oadmin.users(o)
opal.logout(o)

## End(Not run)

Apply the annotations to a Opal table

Description

Set the provided annotations (as the one that can be retrieved from opal.annotations) to the table's data dictionary. Variables that do not exists in the table are ignored.

Usage

opal.annotate(opal, datasource, table, annotations)

Arguments

opal

Opal object.

datasource

Name of the datasource.

table

Name of the table in the datasource.

annotations

A data frame of annotations, with the expected columns: 'variable' (variable name), 'taxonomy' (the taxonomy name), 'vocabulary' (the vocabulary name) and 'term' (the term value, if NULL of NA the annotation is removed).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
annots <- opal.annotations(o, 'CPTP', 'Coreqx_final')
opal.annotate(o, 'CPTP', 'Cag_coreqx', annots)
opal.logout(o)

## End(Not run)

Get the annotations of a Opal table

Description

Directly retrieves from the table's data dictionary the variable annotations (attributes with a namespace).

Usage

opal.annotations(opal, datasource, table)

Arguments

opal

Opal object.

datasource

Name of the datasource.

table

Name of the table in the datasource.

Value

A data frame in long format (one row per annotation).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.annotations(o, 'CPTP', 'Coreqx_final')
opal.logout(o)

## End(Not run)

Array to Markdown

Description

Helper function for turning an array into its Markdown representation.

Usage

opal.as_md_table(
  table,
  icons = TRUE,
  digits = getOption("digits"),
  col.names = colnames(table),
  align,
  caption = NULL
)

Arguments

table

An array, including a matrix or a data.frame.

icons

Turn logicals to icons (requires bootstrap style). Default is TRUE.

digits

The maximum number of digits for numeric columns (passed to round()); it can also be a vector of length ncol(table) to set the number of digits for individual columns.

col.names

A character vector of column names to be used in the table

align

The alignment of columns: a character vector consisting of 'l' (left), 'c' (center) and/or 'r' (right); by default, numeric columns are right-aligned, and other columns are left-aligned; if align = NULL, the default alignment is used.

caption

The table caption.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.as_md_table(opal.variables(o, 'datashield', 'CNSIM1'))
opal.logout(o)

## End(Not run)

Data or expression assignment

Description

Assign a Opal table, or a R expression or a R object to a R symbol in the current R session.

Usage

opal.assign(
  opal,
  symbol,
  value,
  variables = NULL,
  missings = FALSE,
  identifiers = NULL,
  id.name = NULL,
  updated.name = NULL,
  async = FALSE
)

Arguments

opal

Opal object or list of opal objects.

symbol

Name of the R symbol.

value

The value to assign evaluated in the following order: a R expression, a function, a fully qualified name of a variable or a table in Opal or any other R object (data.frame, vector).

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: http://wiki.obiba.org/display/OPALDOC/Variable+Methods

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

Add a vector with the given name representing the entity identifiers (from Opal 2.6). Default is NULL.

updated.name

Add a vector with the given name representing the creation and last update timestamps (from Opal 2.6). Default is NULL.

async

R script is executed asynchronously within the session (default is FALSE). If TRUE, the value returned is the ID of the command to look for (from Opal 2.1).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# assign a list of variables from table CNSIM1
opal.assign(o, symbol="D", value="datashield.CNSIM1", variables=list("GENDER","LAB_TSC"))
# assign all the variables matching 'LAB' from table HOP of opal object o
opal.assign(o, symbol="D", value="datashield.CNSIM1", variables="name().matches('LAB_')")
# assign a function and call it
opal.assign.script(o, 'hello', quote(function(x) { print(paste0('Hello ', x , '!'))}))
opal.execute(o, "hello('Mr Bean')")
# push an arbitrary data frame to the R server
#opal.assign(o, "D", mtcars)
# push an arbitrary vector to the R server
#opal.assign(o, "C", mtcars$cyl)
opal.logout(o)

## End(Not run)

Data assignment

Description

Assign a R object to a R symbol in the current R session.

Usage

opal.assign.data(opal, symbol, value, async = FALSE)

Arguments

opal

Opal object or list of opal objects.

symbol

Name of the R symbol.

value

The R object to assign (data.frame, vector).

async

R script is executed asynchronously within the session (default is FALSE). If TRUE, the value returned is the ID of the command to look for (from Opal 2.1).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# push an arbitrary data frame to the R server
opal.assign.data(o, "D", mtcars)
# push an arbitrary vector to the R server
opal.assign.data(o, "C", mtcars$cyl)
# push a string
opal.assign.data(o, "S", "Hello!")
opal.logout(o)

## End(Not run)

Resource assignment

Description

Assign a ResourceClient object to a R symbol in the current R session.

Usage

opal.assign.resource(opal, symbol, value, async = FALSE)

Arguments

opal

Opal object or list of opal objects.

symbol

Name of the R symbol.

value

The fully qualified name of a resource in Opal.

async

R script is executed asynchronously within the session (default is FALSE). If TRUE, the value returned is the ID of the command to look for (from Opal 2.1).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# assign a resource and make some operation on it
opal.assign.resource(o, "D", "datashield.cram1")
opal.execute(o, "class(D)")
opal.logout(o)

## End(Not run)

R script assignment

Description

Assign a R script or expression to a R symbol in the current R session.

Usage

opal.assign.script(opal, symbol, value, async = FALSE)

Arguments

opal

Opal object or list of opal objects.

symbol

Name of the R symbol.

value

The R expression to assign.

async

R script is executed asynchronously within the session (default is FALSE). If TRUE, the value returned is the ID of the command to look for (from Opal 2.1).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# assign a function and call it
opal.assign.script(o, 'hello', quote(function(x) { print(paste0('Hello ', x , '!'))}))
opal.execute(o, "hello('Mr Bean')")
opal.logout(o)

## End(Not run)

Data assignment to a data.frame

Description

Assign a Opal table to a data.frame identified by a R symbol in the current R session.

Usage

opal.assign.table(
  opal,
  symbol,
  value,
  variables = NULL,
  missings = FALSE,
  identifiers = NULL,
  id.name = NULL,
  updated.name = NULL,
  class = "data.frame",
  async = FALSE
)

Arguments

opal

Opal object or list of opal objects.

symbol

Name of the R symbol.

value

The value to assign evaluated in the following order: a fully qualified name of a variable or a table in Opal.

variables

missings

If TRUE, missing values will be pushed from Opal to R, default is FALSE.

identifiers

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

id.name

Add a vector with the given name representing the entity identifiers (from Opal 2.6). Default is NULL.

updated.name

Deprecated. Add a vector with the given name representing the creation and last update timestamps (from Opal 2.6). Default is NULL.

class

The data frame class into which the table is written: can 'data.frame' (default) or 'tibble' (from Opal 2.6 to 2.13) or 'tibble.with.factors' (from Opal 2.14).

async

R script is executed asynchronously within the session (default is FALSE). If TRUE, the value returned is the ID of the command to look for (from Opal 2.1).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# assign a list of variables from table CNSIM1
opal.assign.table(o, symbol="D", value="datashield.CNSIM1", variables=list("GENDER","LAB_TSC"))
opal.execute(o, "colnames(D)")
# assign a table CNSIM1 with a identifiers column
opal.assign.table(o, symbol="H", value="datashield.CNSIM1", id.name="id")
opal.execute(o, "colnames(H)")
# assign all the variables matching 'LAB' from table HOP of opal object o
opal.assign.table(o, symbol="D", value="datashield.CNSIM1", variables="name().matches('LAB_')")
opal.execute(o, "colnames(D)")
opal.logout(o)

## End(Not run)

Data assignment to a tibble

Description

Assign a Opal table to a tibble identified by a R symbol in the current R session.

Usage

opal.assign.table.tibble(
  opal,
  symbol,
  value,
  variables = NULL,
  missings = FALSE,
  identifiers = NULL,
  id.name = "id",
  with.factors = FALSE,
  updated.name = NULL,
  async = FALSE
)

Arguments

opal

Opal object.

symbol

Name of the R symbol.

value

The fully qualified name of a table in Opal.

variables

missings

If TRUE, missing values will be pushed from Opal to R, default is FALSE.

identifiers

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

id.name

Add a vector with the given name representing the entity identifiers (from Opal 2.6). Default is 'id'.

with.factors

If TRUE, the categorical variables will be assigned as factors (from Opal 2.14). Default is FALSE.

updated.name

Deprecated. Add a vector with the given name representing the creation and last update timestamps (from Opal 2.6 to 2.13). Default is NULL.

async

R script is executed asynchronously within the session (default is FALSE). If TRUE, the value returned is the ID of the command to look for (from Opal 2.1).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# assign a table and make some operation on it
opal.assign.table.tibble(o, 'D', 'datashield.CNSIM1')
opal.execute(o, "class(D)")
opal.logout(o)

## End(Not run)

Get a vector of attribute values

Description

Get a vector of attribute values (for each locale) matching the given attribute namespace and name. Vector is null if no such attribute is found.

Usage

opal.attribute_values(attributes, namespace = NULL, name = "label")

Arguments

attributes

A list of attributes, usually variable or category attributes.

namespace

Optional attribute namespace.

name

Required attribute name.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
var <- opal.variable(o, 'CNSIM', 'CNSIM1', 'GENDER')
opal.attribute_values(var$attributes)
opal.logout(o)

## End(Not run)

Get an asynchronous command

Description

Get an asynchronous R commands in the remote R session.

Usage

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

Arguments

opal

Opal object.

id

R command ID.

wait

Wait for the command to complete.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.command(o, '1234')
opal.logout(o)

## End(Not run)

Get result of an asynchronous command

Description

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

Usage

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

Arguments

opal

Opal object.

id

R command ID.

wait

Wait for the command to complete.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.command_result(o, '1234')
opal.logout(o)

## End(Not run)

Remove an asynchronous command

Description

Remove an asynchronous R commands in the remote R session.

Usage

opal.command_rm(opal, id)

Arguments

opal

Opal object.

id

R command ID.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.command_rm(o, '1234')
opal.logout(o)

## End(Not run)

List the asynchronous commands

Description

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

Usage

opal.commands(opal, df = TRUE)

Arguments

opal

Opal object.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.commands(o)
opal.logout(o)

## End(Not run)

Remove all asynchronous commands

Description

Remove all asynchronous R commands in the remote R session.

Usage

opal.commands_rm(opal)

Arguments

opal

Opal object.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.commands_rm(o)
opal.logout(o)

## End(Not run)

Get a datasource

Description

Get a datasource

Usage

opal.datasource(opal, datasource)

Arguments

opal

Opal object.

datasource

Name of the datasource.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.datasource(o, 'CNSIM')
opal.logout(o)

## End(Not run)

Get datasources

Description

Get datasources

Usage

opal.datasources(opal, df = TRUE)

Arguments

opal

Opal object.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.datasources(o)
opal.logout(o)

## End(Not run)

Generic REST resource deletion.

Description

Generic REST resource deletion.

Usage

opal.delete(opal, ..., query = list(), callback = NULL)

Arguments

opal

Opal object.

...

Resource path segments.

query

Named list of query parameters.

callback

A callback function to handle the response object.

Examples

## Not run: 
o <- opal.login('administrator','password', url = 'https://opal-demo.obiba.org')
opal.delete(o, 'some', 'resource')
opal.logout(o)

## End(Not run)

Execute a R script

Description

Execute a R script in the remote R session.

Usage

opal.execute(opal, script, async = FALSE)

Arguments

opal

Opal object or list of opal objects.

script

R script to execute.

async

R script is executed asynchronously within the session (default is FALSE). If TRUE, the value returned is the ID of the command to look for (from Opal 2.1).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.execute(o, "x <- 'foo'")
opal.execute(o, "ls()")
opal.logout(o)

## End(Not run)

Execute a R file script

Description

Upload a R file script and execute it in the remote R session with source().

Usage

opal.execute.source(opal, path, async = FALSE)

Arguments

opal

Opal object or list of opal objects.

path

Path to the R file script to execute.

async

R script is executed asynchronously within the session (default is FALSE). If TRUE, the value returned is the ID of the command to look for (from Opal 2.1).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.execute.source(o, "myscript.R")
opal.logout(o)

## End(Not run)

Get file content

Description

Get file content from the Opal file system.

Usage

opal.file(opal, path, key = NULL)

Arguments

opal

Opal object.

path

Path to the file in the Opal file system.

key

File encryption key: downloaded file will be a zip file with content encrypted (use 7zip to decrypt).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.file(o, '/home/administrator/joins/join-src-3.csv')
opal.logout(o)

## End(Not run)

Copy a file

Description

Copy a file or a folder to another location in the Opal file system.

Usage

opal.file_cp(opal, source, destination)

Arguments

opal

Opal object.

source

Path to the file in the Opal file system.

destination

New path to the file in the Opal file system.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# copy a file to another folder
opal.file_cp(o, '/home/administrator/export/some-data.csv', '/home/userx/deliverables')
# copy recursively a folder to another folder
opal.file_cp(o, '/home/administrator/export', '/home/userx/deliverables')
opal.logout(o)

## End(Not run)

Download a file

Description

Download a file or a folder from the Opal file system.

Usage

opal.file_download(opal, source, destination = NULL, key = NULL)

Arguments

opal

Opal object.

source

Path to the file in the Opal file system.

destination

Path to the file to be written. If ommitted, file with same name in the working directory will be written.

key

File encryption key: downloaded file will be a zip file with content encrypted (use 7zip to decrypt).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# download a file
opal.file_download(o, '/home/administrator/joins/join-src-3.csv')
# download a file encrypted by a key: resulting file is a zip with an encrypted content
opal.file_download(o, '/home/administrator/export/some-data.csv', 
                      destination='some-data.zip', key='AZF57893FBDE')
# download, create destination folder and rename file
opal.file_download(o, '/home/administrator/spss/DatabaseTest.sav', 'spss/test.sav')
# download a folder
opal.file_download(o, '/home/administrator/export', 'export.zip')
opal.logout(o)

## End(Not run)

List content of a folder

Description

List content of a folder in the Opal file system.

Usage

opal.file_ls(opal, path)

Arguments

opal

Opal object.

path

Path to the folder in the Opal file system.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# list content of a folder
opal.file_ls(o, '/home/administrator')
opal.logout(o)

## End(Not run)

Make a folder

Description

Make a folder in the Opal file system. Use the parents parameter to ignore if it already exist and to create parent folders.

Usage

opal.file_mkdir(opal, path, parents = FALSE)

Arguments

opal

Opal object.

path

Path to the new folder in the Opal file system.

parents

No error if existing, make parent directories as needed. Default is FALSE.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# make a folder
opal.file_mkdir(o, '/home/administrator/test', parents = TRUE)
opal.logout(o)

## End(Not run)

Make a temporary folder

Description

Make a user personal temporary folder in the Opal file system (make sure it does not exists).

Usage

opal.file_mkdir_tmp(opal)

Arguments

opal

Opal object.

Value

The path of the created folder.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# make a folder
path <- opal.file_mkdir_tmp(o)
opal.logout(o)

## End(Not run)

Move and/or rename a file

Description

Move and/or rename a file or a folder in the Opal file system.

Usage

opal.file_mv(opal, source, destination)

Arguments

opal

Opal object.

source

Path to the file in the Opal file system.

destination

New path to the file in the Opal file system.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# move a file to another folder
opal.file_mv(o, '/home/administrator/export/some-data.csv', '/home/userx/deliverables')
# rename a file
opal.file_mv(o, '/home/administrator/export/some-data-20170123.csv', 
                '/home/administrator/export/some-data.csv')
# move and rename a file
opal.file_mv(o, '/home/administrator/export/some-data-20170123.csv', 
                '/home/userx/deliverables/some-data.csv')
opal.logout(o)

## End(Not run)

Read a file

Description

Read a file from the R session workspace into the Opal file system.

Usage

opal.file_read(opal, source, destination)

Arguments

opal

Opal object.

source

Path to the file in the R session workspace (must exists).

destination

Path to the destination file or folder. Any required sub-folders will be created.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# read into folder
opal.file_read(o,"DatabaseTest.sav", "/tmp")
# read and rename
opal.file_read(o,"test/DatabaseTest.sav", "/tmp/Test.sav")
# user home expansion
opal.file_read(o,"DatabaseTest.sav", "~/coucou/pwel.sav")
opal.logout(o)

## End(Not run)

Remove a file

Description

Remove a file or a folder from the Opal file system.

Usage

opal.file_rm(opal, path)

Arguments

opal

Opal object.

path

Path to the file in the Opal file system.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# remove a file
opal.file_rm(o, '/home/administrator/export/some-data.csv')
# remove recursively a folder
opal.file_rm(o, '/home/administrator/export')
opal.logout(o)

## End(Not run)

Unzip a zip archive file

Description

Unzip a zip archive file from the Opal file system.

Usage

opal.file_unzip(opal, source, destination, key = NULL)

Arguments

opal

Opal object.

source

Path to the file in the Opal file system (must exist and have the ".zip" file extension).

destination

Path to the destination file or folder in the Opal file system.

key

Key to decrypt archive.

Value

The path of the extracted archive folder in the Opal file system.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# unzip
path <- opal.file_unzip(o, "/tmp/TESTING.zip", "/home/administrator")
opal.logout(o)

## End(Not run)

Upload a file or a folder

Description

Upload a file or a folder into the Opal file system. Creates the destination folder (and parents) when necessary. Hidden files and folders (with name starting with dot) can be excluded.

Usage

opal.file_upload(opal, source, destination, all.files = TRUE)

Arguments

opal

Opal object.

source

Path to the file in the local file system.

destination

Path of the destination folder in the Opal file system. Folder (and parents) will be created if missing.

all.files

When FALSE, upload only visible files (following Unix-style visibility, that is files whose name does not start with a dot). Default is TRUE.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# upload a file
opal.file_upload(o, 'some_data.csv', '/home/administrator')
# upload a folder
opal.file_upload(o, 'some_data', '/home/administrator')
opal.logout(o)

## End(Not run)

Write a file

Description

Write a file from the Opal file system into the R session workspace.

Usage

opal.file_write(opal, source, destination = NULL)

Arguments

opal

Opal object.

source

Path to the file in the Opal file system (must exists and be accessible for the user).

destination

Path to the destination file, relative to the R session workspace. Any required sub-folders will be created. If ommitted, file with same name will be written.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# user home expansion
opal.file_write(o, "~/spss/DatabaseTest.sav")
# rename file
opal.file_write(o, "/home/administrator/spss/DatabaseTest.sav", "x.sav")
# create sub-folder
opal.file_write(o, "/home/administrator/spss/DatabaseTest.sav", "test/x.sav")
opal.logout(o)

## End(Not run)

Generic REST resource getter.

Description

Generic REST resource getter.

Usage

opal.get(
  opal,
  ...,
  query = list(),
  acceptType = "application/json",
  outFile = NULL,
  callback = NULL
)

Arguments

opal

Opal object.

...

Resource path segments.

query

Named list of query parameters.

acceptType

The type of the body content. Default is 'application/json', i.e. a serialized R object or an error message.

outFile

Write response body to file. Ignored if NULL (default).

callback

A callback function to handle the response object.

Examples

## Not run: 
o <- opal.login('administrator','password', url = 'https://opal-demo.obiba.org')
opal.get(o, 'project', 'CNSIM')
opal.logout(o)

## End(Not run)

Load package

Description

Load package in the remote R session.

Usage

opal.load_package(opal, pkg)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.load_package(o, 'stats')
opal.logout(o)

## End(Not run)

Description

Log in Opal(s). Different login strategies are possible: (1) by providing username/password, or (2) by providing username/password and a one-time password code (TOPT) when user has activated two-factor authentication, or (3) by providing a personal access token (PAT), or (4) by providing a key pair in PEM format.

Usage

opal.login(
  username = getOption("opal.username"),
  password = getOption("opal.password"),
  token = getOption("opal.token"),
  url = getOption("opal.url"),
  opts = getOption("opal.opts", list()),
  profile = getOption("opal.profile"),
  restore = NULL
)

Arguments

username

User name in opal(s). Can be provided by "opal.username" option.

password

User password in opal(s). Can be provided by "opal.password" option.

token

Personal access token (since opal 2.15). Only effective if the username or the password is NULL or empty. Can be provided by "opal.token" option.

url

Opal url or list of opal urls. Can be provided by "opal.url" option. Secure http (https) connection is required.

opts

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

profile

R server profile name. This will drive the R server in which a R session will be created. If no remote R session is needed (because Opal specific operations are done), this parameter does not need to be provided. Otherwise, if missing, the default R server profile will be applied ('default'). See also opal.profiles.

restore

Workspace ID to be restored (see also opal.logout)

Value

A opal object or a list of opal objects.

Examples

## Not run: 
#### The below examples illustrate the different ways to login in opal ####

# explicite username/password login
o <- opal.login(username = 'administrator', password = 'password', 
                url = 'https://opal-demo.obiba.org')
opal.logout(o)

 # explicite personal access token login
o <- opal.login(token = 'HYG16LO0VaX4O0UardNbiqmr2ByBpRke', 
                url = 'https://opal-demo.obiba.org')
opal.logout(o)

# login using options and user credentials
options(opal.username = 'administrator',
 opal.password = 'password',
 opal.url = 'https://opal-demo.obiba.org')
o <- opal.login()
opal.logout(o)

# login using options and personal access token
options(opal.token = 'HYG16LO0VaX4O0UardNbiqmr2ByBpRke',
        opal.url = 'https://opal-demo.obiba.org')
o <- opal.login()
opal.logout(o)

# login using ssl key pair
options(opal.opts = list(
          sslcert = 'my-publickey.pem',
          sslkey = 'my-privatekey.pem'))
o <- opal.login(url = 'https://opal-demo.obiba.org')
opal.logout(o)

# login with a R server profile
o <- opal.login(username = 'administrator', password = 'password', 
                url = 'https://opal-demo.obiba.org', profile = 'default')
opal.logout(o)

## End(Not run)

Logout from Opal(s)

Description

Clear the R sessions and logout from Opal(s).

Usage

opal.logout(opal, save = FALSE)

Arguments

opal

Opal object or a list of opals.

save

Save the workspace with given identifier (default value is FALSE, current session ID if TRUE).

Examples

## Not run: 
o <- opal.login('administrator','password', url = 'https://opal-demo.obiba.org')
opal.logout(o)

## End(Not run)

Get the permissions of a subject

Description

Get the permissions of a subject. If the subject is a user, the permissions of the groups to which the user belongs are also added to the result.

Usage

opal.perms(opal, subject, type = "user")

Arguments

opal

Opal connection object.

subject

A subject identifier: user or group name.

type

The type of subject: user (default) or group.

Value

A data.frame with columns: subject, type, target (path to the opal object to which the permission applies), target_type and perm (the permission name)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.table_perm_add(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user', 'view')
opal.perms(o, 'andrei')
opal.table_perm_delete(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Generic REST resource creation.

Description

Generic REST resource creation.

Usage

opal.post(
  opal,
  ...,
  query = list(),
  body = "",
  contentType = "application/x-rscript",
  acceptType = "application/json",
  outFile = NULL,
  callback = NULL
)

Arguments

opal

Opal object.

...

Resource path segments.

query

Named list of query parameters.

body

The body of the request.

contentType

The type of the body content. Default is 'application/x-rscript'.

acceptType

The type of the body content. Default is 'application/json', i.e. a serialized R object or an error message.

outFile

Write response body to file. Ignored if NULL (default).

callback

A callback function to handle the response object.

Examples

## Not run: 
o <- opal.login('administrator','password', url = 'https://opal-demo.obiba.org')
opal.post(o, 'some', 'resources', body = '{"some":"value"}')
opal.logout(o)

## End(Not run)

List R profiles

Description

Each R profile corresponds one R servers cluster name. These profiles names can be provided when login (see opal.login) and on some package administration operations.

Usage

opal.profiles(opal, df = TRUE)

Arguments

opal

Opal object.

df

Return a data.frame (default is TRUE)

Value

The R profiles as a data.frame or a list

Examples

## Not run: 
o <- opal.login('administrator','password', url = 'https://opal-demo.obiba.org')
opal.profiles(o)
opal.logout(o)

## End(Not run)

Get a project

Description

Get a project

Usage

opal.project(opal, project)

Arguments

opal

Opal object.

project

Name of the project

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.project(o, 'datashield')
opal.logout(o)

## End(Not run)

Backup a project

Description

The project backup task has a limited scope: tables (dictionary and data export), views (either as a logical table or as an exported table), resources, files and report templates. Other project elements that are not part of the backup: user and group permissions, view change history, table analysis, report executions etc.

Usage

opal.project_backup(
  opal,
  project,
  archive,
  viewsAsTables = FALSE,
  override = TRUE,
  wait = TRUE
)

Arguments

opal

Opal object.

project

Name of the project.

archive

Archive directory path in the Opal file system. If folder (and parents) does not exist, it will be created.

viewsAsTables

Treat views as tables, i.e. export data instead of keeping derivation scripts. Default is FALSE.

override

Overwrite an existing backup folder. Default is TRUE.

wait

Wait for backup task completion. Default is TRUE.

Value

The project command ID if wait parameter is FALSE. See opal.project_command to retrieve asynchronous command state.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.project_backup(o, 'GREENSPACE', '/home/administrator/backup/GREENSPACE')
opal.file_download(o, '/home/administrator/backup/GREENSPACE', 'GREENSPACE.zip')
opal.logout(o)

## End(Not run)

Get project task

Description

Get the project's task command object.

Usage

opal.project_command(opal, project, id)

Arguments

opal

Opal object.

project

Name of the project.

id

The project command ID.

Value

The command state object.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
id <- opal.project_backup(o, 'GREENSPACE', '/home/administrator/backup/GREENSPACE', wait = FALSE)
opal.project_command(opal, 'GREENSPACE', id)
opal.logout(o)

## End(Not run)

Create a project

Description

Create a project

Usage

opal.project_create(
  opal,
  project,
  database = NULL,
  title = NULL,
  description = NULL,
  tags = NULL,
  exportFolder = NULL
)

Arguments

opal

Opal object.

project

Name of the project

database

The database name (as declared in Opal) to be used to store project's data. If not provided, the project can have views and resources but no raw tables. If the the value is a logical and is TRUE, the default database will be selected or the first one if there is no default.

title

The title of the project (optional).

description

The description of the project (optional).

tags

A list of tag names (optional).

exportFolder

The default location of the exported data files in the Opal file system (optional).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# with named database
opal.project_create(o, 'test', database='opal_data', title='This is a test', tags=list('Test'))
# with default database
opal.project_create(o, 'test_default_db', database = TRUE)
# no database, for views and resources only
opal.project_create(o, 'test_no_db')
opal.logout(o)

## End(Not run)

Delete a project

Description

Delete a project and every data what could have been associated to it.

Usage

opal.project_delete(opal, project, archive = FALSE, silent = TRUE)

Arguments

opal

Opal object.

project

Name of the project

archive

Logical that is TRUE if the complete removal of the project is requested.

silent

Warn if project does not exist, default is TRUE.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.project_delete(o, 'test')
opal.logout(o)

## End(Not run)

Check a project exists

Description

Check whether a project already exists (and is visible by the requesting user).

Usage

opal.project_exists(opal, project)

Arguments

opal

Opal object.

project

Name of the project

Value

A logical

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.project_exists(o, 'test')
opal.logout(o)

## End(Not run)

Get the permissions on a project

Description

Get the permissions that were applied on a project.

Usage

opal.project_perm(opal, project)

Arguments

opal

Opal connection object.

project

Project name.

Value

A data.frame with columns: subject, type, permission

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.project_perm_add(o, 'CNSIM', c('andrei', 'valentina'), 'user', 'administrate')
opal.project_perm(o, 'CNSIM')
opal.project_perm_delete(o, 'CNSIM', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Add or update a permission on a project

Description

Add or update a permission on a project.

Usage

opal.project_perm_add(
  opal,
  project,
  subject,
  type = "user",
  permission = "administrate"
)

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

permission

The permission to apply: administrate.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.project_perm_add(o, 'CNSIM', c('andrei', 'valentina'), 'user', 'administrate')
opal.project_perm(o, 'CNSIM')
opal.project_perm_delete(o, 'CNSIM', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Delete a permission from a project

Description

Delete a permission that was applied on a project. Silently returns when there is no such permission.

Usage

opal.project_perm_delete(opal, project, subject, type = "user")

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.project_perm_add(o, 'CNSIM', c('andrei', 'valentina'), 'user', 'administrate')
opal.project_perm(o, 'CNSIM')
opal.project_perm_delete(o, 'CNSIM', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Restore a project

Description

Restore the data of a project from a backup archive file to be found on the Opal file system. The destination project must exist and can have a name different from the original one (beware that this could break views). Default behavior is to stop when an item to restore already exist (override can be forced).

Usage

opal.project_restore(
  opal,
  project,
  archive,
  key = NULL,
  override = TRUE,
  wait = TRUE
)

Arguments

opal

Opal object.

project

Name of the project.

archive

Archive directory or zip file path in the Opal file system.

key

Archive zip file password (if applies).

override

Overwrite existing items (table, view, resource, report). Project files override is not checked. Default is TRUE.

wait

Wait for restore task completion. Default is TRUE.

Value

The project command ID if wait parameter is FALSE. See opal.project_command to retrieve asynchronous command state.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# create the project to restore, with the default database (to store tables)
opal.project_create(o, 'GREENSPACE2', database = TRUE)
# upload backup zip and launch restore task
opal.file_upload(o, 'GREENSPACE.zip', '/home/administrator')
opal.project_restore(o, 'GREENSPACE2', '/home/administrator/GREENSPACE.zip')
opal.logout(o)

## End(Not run)

Get projects

Description

Get projects

Usage

opal.projects(opal, df = TRUE)

Arguments

opal

Opal object.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.projects(o)
opal.logout(o)

## End(Not run)

Get projects databases

Description

When creating a project for storing data, it is required to name the database to be associated.

Usage

opal.projects_databases(opal)

Arguments

opal

Opal object.

Value

A character vector of databases names.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.projects_databases(o)
opal.logout(o)

## End(Not run)

Generic REST resource update.

Description

Generic REST resource update.

Usage

opal.put(
  opal,
  ...,
  query = list(),
  body = "",
  contentType = "application/x-rscript",
  callback = NULL
)

Arguments

opal

Opal object.

...

Resource path segments.

query

Named list of query parameters.

body

The body of the request.

contentType

The type of the body content.

callback

A callback function to handle the response object.

Examples

## Not run: 
o <- opal.login('administrator','password', url = 'https://opal-demo.obiba.org')
opal.put(o, 'some', 'resource', 'toupdate', body = '{"some":"value"}')
opal.logout(o)

## End(Not run)

Opal report

Description

Helper function for generating reports.

Usage

opal.report(
  input,
  output = NULL,
  progress = FALSE,
  verbose = FALSE,
  boot_style = NULL
)

Arguments

input

Path to the R markdown report file

output

Directory path where to ouput the html report file. Default is the current working directory.

progress

Knitr progress option

verbose

Knitr verbose option

boot_style

Deprecated, directives can be integrated in the YAML header of the R markdown document.

Examples

## Not run: 
opal.report('input.Rmd', 'report', progress=TRUE)

## End(Not run)

Turn a R markdown file to html.

Description

Turn a R markdown file to html.

Usage

opal.report_md(inputFile, progress, verbose)

Get a resource reference of a project

Description

Get a resource reference of a project

Usage

opal.resource(opal, project, resource)

Arguments

opal

Opal object.

project

Name of the project.

resource

Name of the resource in the project.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resource(o, 'RSRC', 'CNSIM1')
opal.logout(o)

## End(Not run)

Create a resource reference in a project

Description

Create a resource reference in a project

Usage

opal.resource_create(
  opal,
  project,
  name,
  url,
  description = NULL,
  format = NULL,
  package = NULL,
  identity = NULL,
  secret = NULL
)

Arguments

opal

Opal object.

project

Name of the project.

name

Name of the resource in the project.

url

The URL of the resource.

description

The description of the resource (optional).

format

The format of the data described by the resource (optional).

package

The R package to be loaded prior to the assignment of the resource (optional).

identity

The identity key or username to be used when accessing the resource (optional).

secret

The secret key or password to be used when accessing the resource (optional).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resource_create(o, 'RSRC', 'CNSIM4', 
  url = 'opal+https://opal-demo.obiba.org/ws/files/projects/RSRC/CNSIM3.zip', 
  format = 'csv', secret = 'EeTtQGIob6haio5bx6FUfVvIGkeZJfGq')
opal.logout(o)

## End(Not run)

Delete a resource reference

Description

Removes the reference to a resource. The targeted resource remains untouched.

Usage

opal.resource_delete(opal, project, resource, silent = TRUE)

Arguments

opal

Opal connection object.

project

Project name where the resource is located.

resource

Resource name to be deleted.

silent

Warn if resource does not exist, default is TRUE.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resource_delete(o, "RSRC", "CNSIM4")
opal.logout(o)

## End(Not run)

Check a resource reference exists

Description

Check whether a resource already exists in the project (and is visible by the requesting user).

Usage

opal.resource_exists(opal, project, resource)

Arguments

opal

Opal object.

project

Name of the project.

resource

Name of the resource in the project.

Value

A logical

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resource_exists(o, 'RSRC', 'CNSIM1')
opal.logout(o)

## End(Not run)

Create an extended resource reference in a project

Description

Create an extended resource reference in a project

Usage

opal.resource_extension_create(
  opal,
  project,
  name,
  provider,
  factory,
  parameters,
  description = NULL,
  credentials = NULL
)

Arguments

opal

Opal object.

project

Name of the project.

name

Name of the resource in the project.

provider

Name of the R package in which the resource is defined.

factory

Name of the JS function that turns parameters and credentials into a resource object.

parameters

A named list of the resource parameters.

description

The description of the resource (optional).

credentials

A named list of the resource credentials (optional).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resource_extension_create(o, 'RSRC', 'ga4gh_1000g',
  provider = 'dsOmics', factory = 'ga4gh-htsget',
  parameters = list(
    host = 'https://htsget.ga4gh.org',
    sample = '1000genomes.phase1.chr1',
    reference = '1',
    start = '1',
    end = '100000',
    format = 'GA4GHVCF'
  )
)
opal.logout(o)

## End(Not run)

Get the resource object of a project

Description

Get the resource object of a project

Usage

opal.resource_get(opal, project, resource)

Arguments

opal

Opal object.

project

Name of the project.

resource

Name of the resource in the project.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
res <- opal.resource_get(o, 'RSRC', 'CNSIM1')
# then interpret locally the resource object (load the appropriate R packages)
library(resourcer)
# coerce to a data.frame
as.data.frame(res)
# or get the resource client object for low-level interactions
rescli <- resourcer::newResourceClient(res)
opal.logout(o)

## End(Not run)

Get the permissions on a resource

Description

Get the permissions that were applied on a resource.

Usage

opal.resource_perm(opal, project, resource)

Arguments

opal

Opal connection object.

project

The project name.

resource

The resource name.

Value

A data.frame with columns: subject, type, permission

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resource_perm_add(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user', 'view')
opal.resource_perm(o, 'CNSIM', 'CNSIM1')
opal.resource_perm_delete(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Add or update a permission on a resource

Description

Add or update a permission on a resource

Usage

opal.resource_perm_add(
  opal,
  project,
  resource,
  subject,
  type = "user",
  permission
)

Arguments

opal

Opal connection object.

project

The project name.

resource

The resource name.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

permission

The permission to apply: view, administrate. The 'view' permission is suitable for DataSHIELD operations.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resource_perm_add(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user', 'view')
opal.resource_perm(o, 'CNSIM', 'CNSIM1')
opal.resource_perm_delete(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Delete a permission from a resource

Description

Delete a permission that was applied on a resource. Silently returns when there is no such permission.

Usage

opal.resource_perm_delete(opal, project, resource, subject, type = "user")

Arguments

opal

Opal connection object.

project

The project name.

resource

The resource name.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resource_perm_add(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user', 'view')
opal.resource_perm(o, 'CNSIM', 'CNSIM1')
opal.resource_perm_delete(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Create an Opal view over a resource reference

Description

Create an Opal view if a table with same name does not already exist. The resource reference is required.The dictionary of the created view will be discovered at initialization time. Use opal.table_dictionary_update to apply a dictionary.

Usage

opal.resource_view_create(
  opal,
  project,
  table,
  resource,
  type = "Participant",
  idColumn = NULL,
  profile = NULL
)

Arguments

opal

Opal connection object.

project

Project name where the view will be located.

table

View name to be created.

resource

Fully qualified resource name.

type

Entity type, default is "Participant".

idColumn

Name of the column which contains the entity identifiers. If not specified, the first column will be used.

profile

R server profile to use for establishing the connection with the resource. If not specifed, the profile will guessed based on the resource definition.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# make a view over a resource
opal.resource_view_create(o, "CNSIM", "CNSIM4", resource = "RSRC.CNSIM1")
opal.resource_view_create(o, "CNSIM", "FEMALE_2439", 
                          resource = "RSRC.FEMALE_2439", idColumn = "Name")
opal.logout(o)

## End(Not run)

Reconnect an Opal view to its underlying resource

Description

A view over a resource handles a connection to this resource. When the resource changes (data update, broken connection etc.), the connection to this resource can be re-initialized.

Usage

opal.resource_view_reconnect(opal, project, table)

Arguments

opal

Opal connection object.

project

Project name where the view is located.

table

View name to be reconnected.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# make a view over a resource
opal.resource_view_create(o, "CNSIM", "CNSIM4", resource = "RSRC.CNSIM1")
# re-initialize the view's connection to the resource
opal.resource_view_reconnect(o, "CNSIM", "CNSIM4")
opal.logout(o)

## End(Not run)

Get the resource references of a project

Description

Get the resource references of a project

Usage

opal.resources(opal, project, df = TRUE)

Arguments

opal

Opal object.

project

Name of the project.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resources(o, 'RSRC')
opal.logout(o)

## End(Not run)

Get the permissions on any resource

Description

Get the permissions that were applied globally on the project's resources.

Usage

opal.resources_perm(opal, project)

Arguments

opal

Opal connection object.

project

The project name.

Value

A data.frame with columns: subject, type, permission

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resources_perm_add(o, 'CNSIM', c('andrei', 'valentina'), 'user', 'view')
opal.resources_perm(o, 'CNSIM')
opal.resources_perm_delete(o, 'CNSIM', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Add or update a permission on any resource

Description

Add or update a global permission on the project's resources

Usage

opal.resources_perm_add(opal, project, subject, type = "user", permission)

Arguments

opal

Opal connection object.

project

The project name.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

permission

The permission to apply: view, administrate. The 'view' permission is suitable for DataSHIELD operations.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resources_perm_add(o, 'CNSIM', c('andrei', 'valentina'), 'user', 'view')
opal.resources_perm(o, 'CNSIM')
opal.resources_perm_delete(o, 'CNSIM', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Delete a permission from any resource

Description

Delete a permission that was applied globally on the project's resources. Silently returns when there is no such permission.

Usage

opal.resources_perm_delete(opal, project, subject, type = "user")

Arguments

opal

Opal connection object.

project

The project name.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.resources_perm_add(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user', 'view')
opal.resources_perm(o, 'CNSIM', 'CNSIM1')
opal.resources_perm_delete(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Remove a R symbol (deprecated)

Description

Remove a symbol from the current R session. Deprecated: see opal.symbol_rm function instead.

Usage

opal.rm(opal, symbol)

Arguments

opal

Opal object.

symbol

Name of the R symbol.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.rm(o, 'D')
opal.logout(o)

## End(Not run)

Execute a SQL query on tables

Description

The SQL query can apply to raw tables and/or views and require the permission to view the values of these tables. When all tables belong to a project, it is possible to simplify the SQL query by providing the project name parameter. Otherwise the fully qualified table names ('<project>.<table>') must be specified in the FROM statements.

Usage

opal.sql(opal, query, project = NULL, id.name = "_id")

Arguments

opal

Opal connection object.

query

The SQL query statement.

project

Project name where the table(s) are located. If not provided, the SQL query must refer to the full table name(s) (use backquotes to escape, see examples).

id.name

The name of the column representing the entity identifiers. Default is '_id'.

Value

The lists of columns and rows, as a data.frame.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# with project context
opal.sql(o,  
  'select avg(LAB_HDL) as HDL_AVG, GENDER 
     from CNSIM1 
     where LAB_HDL is not null 
     group by GENDER',
  'CNSIM')
# without project context
opal.sql(o,
  'select avg(LAB_HDL) as HDL_AVG, GENDER 
     from `CNSIM.CNSIM1` 
     where LAB_HDL is not null 
     group by GENDER')
opal.logout(o)

## End(Not run)

SQL query execution history

Description

Getting the SQL execution is for being able to re-execute a previously submitted own SQL query (regular users) and for auditing users SQL activity (administrators only).

Usage

opal.sql_history(
  opal,
  project = NULL,
  offset = 0,
  limit = 100,
  user = NULL,
  df = TRUE
)

Arguments

opal

Opal connection object.

project

Project name used as the SQL execution context, to filter. If not specified, history from any context is returned. If NA is specified, the history of SQL executions without context is returned. Default is NULL.

offset

Number of history items to skip. Default is 0 (note that the items are ordered by most recent first).

limit

Maximum number of history items to return. Default is 100.

user

Filter by user name, only administrators can retrieve SQL history of other users. If NA is specified, the SQL execution history of all users will be retrieved. Default is the current user name.

df

Result is a data.frame or a list of raw data.

Value

A data frame.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# with project context
opal.sql_history(o, 'CNSIM')
# without project context
opal.sql_history(o, NA)
# with or without project context
opal.sql_history(o)
opal.logout(o)

## End(Not run)

Import a tibble

Description

Import a tibble identified by the symbol as a table in Opal. This operation creates an importation task in Opal that can be followed (see tasks related functions).

Usage

opal.symbol_import(
  opal,
  symbol,
  project,
  identifiers = NULL,
  policy = "required",
  id.name = "id",
  type = "Participant",
  wait = TRUE
)

Arguments

opal

Opal object.

symbol

Name of the R symbol representing a tibble.

project

Name of the project into which the data are to be imported.

identifiers

Name of the identifiers mapping to use when assigning entities to Opal.

policy

Identifiers policy: 'required' (each identifiers must be mapped prior importation (default)), 'ignore' (ignore unknown identifiers) and 'generate' (generate a system identifier for each unknown identifier).

id.name

The name of the column representing the entity identifiers. Default is 'id'.

type

Entity type (what the data are about). Default is 'Participant'.

wait

Wait for import task completion. Default is TRUE.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.symbol_import(o, 'D', 'test')
opal.logout(o)

## End(Not run)

Remove a R symbol

Description

Remove a symbol from the remote R session.

Usage

opal.symbol_rm(opal, symbol)

Arguments

opal

Opal object.

symbol

Name of the R symbol.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.symbol_rm(o, 'D')
opal.logout(o)

## End(Not run)

Save a tibble

Description

Save a tibble identified by symbol as a file of format SAS, SPSS, Stata, CSV or TSV in the remote R session working directory.

Usage

opal.symbol_save(opal, symbol, destination)

Arguments

opal

Opal object.

symbol

Name of the R symbol representing a tibble.

destination

The path of the file in the R session workspace. Supported file extensions are: .sav (SPSS), .zsav (compressed SPSS), .sas7bdat (SAS), .xpt (SAS Transport), .dta (Stata), .csv (comma separated values), .tsv (tab separated values).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.symbol_save(o, 'D', 'test.sav')
opal.logout(o)

## End(Not run)

List R symbols

Description

Get the R symbols available in the remote R session.

Usage

opal.symbols(opal)

Arguments

opal

Opal object.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.symbols(o)
opal.logout(o)

## End(Not run)

Get a table of a datasource

Description

Get a table of a datasource

Usage

opal.table(opal, datasource, table, counts = FALSE)

Arguments

opal

Opal object.

datasource

Name of the datasource.

table

Name of the table in the datasource.

counts

Flag to get the number of variables and entities (default is FALSE).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.table(o, 'CNSIM', 'CNSIM1')
opal.logout(o)

## End(Not run)

Create an Opal table or view

Description

Create an Opal table if it does not already exist. If a list of table references are provided, the table will be a view. The table/view created will have no dictionary, use opal.table_dictionary_update to apply a dictionary.

Usage

opal.table_create(opal, project, table, type = "Participant", tables = NULL)

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

table

Table name to be created

type

Entity type, default is "Participant". Ignored if some table references are provided.

tables

List of the fully qualified table names that are referred by the view.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# make a raw table
opal.table_create(o, "CNSIM", "CNSIM4")
# make a view
opal.table_create(o, "CNSIM", "CNSIM123", 
                  tables = c("CNSIM.CNSIM1", "CNSIM.CNSIM2", "CNSIM.CNSIM3"))
opal.logout(o)

## End(Not run)

Delete a Opal table

Description

Removes both values and data dictionary of a table, or remove the table's logic if the table is a view. Fails if the table does not exist. See also opal.table_truncate.

Usage

opal.table_delete(opal, project, table, silent = TRUE)

Arguments

opal

Opal connection object.

project

Project name where the table is located.

table

Table name to be deleted.

silent

Warn if table does not exist, default is TRUE.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.table_delete(o, "CNSIM", "CNSIM1")
opal.logout(o)

## End(Not run)

Get the dictionary of a Opal table

Description

Get the dictionary of a Opal table in a format that can be re-applied with opal.table_dictionary_update.

Usage

opal.table_dictionary_get(opal, project, table)

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

table

Table name.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
dico <- opal.table_dictionary_get(o, "CNSIM", "CNSIM1")
opal.logout(o)

## End(Not run)

Update the dictionary of a Opal table

Description

Directly update the dictionary of a Opal table with the provided dictionary.

Usage

opal.table_dictionary_update(
  opal,
  project,
  table,
  variables,
  categories = NULL
)

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

table

Destination table name.

variables

A data frame with one row per variable (column name) and then one column per property/attribute (Opal Excel format).

categories

A data frame with one row per category (columns variable and name) and then column per property/attribute (Opal Excel format). If there are no categories, this parameter is optional.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
variables <- tibble::tribble(
  ~name, ~valueType, ~`label:en`,  ~`Namespace::Name`, ~unit, ~repeatable, ~index,
  "mpg", "decimal", "Mpg label",  "Value1", "years", 0, 1,
  "cyl", "decimal", "Cyl label",  "Value2", "kg/m2", 0, 2,
  "disp", "decimal", "Disp label", NA, NA, 1, 3
)
categories <- tibble::tribble(
  ~variable, ~name, ~missing, ~`label:en`, ~`label:fr`,
  "cyl", "4", 0, "Four", "Quatre",
  "cyl", "6", 0, "Six", "Six",
  "cyl", "8", 1, "Height", "Huit"
)
opal.table_dictionary_update(o, "test", "mtcars", variables, categories)
opal.logout(o)

## End(Not run)

Check a Opal table exists

Description

Check whether a Opal table exists (and is visible). Optionally check whether the table is a raw table or a view.

Usage

opal.table_exists(opal, project, table, view = NA)

Arguments

opal

Opal connection object.

project

Project name where the table is located.

table

Table name.

view

Logical to perform an additional check whether the table is a view (TRUE) or a raw table (FALSE). If NULL or NA, the table can be indifferently a view or a raw table. Default is NA.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# check table exists
opal.table_exists(o, "CNSIM", "CNSIM1")
# check table exists AND is a NOT a view
opal.table_exists(o, "CNSIM", "CNSIM1", view = FALSE)
# check table exists AND is a view
opal.table_exists(o, "CNSIM", "CNSIM1", view = TRUE)
opal.logout(o)

## End(Not run)

Export a table as a file

Description

Export a table as file in the specified format. The file destination is in the Opal server file system. See opal.file_download to download the file locally. See also opal.table_get to get directly the table as an R object.

Usage

opal.table_export(
  opal,
  project,
  table,
  file,
  identifiers = NULL,
  id.name = "id",
  wait = TRUE
)

Arguments

opal

Opal connection object.

project

Project name where the table is located.

table

Table name to export.

file

Destination file in the Opal file system. The expected file extensions are: rds (RDS), sav (SPSS), zsav (SPSS compressed), sas7bdat (SAS), xpt (SAS Transport), dta (Stata).RDS (serialized single R object) is to be read by base::readRDS(), while other formats are supported by the haven R package.

identifiers

Name of the identifiers mapping to use when exporting entities from Opal.

id.name

The name of the column representing the entity identifiers. Default is 'id'.

wait

Wait for import task completion. Default is TRUE.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
cqx <- opal.table_export(o, "CNSIM", "CNSIM1", 
                         file = "/home/administrator/cnsim1.sav")
opal.logout(o)

## End(Not run)

Get a Opal table as a tibble

Description

Shortcut function to assign a Opal table to a tibble in the R server-side session and then retrieve it into the R client-side session. Requires to have the permission to see the individual values of the table and to perform R assignments.

Usage

opal.table_get(
  opal,
  project,
  table,
  id.name = "id",
  variables = NULL,
  missings = TRUE
)

Arguments

opal

Opal connection object.

project

Project name where the table is located.

table

Table name from which the tibble should be extracted.

id.name

The name of the column representing the entity identifiers. Default is 'id'. Requires Opal 4.0+.

variables

(Deprecated) List of variable names or Javascript expression that selects the variables of a table (ignored if value does not refer to a table). See javascript documentation: http://wiki.obiba.org/display/OPALDOC/Variable+Methods

missings

(Deprecated) Include the missing values (default is TRUE).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
cqx <- opal.table_get(o, "CPTP", "Cag_coreqx")
opal.logout(o)

## End(Not run)

Import a file as table

Description

Import a file as a table in Opal. The file formats supported are: RDS (.rds), SPSS (.sav), SPSS compressed (.zsav), SAS (.sas7bdat), SAS Transport (.xpt), Stata (.dta). The RDS format is a serialized single R object (expected to be of tibble class), that can be obtained using base::saveRDS(). The other file formats are the ones supported by the haven R package. This operation creates an importation task in Opal that can be followed (see tasks related functions).

Usage

opal.table_import(
  opal,
  file,
  project,
  table,
  identifiers = NULL,
  policy = "required",
  id.name = "id",
  type = "Participant",
  wait = TRUE
)

Arguments

opal

Opal object.

file

Path in Opal to the file that will be read as a tibble.

project

Name of the project into which the data are to be imported.

table

Destination table name.

identifiers

Name of the identifiers mapping to use when assigning entities to Opal.

policy

id.name

The name of the column representing the entity identifiers. Default is 'id'.

type

Entity type (what the data are about). Default is 'Participant'.

wait

Wait for import task completion. Default is TRUE.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.table_import(o, '/home/administrator/mydataset.rds', 'test', 'mytable')
opal.logout(o)

## End(Not run)

Get the permissions on a table

Description

Get the permissions that were applied on a table.

Usage

opal.table_perm(opal, project, table)

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

table

Destination table name.

Value

A data.frame with columns: subject, type, permission

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.table_perm_add(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user', 'view')
opal.table_perm(o, 'CNSIM', 'CNSIM1')
opal.table_perm_delete(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Add or update a permission on a table

Description

Add or update a permission on a table.

Usage

opal.table_perm_add(opal, project, table, subject, type = "user", permission)

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

table

Destination table name.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

permission

The permission to apply: view, view-values, edit, edit-values, administrate. The 'view' permission is suitable for DataSHIELD operations.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.table_perm_add(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user', 'view')
opal.table_perm(o, 'CNSIM', 'CNSIM1')
opal.table_perm_delete(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Delete a permission from a table

Description

Delete a permission that was applied on a table. Silently returns when there is no such permission.

Usage

opal.table_perm_delete(opal, project, table, subject, type = "user")

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

table

Destination table name.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.table_perm_add(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user', 'view')
opal.table_perm(o, 'CNSIM', 'CNSIM1')
opal.table_perm_delete(o, 'CNSIM', 'CNSIM1', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Save a local tibble as a Opal table

Description

Upload a local tibble to the R server side through Opal, assign this tibble to the provided symbol name and import it as a table into a Opal project.

Usage

opal.table_save(
  opal,
  tibble,
  project,
  table,
  overwrite = TRUE,
  force = FALSE,
  identifiers = NULL,
  policy = "required",
  id.name = "id",
  type = "Participant"
)

Arguments

opal

Opal connection object.

tibble

The tibble object to be imported.

project

Project name where the table will be located.

table

Destination table name.

overwrite

If the destination table already exists, it will be replaced (deleted, re-created with associated permissions reinstated and then imported). Otherwise the table will be updated (data dictionaries merge may conflict). Default is TRUE. See also opal.table_truncate function.

force

If the destination already exists, stop with an informative message if this flag is FALSE (default).

identifiers

Name of the identifiers mapping to use when assigning entities to Opal.

policy

Identifiers policy: 'required' (each identifiers must be mapped prior importation (default)), ignore' (ignore unknown identifiers) and 'generate' (generate a system identifier for each unknown identifier).

id.name

The name of the column representing the entity identifiers. Default is 'id'.

type

Entity type (what the data are about). Default is 'Participant'

Value

An invisible logical indicating whether the destination table exists.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
cqx <- opal.table_get(o, "CPTP", "Cag_coreqx")
# do some (meta)data transformations, then save in opal's database
opal.table_save(o, cqx, "CPTP", "Cag_coreqx", overwrite = TRUE, force = TRUE)
# or overwrite data only (keep original data dictionary)
opal.table_save(o, cqx, "CPTP", "Cag_coreqx", overwrite = 'values', force = TRUE)
opal.logout(o)

## End(Not run)

Truncate a Opal table

Description

Removes the values of a table and keep the dictionary untouched. Fails if the table does not exist or is a view. See also opal.table_delete.

Usage

opal.table_truncate(opal, project, table)

Arguments

opal

Opal connection object.

project

Project name where the table is located.

table

Table name to be truncated.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.table_truncate(o, "CNSIM", "CNSIM1")
opal.logout(o)

## End(Not run)

Create an Opal view over tables

Description

Create an Opal view if a table with same name does not already exist. The view created will have no dictionary, use opal.table_dictionary_update to apply a dictionary.

Usage

opal.table_view_create(opal, project, table, tables, type = "Participant")

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

table

Table name to be created

tables

List of the fully qualified table names that are referred by the view.

type

Entity type, default is "Participant". Ignored if some table references are provided.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# make a view
opal.table_view_create(o, "CNSIM", "CNSIM123", 
                       c("CNSIM.CNSIM1", "CNSIM.CNSIM2", "CNSIM.CNSIM3"))
opal.logout(o)

## End(Not run)

Update the table references and the entity filter of an Opal view

Description

Update the table references and/or the entity filter of an existing Opal view. The view dictionary will NOT be modified (use opal.table_dictionary_update to apply a dictionary).

Usage

opal.table_view_update(opal, project, table, tables = NULL, where = NULL)

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

table

Table name to be created.

tables

List of the fully qualified table names that are referred by the view. Not modified when NULL (default).

where

The entity filter script. Not modified when NULL (default). To remove the filter, set an empty string.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# make a view
opal.table_view_create(o, "CNSIM", "CNSIM123",
                       c("CNSIM.CNSIM1"))

# update the table references
opal.table_view_update(o, "CNSIM", "CNSIM123",
                       tables = c("CNSIM.CNSIM1", "CNSIM.CNSIM2", "CNSIM.CNSIM3"))

# update the entity filter
opal.table_view_update(o, "CNSIM", "CNSIM123", where = "$('LAB_TSC').ge(5)")

# remove the entity filter
opal.table_view_update(o, "CNSIM", "CNSIM123", where = "")

# update both the table references and the entity filter
opal.table_view_update(o, "CNSIM", "CNSIM123",
                       tables = c("CNSIM.CNSIM1", "CNSIM.CNSIM2", "CNSIM.CNSIM3"),
                       where = "$('LAB_TSC').ge(5)")
opal.logout(o)

## End(Not run)

Get tables of a datasource

Description

Get tables of a datasource

Usage

opal.tables(opal, datasource, counts = FALSE, df = TRUE)

Arguments

opal

Opal object.

datasource

Name of the datasource.

counts

Flag to get the number of variables and entities (default is FALSE).

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.tables(o, 'CNSIM')
opal.logout(o)

## End(Not run)

Get the permissions on any table of a project

Description

Get the permissions that were applied on any table of a project.

Usage

opal.tables_perm(opal, project)

Arguments

opal

Opal connection object.

project

Project name.

Value

A data.frame with columns: subject, type, permission

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.tables_perm_add(o, 'CNSIM', c('andrei', 'valentina'), 'user', 'administrate')
opal.tables_perm(o, 'CNSIM')
opal.tables_perm_delete(o, 'CNSIM', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Add or update a permission on any table of a project

Description

Add or update a permission on any table of a project.

Usage

opal.tables_perm_add(opal, project, subject, type = "user", permission)

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

permission

The permission to apply: view-values, add, or administrate.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.tables_perm_add(o, 'CNSIM', c('andrei', 'valentina'), 'user', 'administrate')
opal.tables_perm(o, 'CNSIM')
opal.tables_perm_delete(o, 'CNSIM', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Delete a permission from any table of a project

Description

Delete a permission that was applied on any table of a project. Silently returns when there is no such permission.

Usage

opal.tables_perm_delete(opal, project, subject, type = "user")

Arguments

opal

Opal connection object.

project

Project name where the table will be located.

subject

A vector of subject identifiers: user names or group names (depending on the type).

type

The type of subject: user (default) or group.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.tables_perm_add(o, 'CNSIM', c('andrei', 'valentina'), 'user', 'administrate')
opal.tables_perm(o, 'CNSIM')
opal.tables_perm_delete(o, 'CNSIM', c('andrei', 'valentina'), 'user')
opal.logout(o)

## End(Not run)

Get a task

Description

Get the details of a specific task.

Usage

opal.task(opal, id)

Arguments

opal

Opal object.

id

Task identifier.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.task(o, '1')
opal.logout(o)

## End(Not run)

Cancel a task

Description

Tries to cancel a task.

Usage

opal.task_cancel(opal, id)

Arguments

opal

Opal object.

id

Task identifier.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.task_cancel(o, '1')
opal.logout(o)

## End(Not run)

Wait for a task to complete.

Description

The task completion is defined by its status: *SUCCEEDED*, *FAILED* or *CANCELED*.

Usage

opal.task_wait(opal, id, max = NULL)

Arguments

opal

Opal object.

id

Task identifier.

max

Maximum time (in seconds) to wait for the task completion. Default is NULL (no maximum).

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.task_wait(o, '1')
opal.logout(o)

## End(Not run)

Get the tasks

Description

Get all the tasks with their status at the time of the request.

Usage

opal.tasks(opal, df = TRUE)

Arguments

opal

Opal object.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.tasks(o)
opal.logout(o)

## End(Not run)

Get taxonomies

Description

Get all taxonomies. A taxonomy describes the annotations that can be applied to the variables. Taxonomies also drive the variables search interface.

Usage

opal.taxonomies(opal, locale = "en", df = TRUE)

Arguments

opal

Opal object.

locale

The language for labels (default is "en").

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.taxonomies(o)
opal.logout(o)

## End(Not run)

Get a taxonomy

Description

Get a specific taxonomy details.

Usage

opal.taxonomy(opal, taxonomy)

Arguments

opal

Opal object.

taxonomy

Name of the taxonomy.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.taxonomy(o, 'Mlstr_area')
opal.logout(o)

## End(Not run)

Delete a taxonomy

Description

Delete a taxonomy, without failing if the taxonomy does not exist.

Usage

opal.taxonomy_delete(opal, taxonomy)

Arguments

opal

Opal object.

taxonomy

Name of the taxonomy.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.taxonomy_delete(o, 'Mlstr_area')
opal.logout(o)

## End(Not run)

Download a taxonomy file

Description

Download a taxonomy stored in a file in YAML format.

Usage

opal.taxonomy_download(opal, taxonomy, destination = NULL)

Arguments

opal

Opal object.

taxonomy

Name of the taxonomy.

destination

Path to the taxonomy YAML file. If not provided, the downloaded file will have the taxonomy name with the '.yml' extension and will be located in the working directory.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.taxonomy_download(o, 'Mlstr_area', '~/some/dir/Mlstr_area.yml')
opal.logout(o)

## End(Not run)

Upload a taxonomy file

Description

Upload a taxonomy stored in a local file in YAML format. This operation will fail if the taxonomy already exists, see opal.taxonomy_delete.

Usage

opal.taxonomy_upload(opal, path)

Arguments

opal

Opal object.

path

Path to the taxonomy YAML file.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.taxonomy_upload(o, '~/some/dir/taxo.yml')
opal.logout(o)

## End(Not run)

Get the terms of a vocabulary

Description

Get all the terms of a vocabulary. The term describes the value of a variable annotation.

Usage

opal.terms(opal, taxonomy, vocabulary, locale = "en", df = TRUE)

Arguments

opal

Opal object.

taxonomy

Name of the taxonomy

vocabulary

Name of the vocabulary in the taxonomy

locale

The language for labels (default is "en").

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.terms(o, 'Mlstr_area', 'Lifestyle_behaviours')
opal.logout(o)

## End(Not run)

Get a personal access token

Description

Get a personal access token details. Like for the other token functions, this operation requires the user to authenticate with username/password credentials.

Usage

opal.token(opal, name)

Arguments

opal

Opal object.

name

Name of the token

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.token(o, 'sql-1')
opal.logout(o)

## End(Not run)

Create a personal access token for Datashield usage

Description

Create a personal access token for Datashield usage. Like for the other token functions, this operation requires the user to authenticate with username/password credentials.

Usage

opal.token_datashield_create(opal, name, projects = NULL)

Arguments

opal

Opal object.

name

Name of the token

projects

Vector of project names, to which the token applies. Default is NULL (all projects).

Value

The token value.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
token <- opal.token_datashield_create(o, 'ds-1')
opal.logout(o)

## End(Not run)

Delete a personal access token

Description

Delete a personal access token permanently. Like for the other token functions, this operation requires the user to authenticate with username/password credentials.

Usage

opal.token_delete(opal, name)

Arguments

opal

Opal object.

name

Name of the token

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.token_delete(o, 'sql-1')
opal.logout(o)

## End(Not run)

Create a personal access token for R usage

Description

Create a personal access token for R (server) usage. Like for the other token functions, this operation requires the user to authenticate with username/password credentials.

Usage

opal.token_r_create(
  opal,
  name,
  projects = NULL,
  access = NULL,
  commands = c("export")
)

Arguments

opal

Opal object.

name

Name of the token

projects

Vector of project names, to which the token applies. Default is NULL (all projects).

access

Data access level: 'READ' (read-only) or 'READ_NO_VALUES' (read-only, without access to individual-level data) or NULL (default).

commands

Task commands that can launched on a project: 'import' and/or 'export'. Default is 'export' (use NULL for no task commands).

Value

The token value.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
token <- opal.token_r_create(o, 'r-1', access = 'READ', commands = 'export')
opal.logout(o)

## End(Not run)

Renew an inactive personal access token

Description

Renew an inactive personal access token after it has been marked as being inactive. Like for the other token functions, this operation requires the user to authenticate with username/password credentials.

Usage

opal.token_renew(opal, name)

Arguments

opal

Opal object.

name

Name of the token

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.token_renew(o, 'sql-1')
opal.logout(o)

## End(Not run)

Create a personal access token for SQL usage

Description

Create a personal access token for SQL usage. Like for the other token functions, this operation requires the user to authenticate with username/password credentials.

Usage

opal.token_sql_create(opal, name, projects = NULL)

Arguments

opal

Opal object.

name

Name of the token

projects

Vector of project names, to which the token applies. Default is NULL (all projects).

Value

The token value.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
token <- opal.token_sql_create(o, 'sql-1')
opal.logout(o)

## End(Not run)

Get the personal access tokens

Description

Get the list of personal access tokens. Like for the other token functions, this operation requires the user to authenticate with username/password credentials.

Usage

opal.tokens(opal, df = TRUE)

Arguments

opal

Opal object.

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.tokens(o)
opal.logout(o)

## End(Not run)

Unload package

Description

Unload package from the remote R session.

Usage

opal.unload_package(opal, pkg)

Arguments

opal

Opal object or list of opal objects.

pkg

Package name.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.unload_package(o, 'stats')
opal.logout(o)

## End(Not run)

Get the values of an entity

Description

Get the values of an entity in a table.

Usage

opal.valueset(opal, datasource, table, identifier)

Arguments

opal

Opal object.

datasource

Name of the datasource.

table

Name of the table in the datasource.

identifier

Entity identifier.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.valueset(o, 'CNSIM', 'CNSIM1', '1008573362')
opal.logout(o)

## End(Not run)

Get a variable of a table

Description

Get a variable of a table

Usage

opal.variable(opal, datasource, table, variable)

Arguments

opal

Opal object.

datasource

Name of the datasource.

table

Name of the table in the datasource.

variable

Name of the variable in the table.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.variable(o, 'CNSIM', 'CNSIM1', 'GENDER')
opal.logout(o)

## End(Not run)

Get summary statistics of a variable of a table

Description

Get summary statistics of a variable of a table

Usage

opal.variable_summary(
  opal,
  datasource,
  table,
  variable,
  cached = TRUE,
  nature = NULL
)

Arguments

opal

Opal object.

datasource

Name of the datasource.

table

Name of the table in the datasource.

variable

Name of the variable in the table.

cached

Get cached summary if exists. When FALSE, the cached summary is evicted and replaced by the newly calculated one. Default is TRUE.

nature

Force summary nature, independently from the variable. Possible values are: CATEGORICAL, CONTINUOUS, TEMPORAL, GEO, BINARY, UNDETERMINED.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.variable_summary(o, 'CNSIM', 'CNSIM1', 'GENDER')
opal.logout(o)

## End(Not run)

Get variables of a table

Description

Get variables of a table

Usage

opal.variables(opal, datasource, table, locale = "en", df = TRUE)

Arguments

opal

Opal object.

datasource

Name of the datasource.

table

Name of the table in the datasource.

locale

The language for labels (default is "en").

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.variables(o, 'CNSIM', 'CNSIM1')
opal.logout(o)

## End(Not run)

Compare

Description

Compare Opal version with the provided one. Note that a request must have been done in order to have a non-null Opal version.

Usage

opal.version_compare(opal, version)

Arguments

opal

Opal object.

version

The semantic version string to be compared.

Value

>0 if Opal version is more recent, 0 if equals, <0 otherwise.

Examples

## Not run: 
o <- opal.login('administrator','password', url = 'https://opal-demo.obiba.org')
opal.version_compare(o, "2.6.0")
opal.logout(o)

## End(Not run)

Get the vocabularies of a taxonomy

Description

Get all the vocabularies of a taxonomy. A vocabulary describes the possible values of variable annotations.

Usage

opal.vocabularies(opal, taxonomy, locale = "en", df = TRUE)

Arguments

opal

Opal object.

taxonomy

Name of the taxonomy

locale

The language for labels (default is "en").

df

Return a data.frame (default is TRUE)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.vocabularies(o, 'Mlstr_area')
opal.logout(o)

## End(Not run)

Get a taxonomy vocabulary

Description

Get a specific vocabulary details.

Usage

opal.vocabulary(opal, taxonomy, vocabulary)

Arguments

opal

Opal object.

taxonomy

Name of the taxonomy

vocabulary

Name of the vocabulary in the taxonomy

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.vocabulary(o, 'Mlstr_area', 'Lifestyle_behaviours')
opal.logout(o)

## End(Not run)

Restore a R workspace from a opal.

Description

Restore a R workspace from a opal.

Usage

opal.workspace_restore(opal, ws)

Arguments

opal

Opal object.

ws

The workspace name

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.workspace_restore(o, 'test')
opal.logout(o)

## End(Not run)

Remove a R workspace from a opal.

Description

Remove a R workspace from a opal.

Usage

opal.workspace_rm(opal, ws, user = NULL)

Arguments

opal

Opal object.

ws

The workspace name

user

The user name associated to the worskpace. If not provided, the current user is applied.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.workspace_rm(o, 'test')
opal.logout(o)

## End(Not run)

Save the current session in a opal R workspace.

Description

Save the current session in a opal R workspace.

Usage

opal.workspace_save(opal, save = TRUE)

Arguments

opal

Opal object.

save

Save the workspace with given identifier (default is TRUE, current session ID if TRUE).

Value

The workspace ID (invisible)

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
# provide a workspace ID
opal.workspace_save(o, 'test')
# or use default one
id <- opal.workspace_save(o)
opal.logout(o)

## End(Not run)

Get the R workspaces from a opal.

Description

Get the R workspaces from a opal.

Usage

opal.workspaces(opal)

Arguments

opal

Opal object.

Examples

## Not run: 
o <- opal.login('administrator','password', url='https://opal-demo.obiba.org')
opal.workspaces(o)
opal.logout(o)

## End(Not run)

opalr: 'Opal' Data Repository Client and 'DataSHIELD' Utils

Description

Author(s)

See Also

Permsissions (ACLs) into a data frame.

Description

Usage

Turns a value into 0/1 numeric.

Description

Usage

Constructs the value for the Authorization header

Description

Usage

Turn expression into character strings.

Description

Usage

Extract JSON

Description

Usage

Extract label for locale. If not found, fallback to undefined language label (if any).

Description

Usage

Extract opalsid from cookie data frame.

Description

Usage

Wrapper of httr::content()

Description

Usage

Extract absolute path to the pem file

Description

Usage

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

Description

Usage

Get all R session in Opal.

Description

Usage

Handle error response

Description

Usage

Default request response handler.

Description

Usage

Default request response Location handler.

Description

Usage

Process response with default handler or the provided one

Description

Usage

Verbose option

Description

Usage

Check if response content is empty.

Description

Usage

Simple transformation function of a list into a JSON object/array.

Description

Usage

Create a new progress instance with default settings.

Description

Usage

Create a new R session in Opal.

Description

Usage

Create the opal object

Description

Usage

Remove a Opal session (logout)

Description

Usage

Remove a R session from Opal.

Description

Usage

Returns a list r such that r[[i]] == l[[i]][field] for all i:length(l)

Description

Usage

Output the progress status if option "datashield.progress" is allows to.

Description

Usage

Constructs the value for the X-Opal-Auth header