README.md

In dsROCrate: 'DataSHIELD' RO-Crate Governance Functions

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}:

dsROCrate documentation built on Oct. 16, 2026, 5:09 p.m.