Package {dsROCrate}

Title: 'DataSHIELD' RO-Crate Governance Functions
Version: 0.1.0
Description: Tools for wrapping 'DataSHIELD' analyses into RO-Crate (Research Object Crate) objects. Provides functions to create structured metadata for federated data analysis projects, enabling governance tracking of data access, project membership, analysis execution and output validation across distributed data sources.
License: MIT + file LICENSE
Suggests: dsBaseClient, DSI, DSOpal, fs, knitr, MolgenisArmadillo, testthat (≥ 3.0.0), withr
Config/testthat/edition: 3
Encoding: UTF-8
Language: en-GB
Imports: digest, dplyr, DSMolgenisArmadillo, jsonlite, opalr (≥ 3.6.1), purrr, RcppTOML, rmarkdown, rocrateR (≥ 0.1.0), tibble, vtree, xptr, yaml
Depends: R (≥ 4.1.0)
VignetteBuilder: knitr
URL: https://github.com/FederatedMethods/dsROCrate
BugReports: https://github.com/FederatedMethods/dsROCrate/issues
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-06-01 12:17:56 UTC; robertovillegas-diaz
Author: Roberto Villegas-Diaz ORCID iD [aut, cre], Becca Wilson ORCID iD [aut], Olly Butters ORCID iD [aut], Stuart Wheater ORCID iD [aut], University of Liverpool [cph]
Maintainer: Roberto Villegas-Diaz <r.villegas-diaz@outlook.com>
Repository: CRAN
Date/Publication: 2026-06-01 12:40:08 UTC

dsROCrate: 'DataSHIELD' RO-Crate Governance Functions

Description

logo

Tools for wrapping 'DataSHIELD' analyses into RO-Crate (Research Object Crate) objects. Provides functions to create structured metadata for federated data analysis projects, enabling governance tracking of data access, project membership, analysis execution and output validation across distributed data sources.

Author(s)

Maintainer: Roberto Villegas-Diaz r.villegas-diaz@outlook.com (ORCID)

Authors:

Other contributors:

See Also

Useful links:

Login to a MOLGENIS' Armadillo server

Description

Login to a MOLGENIS' Armadillo server. Wrapper for the function DSMolgenisArmadillo::armadillo.get_credentials().

Usage

armadillo_login(server)

Arguments

server

the URL of the Armadillo server

Value

MOLGENIS' Armadillo connection object.

Create an audit RO-Crate

Description

Create an audit RO-Crate following the 5 Safes Principles.

Usage

audit(x, ...)

## S3 method for class 'ArmadilloCredentials'
audit(x, ..., intent = NULL)

## S3 method for class 'character'
audit(x, ..., intent = NULL)

## S3 method for class 'cr8tor'
audit(x, ..., intent = NULL)

## S3 method for class 'list'
audit(x, ..., intent = NULL)

## S3 method for class 'opal'
audit(
  x,
  ...,
  intent = NULL,
  project = NULL,
  user = NULL,
  logs_from = -Inf,
  logs_to = Inf,
  path = NULL
)

## S3 method for class 'rocrate'
audit(x, ..., intent = NULL)

Arguments

x

Object to be audited. This can be

  • a connection to a DataSHIELD server (e.g., OBiBa's Opal).

  • a path pointing to an RO-Crate OR a cr8tor archive / . governance bundle.

  • an RO-Crate object.

Alternatively, a list of any of the above.

...

Additional arguments.

intent

Additional object with governance bundle/specification of the intent of a project. It takes the same types as x.

project

String with project name(s) from which to extra Safe Project details.

user

String with the user name for which to extract Safe People details.

logs_from

Lower limit timestamp to filter out the outputs generated (default: -Inf, everything up to logs_to)

logs_to

Upper limit timestamp to filter out the outputs generated (default: Inf, everything from logs_from onwards).

path

String with path pointing to the root of the RO-Crate. This will be used to store log files. If not provided, logs will be stored within the RO-Crate returned by this function.

Details

This function handles various audit types, which will be dispatched based on the input object. If the input object is

Value

RO-Crate with audit details.

Check backend connection permissions

Description

Validates whether a backend connection has sufficient permissions for {dsROCrate} audit operations.

Usage

check_permissions(x, ...)

Arguments

x

A backend connection object.

...

Additional arguments passed to methods.

Details

Currently, audit or administrator permissions are required.

Value

Returns TRUE invisibly if the connection has sufficient permissions.

See Also

vignette("audit-permissions", package = "dsROCrate")

Initialise a Five Safes RO-Crate

Description

Creates a new RO-Crate configured for Five Safes auditing.

Usage

init(x, ...)

## S3 method for class 'opal'
init(
  x,
  ...,
  rocrate = rocrateR::rocrate_5s(),
  profile = "default",
  project = NULL,
  resources = NULL,
  tables = NULL,
  path = NULL,
  user = NULL
)

## S3 method for class 'rocrate'
init(
  x,
  ...,
  connection = attr(x, "connection"),
  path = attr(x, "path"),
  profile = attr(x, "profile"),
  project = attr(x, "project"),
  resources = attr(x, "resources"),
  tables = attr(x, "tables"),
  user = attr(x, "user")
)

Arguments

x

This can be a connection to a 'DataSHIELD' server (e.g., object with the opal class, see opalr::opal.login()), an RO-Crate (rocrate class) or a string with the path to an RO-Crate.

...

Other optional arguments. See the full documentation, ?dsROCrate::init.

rocrate

RO-Crate object. Optional, if x is either an RO-Crate object or a path to a valid RO-Crate. If so, then connection is required (default: rocrateR::rocrate_5s()).

profile

String with profile name (used for OBiBa's Opal backend).

project

String with the name of the Safe Project.

resources

Vector of strings with the names of the resources, part of project. Optional, if not provided, all the resources associated to project will be included in the RO-Crate.

tables

Vector of strings with the names of the tables/datasets, part of project. Optional, if not provided, all the tables/datasets associated to project will be included in the RO-Crate.

path

String with path pointing to the root of the RO-Crate. This will be used to store log files. If not provided, logs will be stored within the RO-Crate returned by this function.

user

List (or entity object) with details for the Safe People, it must include ⁠@id⁠ and name entries. Alternatively, this can be a string with the name of the current user.

connection

Connection object for the 'DataSHIELD' server where the values will be extracted from (e.g., OBiBa's Opal). Optional, if x is set to a connection object. If so, then rocrate is required.

Value

Five Safes RO-Crate object.

References

Wilkinson, M., Dumontier, M., Aalbersberg, I. et al. (2016) The FAIR Guiding Principles for scientific data management and stewardship. Sci Data 3, 160018. https://doi.org/10.1038/sdata.2016.18

Create an RO-Crate report

Description

Create an RO-Crate report

Usage

report(x, ...)

## S3 method for class 'character'
report(
  x,
  ...,
  title = "DataSHIELD Report",
  filepath = tempfile(fileext = ".md"),
  render = TRUE,
  doc_format = "html",
  overwrite = FALSE,
  include_user_perm = TRUE,
  diag_title = "DataSHIELD server",
  diag_width = NULL,
  diag_height = NULL,
  max_line_length = 200
)

## Default S3 method:
report(x, ...)

## S3 method for class 'list'
report(
  x,
  ...,
  study_name,
  title = "DataSHIELD Report",
  filepath = tempfile(fileext = ".md"),
  render = TRUE,
  doc_format = "html",
  overwrite = FALSE,
  include_user_perm = TRUE,
  diag_title = "DataSHIELD server",
  diag_width = NULL,
  diag_height = NULL,
  max_line_length = 200
)

## S3 method for class 'rocrate'
report(
  x,
  ...,
  title = "DataSHIELD Report",
  filepath = tempfile(fileext = ".md"),
  render = TRUE,
  doc_format = "html",
  overwrite = FALSE,
  include_user_perm = TRUE,
  diag_title = "DataSHIELD server",
  diag_width = NULL,
  diag_height = NULL,
  max_line_length = 200
)

Arguments

x

This can be an RO-Crate (rocrate class) or a string with the path to an RO-Crate.

...

Other optional arguments. See the full documentation, ?dsROCrate::report.

title

String with title for the report (default: 'DataSHIELD Report').

filepath

String with file path for Markdown report with the summary of the given object, x.

render

Boolean flag to indicate whether to render the markdown report.

doc_format

String with file format for the markdown report.

overwrite

Boolean flag to indicate whether to overwrite a previous version of markdown report.

include_user_perm

Boolean flag to indicate whether to include user permissions in the report overview's diagram.

diag_title

String with title for the 'root' of the diagram (default: 'DataSHIELD server').

diag_width

Numeric value with width (in inches) for the report overview's diagram (default: NULL, estimated based on number of nodes).

diag_height

Numeric value with height (in inches) for the report overview's diagram (default: NULL, estimated based on number of nodes).

max_line_length

Integer with the maximum number of characters per line in the RO-Crate to be printed in the report.

study_name

String with the study name.

Value

RO-Crate report as markdown (.md) file and/or HTML.

Safe Data details

Description

Safe Data details for the RO-Crate.

Usage

safe_data(x, ...)

## S3 method for class 'character'
safe_data(
  x,
  ...,
  profile = attr(x, "profile"),
  project = attr(x, "project"),
  resources = attr(x, "resources"),
  tables = attr(x, "tables"),
  asset_id_suffix = "#asset:",
  project_id_suffix = "#project:",
  connection = attr(x, "connection"),
  path = attr(x, "path"),
  user = attr(x, "user")
)

## S3 method for class 'opal'
safe_data(
  x,
  ...,
  rocrate = rocrateR::rocrate_5s(),
  profile = "default",
  project = NULL,
  resources = NULL,
  tables = NULL,
  include = c("tables", "resources"),
  asset_id_suffix = "#asset:",
  project_id_suffix = "#project:",
  path = NULL,
  user = NULL
)

## S3 method for class 'rocrate'
safe_data(
  x,
  ...,
  profile = attr(x, "profile"),
  project = attr(x, "project"),
  resources = attr(x, "resources"),
  tables = attr(x, "tables"),
  asset_id_suffix = "#asset:",
  project_id_suffix = "#project:",
  connection = attr(x, "connection"),
  path = attr(x, "path"),
  user = attr(x, "user")
)

Arguments

x

This can be a connection to a 'DataSHIELD' server (e.g., object with the opal class, see opalr::opal.login()), an RO-Crate (rocrate class) or a string with the path to an RO-Crate.

...

Other optional arguments. See the full documentation, ?dsROCrate::safe_data.

profile

String with profile name (used for OBiBa's Opal backend).

project

String with the name of the Safe Project.

resources

Vector of strings with the names of the resources, part of project. Optional, if not provided, all the resources associated to project will be included in the RO-Crate.

tables

Vector of strings with the names of the tables/datasets, part of project. Optional, if not provided, all the tables/datasets associated to project will be included in the RO-Crate.

asset_id_suffix

String with ID suffix for the tables/datasets entities in the RO-Crate (default: "#asset:").

project_id_suffix

String with ID suffix for the project entities in the RO-Crate (default: "#project:").

connection

Connection object for the 'DataSHIELD' server where the values will be extracted from (e.g., OBiBa's Opal). Optional, if x is set to a connection object. If so, then rocrate is required.

path

String with path pointing to the root of the RO-Crate. This will be used to store log files. If not provided, logs will be stored within the RO-Crate returned by this function.

user

List (or entity object) with details for the Safe People, it must include ⁠@id⁠ and name entries. Alternatively, this can be a string with the name of the current user.

rocrate

RO-Crate object. Optional, if x is either an RO-Crate object or a path to a valid RO-Crate. If so, then connection is required (default: rocrateR::rocrate_5s()).

include

Vector of strings with types of assets to be included, either "resources", "tables" or both.

Details

Researchers only use de-identified data that is relevant to their study.

In compliance with the Digital Economy Act, data is effectively anonymised within TREs (Trusted Research Environments).

This means any sensitive information that might lead to an individual being identified, such as names and addresses, is either removed or replaced with a random code. Researchers are not processing personal data when using data prepared in this way and when the other Safes are in place. Find out more about de-identification: https://www.researchdata.scot/engage-and-learn/data-explainers/what-is-data-de-identification/

Value

Updated RO-Crate object with Safe Data information.

Source

Safe Output details

Description

Safe Output details for the RO-Crate.

Usage

safe_output(x, ...)

## S3 method for class 'character'
safe_output(
  x,
  ...,
  path = attr(x, "path"),
  user = attr(x, "user"),
  logs_to = Sys.time(),
  logs_from = logs_to - 24 * 60^2,
  connection = attr(x, "connection"),
  profile = attr(x, "profile"),
  project = attr(x, "project"),
  resources = attr(x, "resources"),
  tables = attr(x, "tables")
)

## S3 method for class 'opal'
safe_output(
  x,
  ...,
  rocrate = rocrateR::rocrate_5s(),
  path = NULL,
  user = NULL,
  logs_to = Sys.time(),
  logs_from = logs_to - 24 * 60^2,
  profile = "default",
  project = NULL,
  resources = NULL,
  tables = NULL
)

## S3 method for class 'rocrate'
safe_output(
  x,
  ...,
  path = attr(x, "path"),
  user = attr(x, "user"),
  logs_to = Sys.time(),
  logs_from = logs_to - 24 * 60^2,
  connection = attr(x, "connection"),
  profile = attr(x, "profile"),
  project = attr(x, "project"),
  resources = attr(x, "resources"),
  tables = attr(x, "tables")
)

Arguments

x

This can be a connection to a 'DataSHIELD' server (e.g., object with the opal class, see opalr::opal.login()), an RO-Crate (rocrate class) or a string with the path to an RO-Crate.

...

Other optional arguments. See the full documentation, ?dsROCrate::safe_output.

path

String with path pointing to the root of the RO-Crate. This will be used to store log files. If not provided, logs will be stored within the RO-Crate returned by this function.

user

List (or entity object) with details for the Safe People, it must include ⁠@id⁠ and name entries. Alternatively, this can be a string with the name of the current user.

logs_to

Upper limit timestamp to filter out the outputs generated (default: Sys.time(), current system time).

logs_from

Lower limit timestamp to filter out the outputs generated (default: Sys.time() - 24 * 60 ^ 2, last 24 hours).

connection

Connection object for the 'DataSHIELD' server where the values will be extracted from (e.g., OBiBa's Opal). Optional, if x is set to a connection object. If so, then rocrate is required.

profile

String with profile name (used for OBiBa's Opal backend).

project

String with the name of the Safe Project.

resources

Vector of strings with the names of the resources, part of project. Optional, if not provided, all the resources associated to project will be included in the RO-Crate.

tables

Vector of strings with the names of the tables/datasets, part of project. Optional, if not provided, all the tables/datasets associated to project will be included in the RO-Crate.

rocrate

RO-Crate object. Optional, if x is either an RO-Crate object or a path to a valid RO-Crate. If so, then connection is required (default: rocrateR::rocrate_5s()).

Details

All research outputs are checked to ensure individuals cannot be identified even in the public domain.

This means the other four Safes no longer apply.

Before outputs are released from the TRE, they are checked to make sure it is reasonably unlikely that any individuals can be identified on publication. Compliance with the Digital Economy Act also requires that the TRE applies methods and standards for output checking that are accredited by the UK Statistics Authority.

Value

Updated RO-Crate object with Safe Outputs information.

Source

Safe People details

Description

Safe People details for the RO-Crate.

Usage

safe_people(x, ...)

## S3 method for class 'character'
safe_people(
  x,
  ...,
  user = attr(x, "user"),
  user_id_suffix = "#person:",
  set_author = TRUE,
  set_project = TRUE,
  connection = attr(x, "connection"),
  path = attr(x, "path"),
  profile = attr(x, "profile"),
  project = attr(x, "project"),
  resources = attr(x, "resources"),
  tables = attr(x, "tables")
)

## S3 method for class 'opal'
safe_people(
  x,
  ...,
  rocrate = rocrateR::rocrate_5s(),
  user = NULL,
  user_id_suffix = "#person:",
  set_author = TRUE,
  set_project = TRUE,
  path = NULL,
  profile = "default",
  project = NULL,
  resources = NULL,
  tables = NULL
)

## S3 method for class 'rocrate'
safe_people(
  x,
  ...,
  user = attr(x, "user"),
  user_id_suffix = "#person:",
  set_author = TRUE,
  set_project = TRUE,
  connection = attr(x, "connection"),
  path = attr(x, "path"),
  profile = attr(x, "profile"),
  project = attr(x, "project"),
  resources = attr(x, "resources"),
  tables = attr(x, "tables")
)

Arguments

x

This can be a connection to a 'DataSHIELD' server (e.g., object with the opal class, see opalr::opal.login()), an RO-Crate (rocrate class) or a string with the path to an RO-Crate.

...

Other optional arguments. See the full documentation, ?dsROCrate::safe_people.

user

List (or entity object) with details for the Safe People, it must include ⁠@id⁠ and name entries. Alternatively, this can be a string with the name of the current user.

user_id_suffix

String with ID suffix for the tables/datasets entities in the RO-Crate (default: "#dataset:").

set_author

Boolean flag to indicate if the current user should be set as the author of the RO-Crate.

set_project

Boolean flag to indicate if any Project entities found in x should be linked to the Safe People entity.

connection

Connection object for the 'DataSHIELD' server where the values will be extracted from (e.g., OBiBa's Opal). Optional, if x is set to a connection object. If so, then rocrate is required.

path

String with path pointing to the root of the RO-Crate. This will be used to store log files. If not provided, logs will be stored within the RO-Crate returned by this function.

profile

String with profile name (used for OBiBa's Opal backend).

project

String with the name of the Safe Project.

resources

Vector of strings with the names of the resources, part of project. Optional, if not provided, all the resources associated to project will be included in the RO-Crate.

tables

Vector of strings with the names of the tables/datasets, part of project. Optional, if not provided, all the tables/datasets associated to project will be included in the RO-Crate.

rocrate

RO-Crate object. Optional, if x is either an RO-Crate object or a path to a valid RO-Crate. If so, then connection is required (default: rocrateR::rocrate_5s()).

Details

Researchers must be accredited and trained before accessing the data that has been prepared for them.

The access service provider may require the researcher to sign a statement that they know and understand the regulations of the TRE.

Value

Updated RO-Crate object with Safe People information.

Source

Safe Project details

Description

Safe Project details for the RO-Crate.

Usage

## S4 method for signature 'armadillo'
safe_project(
  x,
  ...,
  profile = "default",
  project = NULL,
  rocrate = rocrateR::rocrate_5s(),
  asset_id_suffix = "#asset:",
  project_id_suffix = "#project:",
  path = NULL,
  resources = NULL,
  tables = NULL,
  user = NULL
)

## S3 method for class 'character'
safe_project(
  x,
  ...,
  profile = attr(x, "profile"),
  project = attr(x, "project"),
  asset_id_suffix = "#asset:",
  project_id_suffix = "#project:",
  connection = attr(x, "connection"),
  path = attr(x, "path"),
  resources = attr(x, "resources"),
  tables = attr(x, "tables"),
  user = attr(x, "user")
)

## S3 method for class 'opal'
safe_project(
  x,
  ...,
  profile = "default",
  project = NULL,
  rocrate = rocrateR::rocrate_5s(),
  asset_id_suffix = "#asset:",
  project_id_suffix = "#project:",
  path = NULL,
  resources = NULL,
  tables = NULL,
  user = NULL
)

## S3 method for class 'rocrate'
safe_project(
  x,
  ...,
  profile = attr(x, "profile"),
  project = attr(x, "project"),
  asset_id_suffix = "#asset:",
  project_id_suffix = "#project:",
  connection = attr(x, "connection"),
  path = attr(x, "path"),
  resources = attr(x, "resources"),
  tables = attr(x, "tables"),
  user = attr(x, "user")
)

## S3 method for class 'ArmadilloCredentials'
safe_project(
  x,
  ...,
  profile = "default",
  project = NULL,
  rocrate = rocrateR::rocrate_5s(),
  asset_id_suffix = "#asset:",
  project_id_suffix = "#project:",
  path = NULL,
  resources = NULL,
  tables = NULL,
  user = NULL
)

Arguments

x

This can be a connection to a 'DataSHIELD' server (e.g., object with the opal class, see opalr::opal.login()), an RO-Crate (rocrate class) or a string with the path to an RO-Crate.

...

Other optional arguments. See the full documentation, ?dsROCrate::safe_project.

profile

String with profile name (used for OBiBa's Opal backend).

project

String with the name of the Safe Project.

asset_id_suffix

String with ID suffix for the tables/datasets entities in the RO-Crate (default: "#asset:").

project_id_suffix

String with ID suffix for the project entities in the RO-Crate (default: "#project:").

connection

Connection object for the 'DataSHIELD' server where the values will be extracted from (e.g., OBiBa's Opal). Optional, if x is set to a connection object. If so, then rocrate is required.

path

String with path pointing to the root of the RO-Crate. This will be used to store log files. If not provided, logs will be stored within the RO-Crate returned by this function.

resources

Vector of strings with the names of the resources, part of project. Optional, if not provided, all the resources associated to project will be included in the RO-Crate.

tables

Vector of strings with the names of the tables/datasets, part of project. Optional, if not provided, all the tables/datasets associated to project will be included in the RO-Crate.

user

List (or entity object) with details for the Safe People, it must include ⁠@id⁠ and name entries. Alternatively, this can be a string with the name of the current user.

rocrate

RO-Crate object. Optional, if x is either an RO-Crate object or a path to a valid RO-Crate. If so, then connection is required (default: rocrateR::rocrate_5s()).

Details

Data must be used ethically, for research that delivers clear public benefit.

As part of their application, researchers are asked to provide an overview of their project, including how the data will be used and what outputs will be achieved. This allows data providers to make an informed decision about whether they are comfortable preparing data for the researcher to use for ethical purposes serving a public good.

Value

Updated RO-Crate object with Safe Project information.

Source

Safe Setting details

Description

Safe Setting details for the RO-Crate.

Usage

safe_setting(x, ...)

## S3 method for class 'character'
safe_setting(
  x,
  ...,
  connection = attr(x, "connection"),
  path = attr(x, "path"),
  profile = attr(x, "profile"),
  project = attr(x, "project"),
  tables = attr(x, "tables"),
  resources = attr(x, "resources"),
  user = attr(x, "user")
)

## S3 method for class 'cr8tor'
safe_setting(x, ..., rocrate = rocrateR::rocrate_5s())

## S3 method for class 'opal'
safe_setting(
  x,
  ...,
  rocrate = rocrateR::rocrate_5s(),
  path = NULL,
  profile = "default",
  project = NULL,
  resources = NULL,
  tables = NULL,
  user = NULL
)

## S3 method for class 'rocrate'
safe_setting(
  x,
  ...,
  connection = attr(x, "connection"),
  path = attr(x, "path"),
  profile = attr(x, "profile"),
  project = attr(x, "project"),
  resources = attr(x, "resources"),
  tables = attr(x, "tables"),
  user = attr(x, "user")
)

Arguments

x

This can be a connection to a 'DataSHIELD' server (e.g., object with the opal class, see opalr::opal.login()), an RO-Crate (rocrate class) or a string with the path to an RO-Crate.

...

Other optional arguments. See the full documentation, ?dsROCrate::safe_setting.

connection

Connection object for the 'DataSHIELD' server where the values will be extracted from (e.g., OBiBa's Opal). Optional, if x is set to a connection object. If so, then rocrate is required.

path

String with path pointing to the root of the RO-Crate. This will be used to store log files. If not provided, logs will be stored within the RO-Crate returned by this function.

profile

String with profile name (used for OBiBa's Opal backend).

project

String with the name of the Safe Project.

tables

Vector of strings with the names of the tables/datasets, part of project. Optional, if not provided, all the tables/datasets associated to project will be included in the RO-Crate.

resources

Vector of strings with the names of the resources, part of project. Optional, if not provided, all the resources associated to project will be included in the RO-Crate.

user

List (or entity object) with details for the Safe People, it must include ⁠@id⁠ and name entries. Alternatively, this can be a string with the name of the current user.

rocrate

RO-Crate object. Optional, if x is either an RO-Crate object or a path to a valid RO-Crate. If so, then connection is required (default: rocrateR::rocrate_5s()).

Details

The organisational and technical settings used to access data are designed to minimise the risk of accidental disclosure of data.

These settings also prevent the deliberate disclosure of data to others.

Physical settings for data access can include locations like SafePods – secured rooms that use controlled door access, CCTV and secure technology to ensure that sensitive data cannot be mishandled or removed from the Safe Setting. Researchers can analyse the data in these secure rooms, but do not have access to the internet, external devices (such as printers), or any other way of removing protected data from the space.

Digital Safe Settings provide secure access to data from a remote location. To be approved for remote data access, researchers will need to prove that their organisation meets physical and IT security standards.

Value

Updated RO-Crate object with Safe Settings information.

Source