diff --git a/website/pages/_app.jsx b/website/pages/_app.jsx index 2e1b362c..851d2f3d 100644 --- a/website/pages/_app.jsx +++ b/website/pages/_app.jsx @@ -1,3 +1,5 @@ +import "../styles/globals.css" + export default function App({ Component, pageProps }) { return -} \ No newline at end of file +} diff --git a/website/pages/_meta.js b/website/pages/_meta.js index e2ff8e6e..f3757b94 100644 --- a/website/pages/_meta.js +++ b/website/pages/_meta.js @@ -11,22 +11,15 @@ export default { } }, standards: "Standards", - federated_research_patterns: "Federated Patterns", + federated_research_patterns: "Patterns Framework", weaves: "Weaves", - implementation: { - title: "Implementations", - type: "separator" - }, - five_safes_tes: "Five Safes TES", - discovery: "Discovery", - beacon: "Beacon", - branding_sep: { title: "Branding", type: "separator" }, branding: "Branding", + "404": { title: "Page not found", display: "hidden", diff --git a/website/pages/beacon.mdx b/website/pages/beacon.mdx deleted file mode 100644 index c1d43cc2..00000000 --- a/website/pages/beacon.mdx +++ /dev/null @@ -1,20 +0,0 @@ -# Beacon - -## Core Functionality - -**Beacon** is a Weave for cohort discovery queries across a federated network of subnodes to the [GA4GH Beacon](https://www.ga4gh.org/product/beacon-api/) standard. -- Accept queries via a GA4GH Beacon v2 API. -- Federating those queries to any compatible Downstream Task API clients. -- Aggregate the returned results into a single GA4GH Beacon v2 response, which is returned to the requester. - -## Use in Federated Research - -**Beacon** is deployed in a centralised environment to form a connected network of subnodes, each typically running its own Cohort Discovery system. This architecture enables distributed datasets to be queried as though they were one, without sharing patient-level data. - -By aggregating results centrally, institutions can collaborate on large-scale research while maintaining data sovereignty and privacy. - -## Reference Implementation - -The open-source, reference implementation is **Relay**, which provides a containerised and security-conscious—enabling ethical, scalable health research through federated collaboration. - -To support data governance, Beacon applies configurable obfuscation techniques such as suppression or rounding, ensuring sensitive counts are protected. It is designed for resilience, returning aggregated results even if one or more nodes are unavailable. \ No newline at end of file diff --git a/website/pages/beacon/_meta.js b/website/pages/beacon/_meta.js deleted file mode 100644 index a56a6abc..00000000 --- a/website/pages/beacon/_meta.js +++ /dev/null @@ -1,4 +0,0 @@ -export default { - reference_implementation: 'Reference Implementation', - branding: 'Branding', -} diff --git a/website/pages/beacon/branding.mdx b/website/pages/beacon/branding.mdx deleted file mode 100644 index 979e986b..00000000 --- a/website/pages/beacon/branding.mdx +++ /dev/null @@ -1,29 +0,0 @@ -# Branding - -We love seeing Beacon being used in talks, proposals, and accreditations, so feel free to use our logos. - -You'll find a selection to use below, please use the best one that is most visible, at a size that is best legible for your use. - -All our work is covered by the MIT License. - -## Primary - -![Beacon Primary Logo](/logos/beacon/beacon_primary.png) - -## Black Transparent - -![Beacon Black Logo](/logos/beacon/beacon_secondary.png) - -## White Tranparent - -![Beacon White Logo](/logos/beacon/beacon_white.png) - -## SVG - -![Beacon Primary Logo](/logos/beacon/beacon_primary.svg) - -## Colour - -Base: #234363 - -Accent: #8CC63E \ No newline at end of file diff --git a/website/pages/beacon/reference_implementation.mdx b/website/pages/beacon/reference_implementation.mdx deleted file mode 100644 index 756fd96e..00000000 --- a/website/pages/beacon/reference_implementation.mdx +++ /dev/null @@ -1,25 +0,0 @@ -# Beacon -### Ideal Use Cases - -Relay is open-source, containerised, and security-conscious—enabling ethical, scalable health research through federated collaboration. - -- Multi-site cohort discovery for clinical trials or observational studies -- Feasibility assessments without sharing raw data -- Privacy-preserving network coordination with built-in resilience to node outages - -## Functionality -| Initiate | Input | Process | Output | -|----------|-------|---------|--------| -|Task API | | Relay | | - -[Relay](https://hutch.health/relay) is an application developed by the University of Nottingham that enables **federated cohort discovery** across health data networks. - -The code for Relay is open source, and can be found on [Github](https://github.com/Health-Informatics-UoN/hutch-relay). - -More about Relay and how to deploy it can be found in the [Relay documentation](https://hutch.health/relay). - -### Integration and Extensibility - -Relay integrates seamlessly with the Task API, allowing coordinated queries across multiple nodes. Its open-source nature means it can be extended, adapted, and embedded into existing research infrastructures to support a range of governance and interoperability needs. - - diff --git a/website/pages/discovery.mdx b/website/pages/discovery.mdx deleted file mode 100644 index adea5ca8..00000000 --- a/website/pages/discovery.mdx +++ /dev/null @@ -1,20 +0,0 @@ -# Discovery - -## Core Functionality - -**Discovery** is a Weave for cohort discovery against OMOP CDM databases. This Weave process two main types of queries: - -- **Availability**: Answers the question _“how many patients meet certain criteria?”_ without revealing individual-level data. -- **Distribution**: Returns de-identified aggregate statistics (e.g. age, sex, diagnosis counts) for a cohort of interest. - -These queries are designed to protect privacy through configurable obfuscation techniques such as rounding and low-count suppression. - -## Use in Federated Research - -**Discovery** is built to support federated research networks where each site runs its own software locally. - -This model allows institutions to collaborate on large-scale health research without sharing raw patient-level data, maintaining **data sovereignty and privacy**. - -## Reference Implementation - -Bunny is open-source, lightweight, and security-conscious, enabling scalable health research without compromising data control at the institutional level. [Bunny](https://hutch.health/bunny) is an application developed by the University of Nottingham that enables **privacy-preserving cohort discovery** across federated health data networks. It is designed to work with **OMOP Common Data Model (CDM)** databases and is deployed at partner institutions as a secure, read-only query agent. diff --git a/website/pages/discovery/_meta.js b/website/pages/discovery/_meta.js deleted file mode 100644 index a56a6abc..00000000 --- a/website/pages/discovery/_meta.js +++ /dev/null @@ -1,4 +0,0 @@ -export default { - reference_implementation: 'Reference Implementation', - branding: 'Branding', -} diff --git a/website/pages/discovery/branding.mdx b/website/pages/discovery/branding.mdx deleted file mode 100644 index a92c257b..00000000 --- a/website/pages/discovery/branding.mdx +++ /dev/null @@ -1,29 +0,0 @@ -# Branding - -We love seeing Discovery being used in talks, proposals, and accreditations, so feel free to use our logos. - -You'll find a selection to use below, please use the best one that is most visible, at a size that is best legible for your use. - -All our work is covered by the MIT License. - -## Primary - -![Discovery Primary Logo](/logos/discovery/discovery_primary.png) - -## Black Transparent - -![Discovery Black Logo](/logos/discovery/discovery_secondary.png) - -## White Transparent - -![Discovery White Logo](/logos/discovery/discovery_white.png) - -## SVG - -![Discovery Primary Logo](/logos/discovery/discovery_primary.svg) - -## Colour - -Base: #234363 - -Accent: #03A9F4 \ No newline at end of file diff --git a/website/pages/discovery/reference_implementation.mdx b/website/pages/discovery/reference_implementation.mdx deleted file mode 100644 index efb8a852..00000000 --- a/website/pages/discovery/reference_implementation.mdx +++ /dev/null @@ -1,20 +0,0 @@ -# Discovery - -## Ideal Use Cases - -Bunny is open-source, lightweight, and security-conscious, enabling scalable health research without compromising data control at the institutional level. - -- **Cohort discovery** for clinical trials or observational studies -- **Feasibility assessments** before launching multi-center research - -## Functionality -| Initiate | Process | -|----------|---------| -| RQUEST | [Bunny](https://hutch.health/bunny) | - -The code for Bunny is open source, and can be found on [Github](https://github.com/Health-Informatics-UoN/hutch-bunny). - -## Integration and Extensibility - -Bunny integrates easily with platforms like **RQUEST**, allowing coordinated Availability and Distribution querying across multiple nodes. - diff --git a/website/pages/federated_research_patterns.mdx b/website/pages/federated_research_patterns.mdx index 5fa9915a..d2443d1b 100644 --- a/website/pages/federated_research_patterns.mdx +++ b/website/pages/federated_research_patterns.mdx @@ -6,24 +6,45 @@ import { Steps,Callout } from "nextra/components" These concepts are still emerging, so get [in touch](mailto:healthinformatics@nottingham.ac.uk) if you have feedback. -There are numerous ways to undertake federated analytics and federated learning. There are also many ways to formally describe the types of analyses -that are to be performed especially via formal mathematical definitions. +There are numerous ways to undertake federated analytics and federated learning, and many tools, algorithms and platforms that implement them. Rather than describing each one, we group them by what matters to a Trusted Research Environment (TRE): what data moves from the TREs, how it is checked before it moves, and what are the interfaces for the software -We frame the domain of federated analytics and federated learning via three concepts. +We frame the domain of federated analytics and federated learning via three concepts: what is **possible**, what is **acceptable**, and what is **useful**. -## Possible -The domain focuses on what analyses are possible to be performed under different federated scenarios and therefore is a more technical representation of the various platforms and algorithms. This concept captures a rapidly developing technology ecosystem. +## Possible +This concept captures what can be done technically: the platforms that run federated analyses. -## Acceptable -Our focus of work is in the use of the possible platforms within and between trusted research environments, analysing data that is considered to be sensitive. These environments tend to be heavily controlled and locked down. This concept focuses on the areas to understand what possible federated methods are likely to be acceptable, and based on what criteria would a secure environment make those decisions. Therefore, not every federated approach that is possible is acceptable to these highly secure environments. +The [Interface](/federated_research_patterns/interface) page describes how platforms initiate a federated project, process the analysis within each TRE, and share metadata. -## Useful -The other concept is to understand the utility of the approaches for the researcher. This is to help clarify what analyses are possible when utilising a possible platform that is acceptable. Not every technology approach provides utility to researchers, but there is also a risk in adjusting the possible to make it more acceptable we lose the usefulness to the research community. +## Acceptable +Our focus is on the use of these platforms within and between TREs, analysing data that is considered sensitive. These environments are heavily controlled, so not every possible approach is acceptable to them. Whether an approach is acceptable depends in part on how results are checked before they move, which is described by the [Egress Inspection Patterns](/federated_research_patterns/egress): -## Patterns and Weaves -The aim of this work in creating patterns, is to have a neutral language that simplifies the technical and governance complexities into patterns, so that similar possible approaches can be grouped together. +| Pattern | Check at each TRE | Check at the federation | +|-|-|-| +| [Full local control](/federated_research_patterns/egress#full-local-control) | Manual | Any | +| [Semi-automated](/federated_research_patterns/egress#semi-automated) | Semi-automated, a person aided by a risk tool | Any | +| [Fully automated](/federated_research_patterns/egress#fully-automated) | Automated, with no person involved | Any | +| [Full central control](/federated_research_patterns/egress#full-central-control) | None | Manual, semi-automated or automated, as agreed by the federation | + +## Useful +This concept captures the utility of an approach for the researcher: which analyses they can carry out, and how good the results are. The analyses fall into three [Computational Patterns](/federated_research_patterns/computational), defined by what data has to move: + +| Pattern | What moves | Example analyses | +|-|-|-| +| [Traditional](/federated_research_patterns/computational/traditional) | Summary results leave each TRE for a central location. Nothing calculated from one TRE's data enters another TRE | Counts, means, contingency tables, linear regression, survival curves | +| [Shared](/federated_research_patterns/computational/shared) | Summary results, such as model parameters, leave each TRE for a central location. Derived values are sent into other TREs and used in their calculations | Iterative model fitting, such as logistic regression and federated learning | +| [Pooled](/federated_research_patterns/computational/pooled) | Row-level data about individuals leaves a TRE, persistently or temporarily | Record linkage, removing duplicate individuals, exploratory analysis | + +The same analysis can often be carried out in more than one pattern, with different trade-offs. For example, quantiles can be estimated in the Traditional Pattern, or calculated exactly in the Shared Pattern at the cost of sending results back into the TREs. -The state of the possible is captured via the [Platform](federated_research_patterns/platforms) Patterns. -The state of acceptability is captured between the [Computational](federated_research_patterns/computational) and [Egress](federated_research_patterns/egress) patterns +## Bringing them together +The useful and the acceptable are linked. Each Computational Pattern needs more trust between TREs than the last. In the Traditional Pattern, data only leaves a TRE as summary results. In the Shared Pattern, each exchange is also an ingress into other TREs, so a TRE takes in derived data about another TRE's individuals. In the Pooled Pattern, row-level data leaves the TRE. An analysis that needs many rounds of exchange in the Shared Pattern cannot practically be checked by hand at every round, so it relies on automated egress, and the Pooled Pattern relies on checks at the boundary of the federation. + +Not every technical approach provides utility to researchers, and there is also a risk that in adjusting the possible to make it more acceptable, we lose its usefulness to the research community. + +## Patterns and Weaves +The aim of creating patterns is to have a neutral language that simplifies the technical and governance complexities, so that similar approaches can be grouped together and compared. -A Weave is then used to bring together the three patterns into a single entity to help assess the usefulness of the combination of the Platform, Computational and Egress pattern. +- The state of the **possible** is captured by the [Interface](/federated_research_patterns/interface). +- The state of the **acceptable** is captured by the [Egress Inspection Patterns](/federated_research_patterns/egress): how results are checked before they move. +- The state of the **useful** is captured by the [Computational Patterns](/federated_research_patterns/computational): which analyses a researcher can carry out, and how close the results are to those from the pooled data. +- A [Weave](/weaves) brings an Interface, a Computational Pattern and an Egress Inspection Pattern together into a single entity, so that an approach can be assessed across what is possible, acceptable and useful together. diff --git a/website/pages/federated_research_patterns/_meta.js b/website/pages/federated_research_patterns/_meta.js index 939f752e..c9b91006 100644 --- a/website/pages/federated_research_patterns/_meta.js +++ b/website/pages/federated_research_patterns/_meta.js @@ -1,5 +1,5 @@ export default { computational: 'Computational Patterns', - platforms: 'Platform Patterns', - egress: 'Egress Patterns', + interface: 'Interface', + egress: 'Egress Inspection Patterns', } diff --git a/website/pages/federated_research_patterns/computational.mdx b/website/pages/federated_research_patterns/computational.mdx index 751d798a..e993912f 100644 --- a/website/pages/federated_research_patterns/computational.mdx +++ b/website/pages/federated_research_patterns/computational.mdx @@ -1,19 +1,28 @@ # Computational Patterns There are many ways to undertake federated analysis or federated learning and there are benefits and limitations of those processes. -Our work has shown that despite the significant number of federated tools, algorithms and platforms, when you examine -the patterns for how these analyses are undertaken they can be simply grouped based on two components: +Our work has shown that despite the significant number of federated tools, algorithms and platforms, when you examine the patterns for how these analyses are undertaken they can be simply grouped based on two components: -| Component | Description | -|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Analytical** | There are three key concepts that summarise the vast number of analytics and learning that are possible when data is spread across multiple TREs:

**Isolated** – these are analyses that are replicated individually within each TRE.

**Connected** – these are analyses that require multiple rounds of local calculation and aggregation, requiring the TREs to receive results from other TREs to be included in the local calculations.

**Centralised** – these analyses require data to be pooled, even temporarily, for the analyses to be performed. | -| **Data Movement** | As determined by the algorithm type, this is how data is required to move in and out of a TRE and how it is executed.

**Summary:** where a statistical result is shared back that does not relate to any individual but is a calculation based on the confidential data. It is the summary result that moves from the TRE.

**Model Parameters:** where a machine learning algorithm has been run on the data and the weights are moved from the TRE.

**Row level data**: where row level data is moving, whether or not the data is anonymised, but each data element is at the level of an individual. | +## Components +### Analytical +There are three key concepts that summarise the vast number of analytics and learning that are possible when data is spread across multiple TREs: + +- **Isolated:** The analysis is realised independently within each TRE, requiring no communication between TREs or shared state during execution. Each TRE completes its local computation in isolation, before any results to a central location to be combined or compared. This approach is suitable for analyses that can be decomposed into independent local computations followed by aggregation or comparison of summary outputs. Examples could be counts, global averages, and sums – or comparison of averages between global populations. +- **Connected:** The analysis is realised through multiple rounds of local computation interleaved with communication between TREs. Intermediate results produced by one TRE are incorporated into subsequent rounds of computation by other TREs, requiring state to be maintained throughout execution. This approach is characteristic of federated learning and other iterative distributed algorithms, such as a binary search. +- **Centralised:** The analysis is realised by bringing data from multiple TREs together before computation can be performed. This approach is required where the analysis depends on properties of the combined dataset that cannot be derived from independent local computations, such as ordering observations to calculate quantiles or rank-based statistics. + +### Data Movement +As determined by the algorithm type, this is how data is required to move in and out of a TRE and how it is executed. + +- **Summary:** Aggregated statistical outputs not corresponding to individual records are transferred between TREs or to a coordinating node. Examples include counts, sums, averages, and other derived summary statistics. The exchanged information represents characteristics of the underlying dataset rather than individual participants. +- **Intermediate Results:** Information is exchanged iteratively throughout execution rather than as a single output. The exchanged information depends on the computational approach and may include model parameters, gradients, transformed values or intermediate summary statistics. +- **Row level data:** Individual records are transferred between environments, irrespective of whether they have been anonymised. This enables analyses that require access to the combined dataset. ## Connections -The patterns we have identified to date indicate that the type of analysis to be run dictates the type of data to move. It is important to state that these classifications of the data movement do not indicate the disclosive data of a specific result. Clearly, summary results are less likely to be disclosive than row-level data; however, we are not stating any safety element to the data movement. +The patterns we have identified to date indicate that the method used to carry out an analysis dictates what data has to move, and in which direction. The same analysis can fall in more than one pattern depending on the method used (see [When an analysis becomes Shared](/federated_research_patterns/computational/traditional#when-an-analysis-becomes-shared)). These classifications of data movement do not indicate how disclosive a specific result is (see [Disclosure control](/federated_research_patterns/egress#disclosure-control)). | Analytical | Data Movement | Associated Pattern| |-|-|-| -| Isolated | Summary only | [Traditional Pattern](/federated_research_patterns/computational/traditional)| -| Connected| Model Parameters | [Shared Pattern](/federated_research_patterns/computational/shared)| -| Centralised| Row level data only | [Pooled Pattern](/federated_research_patterns/computational/pooled)| +| Isolated | Summary | [Traditional Pattern](/federated_research_patterns/computational/traditional)| +| Connected| Intermediate results | [Shared Pattern](/federated_research_patterns/computational/shared)| +| Centralised| Row level data | [Pooled Pattern](/federated_research_patterns/computational/pooled)| diff --git a/website/pages/federated_research_patterns/computational/_meta.js b/website/pages/federated_research_patterns/computational/_meta.js index 8d7839e7..122909a3 100644 --- a/website/pages/federated_research_patterns/computational/_meta.js +++ b/website/pages/federated_research_patterns/computational/_meta.js @@ -1,4 +1,5 @@ export default { + analyses: 'Analyses by Pattern', traditional: 'Traditional', shared: 'Shared', pooled: 'Pooled', diff --git a/website/pages/federated_research_patterns/computational/analyses.mdx b/website/pages/federated_research_patterns/computational/analyses.mdx new file mode 100644 index 00000000..ac4fa807 --- /dev/null +++ b/website/pages/federated_research_patterns/computational/analyses.mdx @@ -0,0 +1,95 @@ +# Analyses by Pattern + +An analysis is what the researcher wants to know, such as the median of a variable or the effect of a treatment on survival. An algorithm is how it is calculated. The same analysis can often be calculated with different algorithms, and it is the algorithm that decides which [Computational Pattern](/federated_research_patterns/computational) is used, and whether the result is the same as it would be with the data in one location. + +For example, the median can be estimated in the Traditional Pattern by merging a t-digest from each TRE, calculated exactly in the Shared Pattern by a search that sends a candidate value back into each TRE over several rounds, or calculated exactly in the Pooled Pattern by sorting the pooled data. + +The tables below list common analyses, with the algorithm that can be used for each in the Traditional and Shared Patterns: + +- **Exact:** the same result as if the data were all in one location +- **Estimated:** close to, but not the same as, the result with the data in one location +- **Same as Traditional:** the analysis can be carried out in the Shared Pattern, but it gives the same result as the Traditional Pattern, with more rounds of exchange and results sent back into the TREs + +Every analysis can be carried out exactly in the [Pooled Pattern](/federated_research_patterns/computational/pooled), using the standard methods, so the Pooled Pattern is not listed in each table. The [final table](#analyses-that-need-pooled-data) lists the analyses that need it. + +These tables are not comprehensive. More detail on what each TRE sends is given on the [Traditional](/federated_research_patterns/computational/traditional) and [Shared](/federated_research_patterns/computational/shared) pages. + +## Describing the data + +| Analysis | Traditional | Shared | +|-|-|-| +| Counts, frequencies and proportions | Counts added across TREs (exact) | Same as Traditional | +| Min/max | Min of the mins, max of the maxes (exact) | Same as Traditional | +| Mean | Totals (n, Σx) added across TREs (exact) | Same as Traditional | +| Variance, standard deviation and covariance | Totals (n, Σx, Σx², Σxy) added across TREs (exact) | Same as Traditional | +| Median and quantiles | Merged t-digests, or histograms with agreed bins (estimated) | Bisection search on a candidate value (exact) | +| Number of distinct individuals | Merged HyperLogLog sketches (estimated) | Same as Traditional | +| Standardisation (z-scores) | Each TRE standardises with its own mean and standard deviation, which is not the same as the pooled values | Pooled mean and standard deviation sent back into each TRE (exact) | + +## Statistical tests and correlation + +| Analysis | Traditional | Shared | +|-|-|-| +| Chi-squared and Fisher's exact test | Contingency tables added cell by cell (exact) | Same as Traditional | +| t-tests (one-sample, two-sample, Welch's) | n, mean and variance for each group (exact) | Same as Traditional | +| ANOVA | n, Σx and Σx² for each group (exact) | Same as Traditional | +| Hotelling's T² | n, mean vector and covariance matrix (exact) | Same as Traditional | +| Pearson's correlation | Covariance totals (exact) | Same as Traditional | + +## Regression models + +| Analysis | Traditional | Shared | +|-|-|-| +| Linear regression | Closed-form fit from XᵀX, Xᵀy and yᵀy (exact) | Same as Traditional | +| Ridge regression | Closed-form fit from XᵀX and Xᵀy (exact) | Same as Traditional | +| Logistic, Poisson and other generalised linear models | Fit on summed tables, categorical covariates only (exact), or meta-analysis (estimated) | Newton–Raphson with score and information added across TREs, any covariates (exact) | +| Generalised estimating equations (GEE) | Meta-analysis (estimated) | Estimating equations added across TREs (exact) | +| Lasso and elastic net | Meta-analysis (estimated) | Gradient methods or ADMM (exact) | +| Linear mixed models, site-level random effects | Closed-form fit from totals (exact) | Same as Traditional | +| Linear mixed models, random effects below site level | Meta-analysis (estimated) | Likelihood added across TREs (exact) | +| Principal component analysis (PCA) | Pooled covariance matrix from totals (exact) | Same as Traditional | + +## Survival analysis + +| Analysis | Traditional | Shared | +|-|-|-| +| Survival curves and log-rank test | Kaplan–Meier or Nelson–Aalen from numbers at risk and events on an agreed time grid (exact) | Same as Traditional | +| Cox regression | Piecewise-exponential model (estimated), or meta-analysis (estimated) | Newton–Raphson, stratified by site (exact) | +| Parametric survival models (Weibull, accelerated failure time) | Meta-analysis (estimated) | Score and information added across TREs (exact) | +| Poisson and piecewise-exponential models, categorical covariates | Fit on summed tables (exact) | Same as Traditional | + +## Clustering and machine learning + +| Analysis | Traditional | Shared | +|-|-|-| +| Clustering | k-means at each TRE, with the local clusters merged centrally (estimated) | k-means with per-cluster sums and counts added each round (exact) | +| Mixture models | None listed | EM algorithm with per-component totals added each round (exact) | +| Neural networks | Trained at each TRE and compared | Federated averaging (estimated) | +| Gradient-boosted trees | Trained at each TRE and compared | Federated XGBoost with binned gradient totals (estimated) | +| Random forests | Trained at each TRE and compared | Merged local trees, or binned split summaries (estimated) | + +Any model in the Shared Pattern can be trained with differential privacy, which adds random noise to each update to protect individuals. This makes the result an estimate, even where the algorithm would otherwise be exact. + +## Comparing locations + +Comparing results between locations is often the aim in its own right, and is where the Traditional Pattern is strongest: any analysis that can run within a TRE can be run in full at each one. + +| Analysis | Traditional | Shared | +|-|-|-| +| Describe each population | Summary tables from each TRE, compared side by side | Same as Traditional | +| Test for differences between locations | Estimates and standard errors from each TRE, tested centrally, including heterogeneity (Cochran's Q, I²) | A model with a location term, fitted across TREs | +| Replicate a finding | The same analysis run in full at each TRE | Same as Traditional | +| Validate a model agreed in advance | Performance measures (such as AUC and calibration) from each TRE, compared | Same as Traditional | +| Check data quality and coding | Completeness, coding frequencies and ranges from each TRE, compared | Same as Traditional | + +## Analyses that need pooled data + +These analyses depend on having individuals' records together, so they need the Pooled Pattern. + +| Analysis | Why it needs pooled data | +|-|-| +| Linking records across TREs | Brings together data held about the same individuals in different TREs | +| Removing duplicate individuals | Individuals present in more than one TRE are otherwise counted more than once. The Traditional Pattern can only estimate how many distinct individuals there are | +| Different variables held for the same individuals | The Traditional and Shared Patterns assume each TRE holds the same variables for different individuals | +| Cox regression, not stratified by site | The risk sets span TREs, so the model cannot be broken into parts each TRE calculates | +| Exploratory analysis | The method is not known in advance, so cannot be broken into results each TRE calculates | diff --git a/website/pages/federated_research_patterns/computational/pooled.mdx b/website/pages/federated_research_patterns/computational/pooled.mdx index 15ce6b8a..1bbb5009 100644 --- a/website/pages/federated_research_patterns/computational/pooled.mdx +++ b/website/pages/federated_research_patterns/computational/pooled.mdx @@ -1,12 +1,37 @@ +# Pooled Pattern +**[Analytical](/federated_research_patterns/computational#analytical):** Centralised +**[Data Movement](/federated_research_patterns/computational#data-movement):** Row level data -# Pooled Pattern -**Analytical:** Centralised -**Data Movement**: Row level data - -The pattern captures the movement of data where row level data moves, either persistently or temporarily to perform an analysis. Outside of TREs this is the most common method, where researchers would be accustomed to data being on their data where they can perform any analysis or learning. +The defining feature of the Pooled Pattern is that row-level data leaves a TRE, whether persistently or temporarily, and whether or not it has been anonymised or pseudonymised. Outside of TREs this is the most common method, where researchers would be accustomed to having the data in one place where they can perform any analysis or learning. This approach requires a very high level of trust between TREs as it requires sharing of row-level data between TREs. Disclosure control can still be applied before the data leaves the TRE network. It is however by far the most powerful for a user as the analyses and learning are almost unlimited. -![Alt Text](/assets/gif/Dynamics.gif) + +![Animated diagram of the Pooled pattern: a temporary front-door connection forming between TREs to share row-level data](/assets/gif/Dynamics.gif) + +## Analyses + +Because the analysis runs on the pooled data, every result is exact by definition and requires no approximation, as may be required in the [Traditional](/federated_research_patterns/computational/traditional) and [Shared](/federated_research_patterns/computational/shared) Patterns. + +Most statistics and models can be calculated without pooling, using one of the other two patterns. The Pooled Pattern is needed when an analysis depends on having individuals' records together: + +| Analysis | Why it needs pooled data | +|-|-| +| Linking records across TREs | Bringing together data held about the same individuals in different TREs, where each TRE holds different information about them | +| Removing duplicate individuals | Individuals present in more than one TRE are otherwise counted more than once | +| Different variables held for the same individuals | The Traditional and Shared Patterns assume each TRE holds the same variables for different individuals | +| Analyses with no decomposable form | For example, unstratified Cox regression, or methods that need the full dataset at once | +| Exploratory analysis and data quality checks | Where the method is not known in advance, so cannot be broken down into results each TRE calculates | + +### What counts as Pooled + +Some approaches move row-level data without it appearing in readable form. These are still the Pooled Pattern, because data about each individual leaves the TRE: + +- **Privacy-preserving record linkage:** sending hashed or encoded identifiers for each individual is row-level data moving. This differs from a sketch of hashed identifiers, such as the HyperLogLog sketch in the [Traditional Pattern](/federated_research_patterns/computational/traditional), which summarises the identifiers rather than listing them. +- **Secure multi-party computation and trusted execution environments:** row-level data moves, but in encrypted form, so no party sees another TRE's records. These are Pooled, but with a lower trust requirement than pooling readable data. + +## Trust and egress + +This pattern is most likely associated with the [Full central control](/federated_research_patterns/egress#full-central-control) Egress Inspection Pattern: data that would not normally be allowed to leave a TRE moves within the federation, and the normal egress check is performed before results leave the boundary of the federation of TREs. ## Variance in implementation -An emerging implementation of the Pooled Pattern is from the DARE UK TREvolution programme. They are exploring a project-specific network being created between the TREs, to either move or provide the researcher with a view of the data that makes it appear as if the data is all in one location. +An emerging implementation of the Pooled Pattern is from the DARE UK TREvolution programme. They are exploring a project-specific network being created between the TREs, to either move or provide the researcher with a view of the data that makes it appear as if the data is all in one location. diff --git a/website/pages/federated_research_patterns/computational/shared.mdx b/website/pages/federated_research_patterns/computational/shared.mdx index 60094c9a..3979e1bd 100644 --- a/website/pages/federated_research_patterns/computational/shared.mdx +++ b/website/pages/federated_research_patterns/computational/shared.mdx @@ -1,6 +1,61 @@ # Shared Pattern -**Analytical:** Connected -**Data Movement**: Model Parameters +**[Analytical](/federated_research_patterns/computational#analytical):** Connected +**[Data Movement](/federated_research_patterns/computational#data-movement):** Model Parameters -The most common method to undertake federated learning is for the model parameters to be passed via a central node, or directly between the TREs. The key difference for a TRE is that results are combined and shared between other TREs, therefore there is a higher trust required between the TREs, as they must trust the sharing of model parameters with the researcher and the TREs. -![Alt Text](/assets/gif/Connected%20Analytics.gif) +The defining feature of the Shared Pattern is that results calculated from one TRE's data are sent into another TRE and used in its calculations. This is the case whether results are passed via a central node or directly between the TREs: when a central node combines results and sends updated parameters back, each TRE receives information derived from the other TREs' data. + +The most common method to undertake federated learning is for the model parameters to be passed via a central node, though it is also possible to share directly between TREs. +The key difference between this and the [traditional pattern](traditional) for a TRE is that results are combined and shared with other TREs. There is a higher level of trust required between the TREs as they must trust the sharing of some information, not only with the researcher, but also other TREs. +![Animated diagram of the Shared pattern: model parameters passing between a central location and two connected TREs](/assets/gif/Connected%20Analytics.gif) + +## Trust and egress + +Each exchange is both an egress from one TRE and an ingress into the others. Model parameters can carry information about the individuals they were fitted on, so a TRE receiving them is taking in derived data about another TRE's individuals, and its governance has to accept that. + +Most analyses in this pattern are iterative. A logistic regression might need 5–10 rounds, and training a neural network can take thousands. Checking every round by hand is impractical, so this pattern usually relies on the semi-automated or fully automated [Egress Inspection Patterns](/federated_research_patterns/egress). Comparing updates across rounds can also reveal more about individuals than any single update, which is why techniques such as differential privacy and secure aggregation are often used. + +## Analyses + +In a typical analysis, the central location sends the current estimate to each TRE, each TRE returns an update calculated on its own data, and the cycle repeats until the estimate stops changing. These tables are not comprehensive, and only encompass some common analyses that can be achieved by the shared pattern. + +### Exact + +These analyses converge to the same result as if the data were all in one location. + +| Analysis | What each TRE sends each round | Why the combined result is exact | +|-|-|-| +| Logistic, Poisson and other generalised linear models (any covariates) | Score vector and information matrix at the current coefficients | These add across TREs to give the pooled Newton–Raphson step, so the model converges to the pooled fit | +| Generalised estimating equations (GEE) | Estimating equation contributions and their derivatives at the current estimates | The equations add across TREs, provided each cluster sits within one TRE | +| Cox regression, stratified by site | Score and information from its own risk sets at the current coefficients | The stratified partial likelihood is a sum over sites, so the summed updates converge to the pooled stratified fit | +| Parametric survival models (Weibull, accelerated failure time) | Score and information at the current parameters | The log-likelihood is a sum across TREs | +| Linear mixed models with random effects below the site level (e.g. groups or organisations within a TRE) | Likelihood contributions at the current parameters | The likelihood is a sum across TREs, provided each cluster sits within one TRE | +| Exact quantiles (e.g median) | Count of values below the current candidate value | Bisection narrows the candidate until it lands on the exact pooled value | +| Lasso and elastic net regression | Gradient contributions, or local solutions under ADMM (an algorithm for splitting a model fit across sites) | Converges to the pooled penalised fit | +| k-means clustering | Per-cluster sums and counts for the current centres | Each round reproduces a pooled k-means step, so the result matches pooled k-means given the same starting centres | +| Gaussian mixture models (EM algorithm) | Per-component weighted sums and counts | Each EM step adds across TREs, so the result matches the pooled fit given the same starting values | +| Standardisation (z-scores) | One round sharing mean and variance to pool, one round to send results after standardisation | Mean, variance, and standardised results can be calculated exactly | + +### Estimated + +These analyses give results close to, but not the same as, those from the data in one location. + +| Analysis | What each TRE sends each round | Why the combined result is an estimate | +|-|-|-| +| Neural networks via federated averaging (FedAvg) | Model weights after several steps of local training | Averaging locally trained models differs from training on the pooled data, especially when the TREs' data differ | +| Gradient-boosted trees (e.g. federated XGBoost) | Binned gradient totals for candidate splits | Splits are chosen from bins built from merged summaries, so they can differ slightly from those found on pooled data | +| Random forests | Locally built trees, or binned split summaries | The combined forest approximates one trained on pooled data | +| Any model trained with differential privacy | Updates with added random noise | The noise protects individuals but moves the result away from the pooled fit | + +### Overlap with the Traditional Pattern + +Several of these analyses can also be carried out in the [Traditional Pattern](/federated_research_patterns/computational/traditional), where nothing is sent back into a TRE. The trade-off is fewer exchanges and simpler egress in the Traditional Pattern, against exact results for a wider range of models in the Shared Pattern. + +| Analysis | In the Traditional Pattern | What the Shared Pattern adds | +|-|-|-| +| Generalised linear models | Exact with categorical covariates only, otherwise each TRE's results are combined in a meta-analysis | An exact fit with continuous covariates | +| Cox regression | Estimated via piecewise-exponential models, or by combining each TRE's results in a meta-analysis | An exact fit when stratified by site | +| Quantiles and median | Estimated via t-digest or histograms | Exact values | +| Mixed models | Exact with site-level random effects | Random effects below the site level | +| k-means clustering | Estimated by merging local clusters | An exact match to pooled k-means | + +An analysis that looks like it belongs in the Traditional Pattern also becomes Shared if a pooled value is sent back into the TREs, for example a pooled mean used to standardise data locally. See [When an analysis becomes Shared](/federated_research_patterns/computational/traditional#when-an-analysis-becomes-shared). diff --git a/website/pages/federated_research_patterns/computational/traditional.mdx b/website/pages/federated_research_patterns/computational/traditional.mdx index 9e95324a..b2036712 100644 --- a/website/pages/federated_research_patterns/computational/traditional.mdx +++ b/website/pages/federated_research_patterns/computational/traditional.mdx @@ -1,31 +1,85 @@ # Traditional Pattern -**Analytical:** Isolated -**Data Movement**: Summary +**[Analytical](/federated_research_patterns/computational#analytical):** Isolated +**[Data Movement](/federated_research_patterns/computational#data-movement):** Summary -The most common method of federated analytics carries out a local computation in each location separately to generate summary results which are combined centrally. This pattern requires the lowest trust between TREs, as each result is undertaken independently. +The most common method of federated analytics carries out a local computation in each location separately to generate summary results. This pattern requires the lowest trust between TREs, as each analysis is undertaken independently and no TRE receives results from another. One limitation of this approach is that data cannot be linked, as no row-level attributes are shared. -One limitation of this approach is that data cannot be linked, as no row-level attributes are shared. Certain analyses cannot be undertaken via this method. Though this is the most traditional approach, it is the least powerful of the three patterns for a researcher. +In the simplest case, a researcher carrying out this kind of analysis wants to calculate a separate result of the analysis for each location. In this case, any analysis that can be run within the boundary of the TRE, constrained only by the compute and permissions from the TRE, is possible. The results can then be compared side by side, tested for differences between locations, or combined in a meta-analysis (see [Compared](#compared)). -The analyses that can be run within the boundary of the TRE are almost unlimited and constrained only by the compute and permissions from the TRE. Egress can be applied which will limit the results that can analysed together. +In other cases, a researcher wishes to estimate a result across locations, combining local results. For example, they could carry out a meta-analysis, calculating a summary of the data in each location so they can use statistical methods to estimate some overall result from each location's summary. +For a more limited set of results, discussed below, it is possible to use a Traditional pattern to calculate the result as if the data were in a single, pooled dataset. -![Alt Text](/assets/gif/Isolated%20Analytics.gif) +The analyses that can be run within the boundary of the TRE are almost unlimited and constrained only by the compute and permissions from the TRE. Egress can be applied which will limit the results that can be analysed together. + +![Animated diagram of the Traditional pattern: each TRE running analysis independently and returning summary results to a central location](/assets/gif/Isolated%20Analytics.gif) ## Analyses -An algorithm to calculate a statistic is *isolated* if the algorithm can be broken into subproblems that can be calculated separately at each TRE. These results can be combined, compared, analysed in the middle based on the data that has been allowed out from the egress process. - -In some scenarios, it is desirable to achieve the same result when the data is federated as calculating them on a single, pooled data set, but not all analytics can be performed in this way. This table is not comprehensive, and only encompasses some common analyses that can be achieved by the traditional pattern that would perform the same as if the data were all in one location. - -| Statistic | Notes | -| -------------------------------------- | ------------------------------------------------------------------------------------ | -| Minimum/maximum | | -| Counts | Includes prevalence, incidence | -| Contingency tables | Includes comorbidity. Can be used for Chi-squared test, Fisher's exact test, etc. | -| Mean | | -| Variance | Can be used to calculate standard deviation | -| Covariance | | -| Product-moment correlation coefficient | Also known as Pearson's correlation coefficient. Can be used to calculate Fisher's Z | -| t-tests | Including one-sample and two-sample t-tests | -| Hotelling's T2 | | -| ANOVA | | -| t-digest | Used to estimate quartiles (median, interquartile ranges, etc.) | -| Linear regression | | +In the Traditional Pattern each analysis is *isolated*: it is carried out separately within each TRE, and the results are combined, compared or analysed centrally, based on what has been allowed out through the egress process. Some analyses can be broken into parts whose results combine to give the same answer as the pooled data. Others are run in full at each TRE, and the results are compared centrally. + +In that sense the analyses whose results can be compared between TREs are almost endless and are only constrained by what the TRE is likely to allow to leave. +Combining these results in a meta-analysis relies on having an applicable statistical approach. + +The analyses below assume each TRE sends its results in a single pass, using settings (such as time grids, histogram bins or starting values) agreed before the analysis starts. If anything calculated from one TRE's data is sent into another TRE, the analysis becomes [Shared](/federated_research_patterns/computational/shared) (see [When an analysis becomes Shared](#when-an-analysis-becomes-shared)). + +These tables are not comprehensive, and describe common analyses that can be achieved with the traditional pattern. + +#### Compared + +Any analysis that can run within a TRE can be run in full at each TRE, with the results returned for each location. This includes models that cannot be combined exactly, such as Cox regression, logistic regression with continuous covariates, mixed models and machine learning models. Differences between locations are often a finding in their own right. + +| Aim | What each TRE sends | How the results are used | +|-|-|-| +| Describe each population | Summary tables, such as counts, rates, prevalence, means and distributions | Compared side by side, for example a table of characteristics with a column per location | +| Test for differences between locations | Estimates with their standard errors, or the totals behind them (such as n, mean and variance) | Tested centrally, for example comparing rates or means between locations, or measuring heterogeneity (Cochran's Q, I²) | +| Meta-analysis | An effect estimate and its standard error from the same model at each TRE | Combined into an overall estimate using fixed or random effects, and shown in a forest plot. The overall estimate is close to, but not the same as, fitting the model on the pooled data | +| Replication | The full results of the same analysis at each TRE | Checked for whether a finding at one location holds at the others | +| Validating a model agreed in advance | Performance measures, such as discrimination (AUC) and calibration | Compared across locations, for example to see whether a published risk score performs equally well in each population. A model fitted on another TRE's data in the same project makes this the [Shared Pattern](/federated_research_patterns/computational/shared) | +| Data quality and coding | Completeness, coding frequencies and data ranges | Compared to find where variables are recorded or coded differently, before results are combined | + +#### Exact + +These analyses give the same result as if the data were all in one location. + +| Statistic | What each TRE sends | Why the combined result is exact | +|-|-|-| +| Min/max | Its own min/max | The min of the mins is the overall min | +| Counts | Its counts | Counts simply add up. Includes frequencies and proportions | +| Contingency tables (chi-squared, Fisher's exact test) | Its cell counts | The tables add cell by cell, then the test runs on the summed table | +| Mean | n, Σx | Overall mean = ΣΣx / Σn | +| Variance and covariance | n, Σx, Σx², Σxy (or n, mean and sum of squared deviations) | The pooled variance is **not** the average of each TRE's variance, so these totals must be sent | +| Pearson's correlation and Fisher's z | The same totals as covariance | Built from the exact variances and covariance | +| t-tests (one-sample, two-sample, Welch's) | n, mean and variance for each group | Built from exact values | +| Hotelling's T² | n, mean vector and covariance matrix | The multivariate version of the same ideas as a t-test | +| ANOVA | n, Σx and Σx² for each group | One-way is exact. Multi-way ANOVA is a linear model, so it's exact the same way regression is | +| Linear regression (OLS) | XᵀX, Xᵀy, yᵀy, n | The coefficients, residual sum of squares and standard errors all come from these, in one round | +| Survival curves and log-rank test (Kaplan–Meier, Nelson–Aalen) | Number at risk and number of events at each event time, per group | These add across TREs at each time point, so the pooled curve and test follow exactly. All TREs must use the same time grid. If event times are grouped (e.g. by week or month) to reduce disclosure risk, the result is exact for the grouped times | +| Logistic and other generalised linear models (categorical covariates) | Event and non-event counts for each covariate combination | The tables add, and the model is fitted centrally on the summed table, giving the same fit as the pooled data. With continuous covariates, an exact fit needs the [Shared Pattern](/federated_research_patterns/computational/shared), or each TRE's results can be combined in a meta-analysis | +| Ridge regression | XᵀX, Xᵀy, n | Ridge has a closed-form solution, (XᵀX + λI)⁻¹Xᵀy, built from the same totals as linear regression | +| Linear mixed models with site-level random effects | XᵀX, Xᵀy, yᵀy, Σy, column sums of X and n | Each TRE's totals are enough to fit the model centrally. Random effects below the site level (e.g. groups or organisations within a TRE) need the [Shared Pattern](/federated_research_patterns/computational/shared) | +| Principal component analysis (PCA) | n, Σx and the cross-product matrix Σxxᵀ | The pooled covariance matrix is exact, and the principal components are calculated from it centrally | +| Poisson and piecewise-exponential survival models (categorical covariates) | Event counts and person-time for each time interval and covariate combination | The tables add, and the model is fitted centrally on the summed table, giving the same fit as the pooled data | + +#### Estimated + +Some statistics cannot be rebuilt exactly from simple totals sent once by each TRE, but can be estimated closely. The combined result is an approximation of what would be obtained if the data were all in one location, and may differ slightly from it. + +| Exact Statistic | Approximation | What each TRE sends | Why the combined result is an estimate | +|-|-|-|--| +| Quantiles (median, quartiles, IQR, percentiles) | t-digest | A t-digest: a compact summary of the distribution as weighted centroids | Digests merge into one approximate digest. Accuracy is highest near the extremes (e.g. 1st or 99th percentile) and lower near the median. Exact quantiles need several rounds of communication (the [Shared Pattern](/federated_research_patterns/computational/shared)) | +| Quantiles | Histograms | Counts in agreed bins | The binned counts add exactly, but quantiles can only be located within a bin, so precision depends on the bin width | +| Distinct counts | HyperLogLog | A HyperLogLog sketch of hashed identifiers | Sketches merge to estimate the number of distinct individuals across TREs, allowing for people present in more than one TRE. Typical error is around 1–2% | +| Cox regression | Piecewise-exponential models | Event counts and person-time for each fine time interval and covariate combination | A piecewise-exponential model with fine time intervals closely approximates the Cox model. An exact Cox model needs repeated exchanges between TREs (the [Shared Pattern](/federated_research_patterns/computational/shared)), or each TRE's results can be combined in a meta-analysis | +| k-means clustering | Merged local clusters | Cluster centres and sizes from clustering run locally | The local centres are combined centrally. The result is usually close to, but not the same as, k-means on the pooled data | + + +### When an analysis becomes Shared + +What separates this pattern from the [Shared Pattern](/federated_research_patterns/computational/shared) is not the analysis itself, but whether anything calculated from one TRE's data enters another TRE. In the Traditional Pattern, results flow out of each TRE to the central location and stop there; the only thing going into a TRE is the analysis code and the settings agreed in advance. The same analysis can fall in either pattern depending on how it is carried out. + +| Analysis | Stays Traditional if… | Becomes Shared if… | +|-|-|-| +| Variance and standard deviation | Each TRE sends n, Σx and Σx² in one pass | The pooled mean is sent back so TREs can compute deviations from it | +| Kaplan–Meier and the time grid | The time grid is fixed in advance | The grid is derived from pooled event times and sent back | +| Histograms | The bins are agreed in advance | The bins are set from pooled data, such as pooled quantiles | +| k-means clustering | Each TRE clusters independently | Merged centres are sent back for refinement | +| Standardisation (z-scores) | Each TRE sends totals only | The pooled mean and standard deviation are sent back to standardise locally | diff --git a/website/pages/federated_research_patterns/egress.mdx b/website/pages/federated_research_patterns/egress.mdx index 9c989120..813fba3f 100644 --- a/website/pages/federated_research_patterns/egress.mdx +++ b/website/pages/federated_research_patterns/egress.mdx @@ -1,7 +1,7 @@ -# Data Egress Patterns +# Egress Inspection Patterns Within a federated project there is always an interaction that occurs at each location, and then at the central level where results are either combined, compared or analysed. Therefore, whilst in a more traditional setup not involving federation, the only area where egress would be considered is at the boundary of each TRE, within a federated model, there are two options for egress to occur. -The first is at the boundary of the individual TRE where data is held and being made available to the federated project. The purpose of the egress check is to ensure only the data that has been approved to move is indeed what is moving. In most TREs this check is to ensure the data leaving does not contain anything disclosive and is safe to leave the secure boundary of the TRE.We have identified four methods in which egress can occur. +The first is at the boundary of the individual TRE where data is held and being made available to the federated project. The purpose of the egress check is to ensure only the data that has been approved to move is indeed what is moving. In most TREs this check is to ensure the data leaving does not contain anything disclosive and is safe to leave the secure boundary of the TRE. We have identified four methods in which egress can occur. | Method | Description | @@ -17,7 +17,7 @@ The first is at the boundary of the individual TRE where data is held and being Local egress method: Manual Central egress method: Any -This egress pattern is most likely affiliated with the [Traditional Federation Pattern](/federated_research_patterns/computational/traditional), as it mirrors the current process as much as possible. All data to move out from the boundary of the individual TRE has a manual disclosure control check, regardless of whether any disclosure control is performed on the federated network. +This Egress Inspection Pattern is most likely affiliated with the [Traditional Federation Pattern](/federated_research_patterns/computational/traditional), as the considerations are similar to the case without federation. All data to move out from the boundary of the individual TRE has a manual disclosure control check, regardless of whether any disclosure control is performed on the federated network. ## Semi-automated Local egress method: Semi-automated @@ -33,6 +33,14 @@ There are federated platforms and tools that will automate the checks and ensure ### Full central control Local egress method: None -Central egress method: Any +Central egress method: Manual, semi-automated or automated, as agreed by the federation There are certain analyses that can only be performed when all the data is in a single location. Therefore, data pooling must occur, and data that normally would not be allowed via egress does indeed move. The key concept of this pattern, is that the data is moving to another TRE/SDE and that before the results leave the boundary of the federation of TREs, the normal egress check is performed. At this stage, it could be any of the disclosure control components that are used, but would be agreed upon by the federation of TREs/SDEs. + +## Disclosure control + +Disclosure control is the process of checking that results leaving a TRE cannot be used to identify individuals or reveal information about them. This framework does not treat disclosure risk as a pattern. The Egress Inspection Patterns describe the method of inspection: who or what checks the results, and at which boundary. They do not describe how risky those results are. + +No [Computational Pattern](/federated_research_patterns/computational) is inherently safer from a disclosure control perspective. A summary result in the Traditional Pattern can be disclosive, for example a count of a small group or a table with small cells. Model parameters in the Shared Pattern can reveal information about the individuals they were fitted on. Row-level data in the Pooled Pattern can still be inspected and protected before results leave the federation. The risk depends on the specific result and its context, such as the size of the groups involved and what has already been released, not on the pattern used to produce it. + +This is why the same Computational Pattern can be combined with different Egress Inspection Patterns in a [Weave](/weaves), and why the method of disclosure control needs to be agreed with each TRE whichever pattern is used. diff --git a/website/pages/federated_research_patterns/interface.mdx b/website/pages/federated_research_patterns/interface.mdx new file mode 100644 index 00000000..4c7907a3 --- /dev/null +++ b/website/pages/federated_research_patterns/interface.mdx @@ -0,0 +1,33 @@ +# Interface +There are many [federated platforms](#current-platforms) that could be used by the researcher to perform their federated analytics or federated learning projects. + +Whilst there may be only a few types of federation, the various platforms tend to differ in how they implement them. + +The purpose of this page is to understand how things move in a federated project: how an analysis is submitted to the network, how each TRE is asked to process it, and how metadata is shared. Interfaces here are the technical connection points between systems, usually APIs, rather than user interfaces. + +Linking to each platform's API specification allows it to be assessed for how that movement happens, for example: +- whether work is pushed into a TRE, which requires the TRE to accept inbound connections, or pulled by an agent inside the TRE that only makes outbound connections +- whether the parties connect directly, or through a central service or broker +- what specifically is sent at each stage, such as analysis code, model parameters or results, and in what form +- where results could be inspected before they leave a TRE + +## Initiate +A federated analysis or federated learning project usually will start with some commands to initiate the project. At this +stage we are collecting information from platform providers to understand if they are using an API specification that captures how a federated project is initiated. + +Therefore, at this stage, we will list the API specification for the receiving of the analysis to run across the network. + +## Process +Each TRE will be asked to process some local job, and that local processing can equally be initiated by an API. We have separated out the API specification that initiates +a federated project and the API specification that is used to initiate a local processing in case these are different. + +Therefore, at this stage, we will list the API specification for API that is to request the processing of the analysis within a TRE. + +## Metadata +Many federated systems rely on the sharing of metadata in order to make the platform usable, to help researchers to design their studies, and to discover what data is available across the network. At this stage we are seeking to understand how common the metadata is between the various platforms, as this could aid egress and TRE onboarding if we can standardise. + +## Current Platforms +| Platform Name | Initiate | Process | Metadata | +|-|-|-|-| +| Aridhia DRE | [Aridhia API docs](https://aridhia-open-source.github.io/PHEMS_federated_node/) | [Aridhia API docs](https://aridhia-open-source.github.io/PHEMS_federated_node/) | | +| Five Safes TES | [Five Safes TES docs](https://docs.federated-analytics.ac.uk/explanations/concepts/tes) | [GA4GH TES API specification](https://ga4gh.github.io/task-execution-schemas/docs/) | | diff --git a/website/pages/federated_research_patterns/platforms.mdx b/website/pages/federated_research_patterns/platforms.mdx deleted file mode 100644 index cf7c5058..00000000 --- a/website/pages/federated_research_patterns/platforms.mdx +++ /dev/null @@ -1,28 +0,0 @@ -# Platform Patterns -There are many [federated platforms](#current-platforms) that could be used by the researcher to perform their federated analytics or federated learning projects. - -Whilst there may be only a few types of federation, the various platforms tend to differ in how they implement them. - -## Initiate -A federated analysis or federated learning project usually will start with some commands to initiate the project. At this -stage we are collecting information from platform providers to understand if they are using an API specification that captures how a federated project is initiated. - -Therefore, at this stage, we will list the API specification for the receiving of the analysis to run across the network. - -## Process -Each TRE will be asked to process some local job, and that local processing can equally be initiated by an API. We have seperated out the API specification that initiates -a federated project and the API specification that is used to initiate a local processing incase these are different. - -Therefore, at this stage, we will list the API specification for API that is to request the processing of the analysis with a TRE. - -## Metadata -Many federated systems rely on the sharing of metadata in order to make the platform usable, to help reseasrchers to design their studies, and to discover what data is available across the network. At this stage we are seeking to understand how common the metadata is between the various platforms, as this could aid egress and TRE onboarding if we can standardise. - -## Current Platform Patterns -| Platform Name | Initiate | Process | Metadata | -|-|-|-|-| -| Aridhia DRE | [Aridhia API docs](https://aridhia-open-source.github.io/PHEMS_federated_node/) | [Aridhia API docs](https://aridhia-open-source.github.io/PHEMS_federated_node/) | | -| Apheris | [Apheris API docs](https://www.apheris.com/docs/gateway/latest/general/custom-models.html) | NA| | -| Bitfount | [Bitfound API docs](https://docs.bitfount.com/guides/for-data-scientists/writing-tasks/task-components) | [Bitfound API docs](https://docs.bitfount.com/guides/for-data-scientists/writing-tasks/task-components) | | -| Five Safes TES | [Five Safes TES](/submission/guides/teswizard) |[TES Documentation](https://www.ga4gh.org/product/task-execution-service-tes/) | | -| Vantage6 | [Vantage 6 API docs](https://github.com/vantage6/vantage6/blob/main/vantage6-server/vantage6/server/resource/task.py) | NA | | diff --git a/website/pages/five_safes_tes.mdx b/website/pages/five_safes_tes.mdx deleted file mode 100644 index 746ccf12..00000000 --- a/website/pages/five_safes_tes.mdx +++ /dev/null @@ -1,42 +0,0 @@ -# Five Safes TES - -## Core Functionality - -**Five Safes TES** implements the HDR UK Federation Weave for the secure, remote execution of [GA4GH TES analyses](/standards#global-alliance-for-genomics-and-health-ga4gh) in Trusted Research Environments (TREs). - -- TRE managers can register environments, create projects, and manage authorised access. -- Researchers can submit GA4GH TES analyses for secure execution within participating TREs. - -Built on international [open standards](/standards) from GA4GH and ELIXIR, **Five Safes TES** uses an enhanced GA4GH Task Execution Service -to receive federated analysis requests. This approach supports the essential disclosure control processes within TREs, ensuring outputs are reviewed -to prevent disclosive data from leaving secure environments. - -## Use in Federated Research - -Five Safes TES enables secure cross-TRE federated analytics, where the data remains in place and only the researchers’ -analysis code is sent to the data. It is specifically designed to meet the stringent technical and governance constraints -of TREs by separating the logical stages of a federated project. - -## Five Safes TES Analysis Capability - -Five Safes TES supports isolated algorithms only. - -An algorithm to calculate a statistic is *isolated* if the algorithm can be broken into subproblems that can be calculated separately at each TRE. These results can be combined to achieve the same result as calculating them on a single, pooled data set. - -There are often several different algorithms that can be used to calculate the same statistic, but it is the algorithm, not the statistic which is of importance in determining how it can be federated. In considering several common statistics and algorithms in health informatics, we have produced a table which shows statistics that are known to be calculable in a federated manner using Five Safes TES. Note that this summary gives no regard to disclosure risks or checking of outputs, only the suitability of Five Safes TES for an implementation. This table is not comprehensive, and only encompasses some common analyses in health informatics. - -| Statistic | Possible in Five Safes TES | Notes | -| -------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------ | -| Minimum/maximum | ✅ | | -| Counts | ✅ | Includes prevalence, incidence | -| Contingency tables | ✅ | Includes comorbidity. Can be used for Chi-squared test, Fisher's exact test, etc. | -| Mean | ✅ | | -| Variance | ✅ | Can be used to calculate standard deviation | -| Covariance | ✅ | | -| Product-moment correlation coefficient | ✅ | Also known as Pearson's correlation coefficient. Can be used to calculate Fisher's Z | -| t-tests | ✅ | Including one-sample and two-sample t-tests | -| Hotelling's T2 | ✅ | | -| ANOVA | ✅ | | -| t-digest | ✅ | Used to estimate quartiles (median, interquartile ranges, etc.) | -| Linear regression | ✅ | | - diff --git a/website/pages/five_safes_tes/_meta.js b/website/pages/five_safes_tes/_meta.js deleted file mode 100644 index ee82d8cc..00000000 --- a/website/pages/five_safes_tes/_meta.js +++ /dev/null @@ -1,4 +0,0 @@ -export default { - reference_implementation: "Reference Implementation", - branding: "Branding", -}; diff --git a/website/pages/five_safes_tes/branding.mdx b/website/pages/five_safes_tes/branding.mdx deleted file mode 100644 index 3c7f07b9..00000000 --- a/website/pages/five_safes_tes/branding.mdx +++ /dev/null @@ -1,29 +0,0 @@ -# Branding - -We love seeing Five Safes TES being used in talks, proposals, and accreditations, so feel free to use our logos. - -You'll find a selection to use below, please use the best one that is most visible, at a size that is best legible for your use. - -All our work is covered by the MIT License. - -## Primary - -![Five Safes TES Primary Logo](/logos/five-safes-tes/five_safes_tes_primary.png) - -## Black Transparent - -![Five Safes TES Secondary Logo](/logos/five-safes-tes/five_safes_tes_secondary.png) - -## White Transparent - -![Five Safes TES White Logo](/logos/five-safes-tes/five_safes_tes_white.png) - -## SVG - -![Five Safes TES Primary Logo](/logos/five-safes-tes/five_safes_tes_primary.svg) - -## Colour - -Base: #234363 - -Accent: #F1BD44 \ No newline at end of file diff --git a/website/pages/five_safes_tes/reference_implementation.mdx b/website/pages/five_safes_tes/reference_implementation.mdx deleted file mode 100644 index 66fe9bd6..00000000 --- a/website/pages/five_safes_tes/reference_implementation.mdx +++ /dev/null @@ -1,8 +0,0 @@ -import { Steps, Callout } from "nextra/components"; - -# Five Safes TES - - - Documentation for the Five Safes TES Reference Implementation has been moved - to the [new site](https://docs.federated-analytics.ac.uk/). - diff --git a/website/pages/index.mdx b/website/pages/index.mdx index 264ba1d9..43c54e84 100644 --- a/website/pages/index.mdx +++ b/website/pages/index.mdx @@ -12,7 +12,7 @@ Trusted Research Environments (TREs) are secure locations in which data are safe - cater to a variety of system implementations, and - operate using standards to facilitate safe access and use of data. -Federation in research is an approach to mitigate the challenges inherent when conducting research on sensitive and disparate data. This approach emphasises data always remaining with the collecting organisation. Here, code written by the researchers is sent to the data. In this system, all data analysis takes place within highly secure computer systems called TREs. A researcher writes their computer code, and this is then sent to each TRE, analysing only the data kept in that one TRE. The results from each TRE are then returned to the researcher and combined. There is a spectrum of federation in research: +Federation in research is an approach to mitigate the challenges inherent when conducting research on sensitive and disparate data. This approach emphasises data remaining with the collecting organisation. Here, code written by the researchers is sent to the data, and analysis takes place within highly secure computer systems called TREs. In its simplest form, a researcher writes their computer code, and this is then sent to each TRE, analysing only the data kept in that one TRE. The results from each TRE are then returned to the researcher and combined. Other approaches exchange results between TREs, or bring data together temporarily; these are described in the [Patterns Framework](/federated_research_patterns). There is a spectrum of federation in research: - **Discovery** enables researchers to discover datasets across various data sources. - **Analytics** enables researchers to perform analysis on data from disparate data sources. - **Learning** enables researchers to use machine learning methods across different datasets. @@ -29,7 +29,7 @@ Federated Research is driven to transform how researchers securely access and an - Involvement with leading organisations to design and develop suitable research data infrastructure. - Collaborate with the public to promote transparency, garner acceptance and ensure operation within social licence -#### Enable [Federation](/federated_research_patterns/patterns) +#### Enable [Federation](/federated_research_patterns) - Federation is more than software or any specific platform. It's many, working together to form an ecosystem - Beyond technical possibilities, there are elements of trust, autonomy, and governance to inform what is acceptable and useful - There is no one-size-fits-all model of federation. How these networks are deployed is determined by trust, data maturity, technical infrastructure, and resources diff --git a/website/pages/standards.mdx b/website/pages/standards.mdx index fbb66643..d2ef6028 100644 --- a/website/pages/standards.mdx +++ b/website/pages/standards.mdx @@ -1,6 +1,6 @@ # What standards are we adopting? -These standards have been selected based on relevance and prevalence to the research data infrastruture domain. Included below is a brief description of what these standards are and why they have been adopted. +These standards have been selected based on relevance and prevalence to the research data infrastructure domain. Included below is a brief description of what these standards are and why they have been adopted. ## Five Safes - A set of principles to describe how decisions about granting access to data should be made. Covering Safe People, Data, Project, Outputs, Settings it is a set of interlocking principles @@ -39,30 +39,6 @@ The Federated Analytics programme in HDR UK and the TREvolution programme in DAR [Read more about TES](https://www.ga4gh.org/product/task-execution-service-tes/) -## Research Object Crate (RO-Crate) - -- A collaborative approach to use Web standards for packaging data with structured metadata -- Rich support for describing provenance (e.g. attribution, workflow executions) -- Support FAIR principles with programmatic consumption/generation of metadata and content -- Platform-independent and Archivable for long-term storage -- Extensible with domain-specific metadata profiles -- Used and supported by a large range of international research projects, open source tools and data repositories - -We are using (and further developing) RO-Crate in HDR UK and DARE UK to achieve: -- Transparency of internal TRE processes (e.g. evidence of disclosure control) -- Records of TRE use as part of Information Governance, e.g. to populate data usage registry or aggregate into a TRE dashboard -- Reproducibility of computational analysis, if captured as an embedded workflow -- Interoperability across disparate existing systems, in particular as a common format between different TRE implementations - -In particular, we have developed the [Five Safes RO-Crate](https://w3id.org/5s-crate/) profile as a FAIR approach to document and support Five Safes principles, initially in the context of computational workflows. We are working further, in collaboration with our FAIR engagement work, to expand this profile to evidence any computational execution and data extract, as well as a new profile (TRE Crate) to document TRE datasets (e.g. linking to OMOP specifications of variables, and populating the [HDR Gateway](https://healthdatagateway.org/)). - -Related publications: -- [The Five Safes RO-Crate](https://doi.org/10.52825/ocp.v5i.1419) -- [Recording provenance of workflow runs with RO-Crate](https://doi.org/10.1371/journal.pone.0309210) -- [Packaging research artefacts with RO-Crate](https://doi.org/10.3233/DS-210053) - -[Read more about RO-Crate](https://www.researchobject.org/ro-crate/). - ## Observational Medical Outcomes Partnership (OMOP) - A standard that describes how health data should be grouped together in a set of common tables (a common data model) - Created and maintained by Observational Health Data Sciences and Informatics (OHDSI) diff --git a/website/pages/weaves.mdx b/website/pages/weaves.mdx index 29c69e27..c1c103b7 100644 --- a/website/pages/weaves.mdx +++ b/website/pages/weaves.mdx @@ -1,15 +1,15 @@ # Weaves -A **Weave** is a combination of a platform and computational pattern, which are linked by what disclosure control is allowed for that Weave. +A **Weave** brings together an [Interface](/federated_research_patterns/interface), a [Computational Pattern](/federated_research_patterns/computational) and an [Egress Inspection Pattern](/federated_research_patterns/egress) into a single entity. Each on its own describes one aspect of a federated approach: the Interface captures what is **possible**, the Egress Inspection Pattern captures what is **acceptable**, through how results are checked before they move, and the Computational Pattern captures what is **useful**, through which analyses a researcher can carry out. A Weave combines them so that an approach can be assessed across all three aspects together, rather than one at a time. ## Creating a Weave -A Weave must contain a single [Platform Pattern](/federated_research_patterns/platforms) and a single [Computational Pattern](/federated_research_patterns/computational). A single platform may have multiple Weaves if it implements more than a single Computational Pattern. +A Weave must contain a single Interface, a single Computational Pattern and a single Egress Inspection Pattern. A single platform may have multiple Weaves if it implements more than one Computational Pattern, or supports more than one Egress Inspection Pattern. ### Current Weaves -| Weave Name | Computational Pattern | Platform Pattern | Egress Pattern | +| Weave Name | Computational Pattern | Interface | Egress Inspection Pattern | |-|-|-|-| -|HDR UK Federation | Traditional Pattern | Five Safes TES | Manual | -|HDR UK Cohort Discovery| Traditional Pattern | Bunny | Automated | +|Sovereign | Traditional Pattern | Five Safes TES | [Full local control](/federated_research_patterns/egress#full-local-control) | +|Discovery | Traditional Pattern | Bunny | [Fully automated](/federated_research_patterns/egress#fully-automated) | |Aridhia - DC Off| Traditional Pattern | Aridhia DRE | Off | -|Aridhia - DC Manual| Traditional Pattern | Aridhia DRE | Manual | +|Aridhia - DC Manual| Traditional Pattern | Aridhia DRE | [Full local control](/federated_research_patterns/egress#full-local-control) | diff --git a/website/pages/weaves/beacon.mdx b/website/pages/weaves/beacon.mdx new file mode 100644 index 00000000..95f5d812 --- /dev/null +++ b/website/pages/weaves/beacon.mdx @@ -0,0 +1,78 @@ +# HDR UK Beacon + +## Core Functionality + +**Beacon** is a Weave for cohort discovery queries across a federated network of subnodes to the [GA4GH Beacon](https://www.ga4gh.org/product/beacon-api/) standard. +- Accept queries via a GA4GH Beacon v2 API. +- Federating those queries to any compatible Downstream Task API clients. +- Aggregate the returned results into a single GA4GH Beacon v2 response, which is returned to the requester. + +## Use in Federated Research + +**Beacon** is deployed in a centralised environment to form a connected network of subnodes, each typically running its own Cohort Discovery system. This architecture enables distributed datasets to be queried as though they were one, without sharing patient-level data. + +By aggregating results centrally, institutions can collaborate on large-scale research while maintaining data sovereignty and privacy. + +## Reference Implementation + +The open-source, reference implementation is **Relay**, which provides a containerised environment designed with security in mind, enabling ethical, scalable health research through federated collaboration. + +To support data governance, Beacon applies configurable obfuscation techniques such as suppression or rounding, ensuring sensitive counts are protected. It is designed for resilience, returning aggregated results even if one or more nodes are unavailable. + +## Weave details + +### Patterns +| Component | Used in this Weave | +|-|-| +| Interface | [GA4GH Beacon v2 API](https://www.ga4gh.org/product/beacon-api/), via Relay | +| Computational Pattern | [Traditional Pattern](/federated_research_patterns/computational/traditional) | +| Egress Inspection Pattern | [Fully automated](/federated_research_patterns/egress#fully-automated): suppression or rounding is applied to counts before they are returned | + +### What a researcher can do +- Send a single query to many subnodes, and receive one aggregated answer. +- Find out whether, and how many, individuals across the network match a set of criteria. +- Use any client that supports the GA4GH Beacon v2 standard. + +### Effect on results +Results are estimates, not exact counts, for the same reasons as in the [Discovery Weave](/weaves/discovery#effect-on-results): rounded counts do not add up to the true total, and suppressed counts are missing. In addition, if one or more subnodes are unavailable, the aggregated result is returned without them, so a total can be lower than the true value. + +### What it can't do +- Run the researcher's own code, or any analysis beyond the queries supported by the Beacon v2 standard. +- Link records or remove duplicates across subnodes, so individuals present in more than one subnode may be counted more than once. + +### Practical constraints +- Results are returned without waiting for a manual check. +- Each subnode must run a compatible cohort discovery system. +- Relay is deployed centrally, so the federation needs to agree who operates it. + +{/* To confirm with the Beacon team: whether obfuscation is applied at each subnode, centrally by Relay, or both (if only centrally, unobfuscated counts leave each subnode and the Egress Inspection Pattern may differ); and whether responses indicate which subnodes were unavailable. */} + +# Branding + +We love seeing Beacon being used in talks, proposals, and accreditations, so feel free to use our logos. + +You'll find a selection to use below, please use the best one that is most visible, at a size that is best legible for your use. + +All our work is covered by the MIT License. + +## Primary + +![Beacon Primary Logo](/logos/beacon/beacon_primary.png) + +## Black Transparent + +![Beacon Black Logo](/logos/beacon/beacon_secondary.png) + +## White Transparent + +![Beacon White Logo](/logos/beacon/beacon_white.png) + +## SVG + +![Beacon Primary Logo](/logos/beacon/beacon_primary.svg) + +## Colour + +Base: #234363 + +Accent: #8CC63E \ No newline at end of file diff --git a/website/pages/weaves/discovery.mdx b/website/pages/weaves/discovery.mdx new file mode 100644 index 00000000..22567b2d --- /dev/null +++ b/website/pages/weaves/discovery.mdx @@ -0,0 +1,78 @@ +# HDR UK Discovery + +## Core Functionality + +**Discovery** is a Weave for cohort discovery against OMOP CDM databases. This Weave processes two main types of queries: + +- **Availability**: Answers the question _“how many patients meet certain criteria?”_ without revealing individual-level data. +- **Distribution**: Returns de-identified aggregate statistics (e.g. age, sex, diagnosis counts) for a cohort of interest. + +These queries are designed to protect privacy through configurable obfuscation techniques such as rounding and low-count suppression. + +## Use in Federated Research + +**Discovery** is built to support federated research networks where each site runs its own software locally. + +This model allows institutions to collaborate on large-scale health research without sharing raw patient-level data, maintaining **data sovereignty and privacy**. + +## Reference Implementation + +Bunny is open-source, lightweight, and security-conscious, enabling scalable health research without compromising data control at the institutional level. [Bunny](https://hutch.health/bunny) is an application developed by the University of Nottingham that enables **privacy-preserving cohort discovery** across federated health data networks. It is designed to work with **OMOP Common Data Model (CDM)** databases and is deployed at partner institutions as a secure, read-only query agent. + +## Weave details + +### Patterns +| Component | Used in this Weave | +|-|-| +| Interface | Bunny, a query agent deployed at each site | +| Computational Pattern | [Traditional Pattern](/federated_research_patterns/computational/traditional) | +| Egress Inspection Pattern | [Fully automated](/federated_research_patterns/egress#fully-automated): rounding and low-count suppression are applied at each site before results leave | + +### What a researcher can do +- Count the individuals meeting a set of criteria at each site, and across the network. +- Get aggregate distributions (such as age and sex) for a cohort of interest. + +This is mainly useful for assessing whether a study is feasible, and which sites hold suitable data, before applying for access. + +### Effect on results +Results are estimates, not exact counts. Rounded counts from several sites do not add up to the true total, and suppressed counts are missing, so a small cohort can appear as zero. The precision can also differ between sites, as the rounding and suppression settings are configured at each site. + +### What it can't do +- Run the researcher's own code, or any analysis beyond the defined query types, such as statistical tests or modelling. +- Link records or remove duplicates across sites, so individuals present at more than one site may be counted more than once. + +### Practical constraints +- Results are returned without waiting for a manual check. +- Each site must run Bunny against data in the OMOP Common Data Model, so query criteria are limited to what is captured in OMOP. + +{/* To confirm with the Discovery team: where rounding/suppression is applied (each site, centrally or both), and default settings. */} + +# Branding + +We love seeing Discovery being used in talks, proposals, and accreditations, so feel free to use our logos. + +You'll find a selection to use below, please use the best one that is most visible, at a size that is best legible for your use. + +All our work is covered by the MIT License. + +## Primary + +![Discovery Primary Logo](/logos/discovery/discovery_primary.png) + +## Black Transparent + +![Discovery Black Logo](/logos/discovery/discovery_secondary.png) + +## White Transparent + +![Discovery White Logo](/logos/discovery/discovery_white.png) + +## SVG + +![Discovery Primary Logo](/logos/discovery/discovery_primary.svg) + +## Colour + +Base: #234363 + +Accent: #03A9F4 \ No newline at end of file diff --git a/website/pages/weaves/sovereign.mdx b/website/pages/weaves/sovereign.mdx new file mode 100644 index 00000000..25f2813f --- /dev/null +++ b/website/pages/weaves/sovereign.mdx @@ -0,0 +1,40 @@ +# Sovereign + +## Core Functionality + +The Sovereign Weave represents the secure, remote execution of [GA4GH TES analyses](/standards#task-execution-service-tes) within Trusted Research Environments (TREs). + +The functionality represented in the Weave is the closest to current day activity of TREs and offers the maximum control and isolation, +requiring no TRE-TRE connectivity. + +Built on international [open standards](/standards) from GA4GH, it uses an enhanced GA4GH Task Execution Service +to receive federated analysis requests. This approach supports the essential disclosure control processes within TREs, ensuring outputs are reviewed +to prevent disclosive data from leaving secure environments. + +## Weave details + +### Patterns +| Component | Used in this Weave | +|-|-| +| Interface | [Five Safes TES](/federated_research_patterns/interface#current-platforms), via the [Five Safes TES](https://docs.federated-analytics.ac.uk) open source software stack | +| Computational Pattern | [Traditional Pattern](/federated_research_patterns/computational/traditional) | +| Egress Inspection Pattern | [Full local control](/federated_research_patterns/egress#full-local-control): all results are checked and authorised at each TRE before being released | + +### What a researcher can do +The researcher submits their own analysis code as a TES task, which is run at each TRE. This supports any [analysis in the Traditional Pattern](/federated_research_patterns/computational/traditional#analyses), where each TRE's results are: + +- **compared:** any analysis that can run within a TRE gives a separate result for each location, and these can be compared centrally +- **combined exactly:** results such as counts, means, contingency tables and linear regression combine to give the [same result as the pooled data](/federated_research_patterns/computational/traditional#exact) +- **combined as an estimate:** results such as quantiles, distinct counts and Cox regression give a [close estimate](/federated_research_patterns/computational/traditional#estimated) of the pooled result, or each TRE's results are combined statistically, as in a meta-analysis + +### Effect on results +Exact analyses stay exact, provided the egress check releases each TRE's results unchanged. If the check rounds or suppresses results, for example small cells in a table, the totals no longer combine exactly, and a TRE whose results are withheld drops out of the analysis. + +### What it can't do +- **Shared Pattern analyses.** Each round of an iterative analysis would need a manual check at every TRE, so iterative model fitting is not practical. Analyses that need a single pass, such as piecewise-exponential models in place of Cox regression, or combining each TRE's results as in a meta-analysis, can often be used instead (see [When an analysis becomes Shared](/federated_research_patterns/computational/traditional#when-an-analysis-becomes-shared)). +- **Pooled Pattern analyses.** Row-level data does not leave the TRE, so records cannot be linked across TREs, and individuals present in more than one TRE may be counted more than once. + +### Practical constraints +- Each result waits for a person to check it at every TRE, so turnaround is set by the slowest review. +- Settings such as time grids, histogram bins and output formats need to be agreed in advance, so that each TRE produces results that can be combined and checked. +- The same analysis code runs at every TRE, so variables need to be defined in the same way at each one. diff --git a/website/styles/globals.css b/website/styles/globals.css new file mode 100644 index 00000000..9ef97c9c --- /dev/null +++ b/website/styles/globals.css @@ -0,0 +1,14 @@ +/* Give tables a consistent width and column layout so columns line up + from one table to the next as you scroll down a page. Small screens + keep Nextra's default horizontal scrolling. */ +@media (min-width: 768px) { + .nextra-content table { + display: table; + width: 100%; + table-layout: fixed; + } + + .nextra-content table th:first-child { + width: 25%; + } +}