dsROCrate: ‘DataSHIELD’ RO-Crate Governance Functions

Overview

{dsROCrate} provides tools to capture, structure and audit DataSHIELD analyses using the RO-Crate standard and the Five Safes framework. It enables reproducible governance of federated analyses by packaging inputs, outputs, metadata and audit information into a consistent, portable format, and turns the result into a human-readable report.

Installation

You can install the released version of {dsROCrate} from CRAN with:

install.packages("dsROCrate")

And the development version from GitHub with:

# install.packages("pak")
pak::pak("FederatedMethods/dsROCrate@dev")

Requirements

Backend	Status	Minimum version	Account needed
OBiBa Opal	Supported	5.7.2 (6.0 to capture `RESOLVE` operations in the outputs)	Administrator, or a user with the `Audit system` permission
MOLGENIS Armadillo	In development	–	–

Auditing reads server-wide information (users, system permissions, DataSHIELD settings and logs), so a standard analyst account is not enough. We recommend a dedicated auditor account, see vignette("audit-permissions", package = "dsROCrate").

Key Features

Create RO-Crates for DataSHIELD workflows
Capture project metadata, data references and analysis outputs
Record and audit disclosure control processes
Support reproducibility and governance in federated environments

Which function should I use?

I want to…	Use
Check my account can audit before starting	`check_permissions()`
Audit a whole project in one call (people, project, data, setting, outputs)	`audit()`
Build a crate step by step, inspecting each Safe	`init()`, then `safe_people()` … `safe_output()`
Produce a Markdown/HTML report from a crate, or from several servers	`report()`

Quick Start

The examples use OBiBa’s public demo server and its default administrator account. For real servers, use an auditor account.

# open connection
con <- opalr::opal.login(
  username = "administrator",
  password = "password",
  url = "https://opal-demo.obiba.org"
)

# check the account has sufficient permissions to audit
dsROCrate::check_permissions(con, verbose = TRUE)

Audit a project

# generate RO-Crate with Five Safes components
proj_audit <- con |>
  dsROCrate::audit(project = "CNSIM", tables = "CNSIM1", user = "dsuser")

# generate report
dsROCrate::report(proj_audit, title = "DataSHIELD Five Safes report")

If user is omitted, all non-administrator, non-auditor accounts are included. Use logs_from and logs_to to limit the period covered by the outputs, and path to store the log files next to the crate instead of inside it.

Build the crate step by step

Alternatively, it’s possible to extract only partial components from the Five Safes, by calling or skipping them as follows. init() records the connection and study details once, so the safe_*() functions need no further arguments:

proj_crate <- con |>
  # initialise RO-Crate
  dsROCrate::init(project = "CNSIM", tables = "CNSIM1", user = "dsuser") |>
  # extract Five Safes components
  dsROCrate::safe_people() |>
  dsROCrate::safe_project() |>
  dsROCrate::safe_data() |>
  dsROCrate::safe_setting() |>
  dsROCrate::safe_output()

# generate report
dsROCrate::report(proj_crate, title = "DataSHIELD Five Safes report")

Run safe_people() first, so the later steps can leave administrator and auditor accounts out of the permissions recorded for the data.

# close connection
opalr::opal.logout(con)

Several servers

audit() and report() also accept a named list of connections, e.g., for a study spanning several sites:

study_audit <- list(site_a = con_a, site_b = con_b) |>
  dsROCrate::audit(project = "CNSIM")

dsROCrate::report(study_audit, title = "DataSHIELD study audit")

Learn More

Vignette	Content
`vignette("getting-started", package = "dsROCrate")`	Connect, check permissions, audit a project and create a report
`vignette("building-crates", package = "dsROCrate")`	Build the RO-Crate one Safe at a time with `init()` and `safe_*()`
`vignette("auditing-studies", package = "dsROCrate")`	Audit and report on several servers as one study
`vignette("audit-permissions", package = "dsROCrate")`	Create an auditor account and understand the permission checks
`vignette("deploy-local-datashield-server-with-opal", package = "dsROCrate")`	Run a local Opal/DataSHIELD server with Docker for testing

Questions, bugs and feature requests: GitHub issues.

Identity

You are welcome to use any of the following logos when referencing {dsROCrate}: