Overview

This book is the reproducibility companion to the paper “Federated Analysis using DataSHIELD”. It is a single, end-to-end federated analysis that you can re-run from scratch: it stands up a local three-site DataSHIELD federation over OMOP CDM data, explores what each site holds, extracts one tailored person-level table by fusing three OMOP tables on each server, describes it, and finally fits a federated logistic regression — all without a single patient-level row ever leaving a site.

Every result you see was produced by executing the code live against the three sites while this book was rendered. Nothing is pre-baked: the counts, the prevalence tables, the histograms and the GLM iteration trace are the genuine output of the run.

Why a simulated federation

In a real DataSHIELD study the data stays where it lives: each research centre hosts its own server and the patient-level records never leave the institution — that is the entire point. That real data therefore cannot be handed to you to reproduce the analysis.

So this book does the next best thing. On your own machine it simulates three research centres — aphrc, dgh and iressef — each running an independent Opal + Rock server backed by its own OMOP CDM database. The data is fully synthetic (see The dataset below) and is sharded by person across the three sites, so each “centre” holds a disjoint set of patients, exactly as three real institutions would. The analysis then runs across all three as if they were remote — the client only ever sees disclosure-checked aggregates.

Part I of this book walks you through building that federation, one step per chapter. Part II is the analysis itself.

The federation

Figure 0.1: The simulated three-site federation. One DataSHIELD client logs into three independent Opal + Rock sites (the dsOMOP omop profile); each site is backed by its own OMOP CDM PostgreSQL holding a person-disjoint shard of the GiBleed cohort.

Each site is an independent Opal + Rock stack: Opal handles authentication and the resource catalogue, while Rock is the R server that actually runs the federated computations. Our omop Rock profile bundles dsOMOP v2, the layer that turns a PostgreSQL OMOP CDM into DataSHIELD-ready tables. The one person-level table we extract is analysed in place on each server with standard dsBaseClient.

The dataset: OHDSI GiBleed

The synthetic data is the OHDSI GiBleed demonstration cohort (2 694 persons), distributed by the OHDSI community in the EunomiaDatasets repository under the Apache-2.0 licence. It is a small, fully synthetic OMOP CDM v5.3 dataset built for teaching and testing — it contains no real patients, which is precisely why we can publish and re-distribute it here for a reproducibility exercise.

Step 3 downloads a pinned copy, loads it into each site’s PostgreSQL, and shards it by person_id % 3 so each site keeps one third of the persons (and all of their records). The vocabulary tables (concept, vocabulary, …) carry no person_id and are replicated to every site so each can resolve concept names locally.

The study

From the catalogue exploration in Chapter 6 we design a clinically coherent question and answer it federally:

Is a prior history of peptic ulcer — adjusting for age, sex and NSAID exposure — associated with gastrointestinal haemorrhage?

To answer it we fuse three OMOP tables into one person-level analysis frame: person (demographics), condition_occurrence (the GI-bleed outcome and the peptic-ulcer predictor) and drug_exposure (NSAID exposure). Part II follows the natural arc of the analysis:

  1. Explore the catalogue (Chapter 6) — what tables, variables and concepts each site exposes.
  2. Extract (Chapter 7) — one server-side person-level frame built by fusing three tables, with named features.
  3. Observe (Chapter 8) — federated summaries and dsBaseClient plots of the extracted variables.
  4. Model (Chapter 9) — a federated logistic GLM, with its live training trace, plus a study-level meta-analysis.

Reproducing it yourself

Part I builds the federation in five steps that mirror the repository’s numbered folders, then opens the live connection the analysis chapters use. Each chapter shows the real commands and links the exact script that runs them:

  1. Prerequisites & easy-opal (Chapter 1) — Docker, Python and R; installing the easy-opal CLI.
  2. The three sites (Chapter 2) — declaring the aphrc, dgh, iressef Opal + Rock stacks and adding the dsOMOP omop profile.
  3. The databases (Chapter 3) — a PostgreSQL OMOP CDM per site, seeded and sharded from GiBleed.
  4. The resources (Chapter 4) — the dsOMOP resource that points each Rock session at its database.
  5. Connecting (Chapter 5) — logging the DataSHIELD client into all three sites; this live connection feeds every chapter in Part II.

If you just want the whole thing to run, the repository README has a five-command quick start; the chapters that follow explain what each command does and why.