| Title: | Federated Learning, Trusted Third-Party Custody, and Differential Privacy for 'DICOM' |
|---|---|
| Description: | Federated learning and trusted third-party ('TTP') custody satellite for 'dicomtk'. Provides 'Mainzelliste' REST client integration with offline fallback, polymorphic encryption and pseudonymisation ('PEP') for cross-project unlinkability, hardened Bloom-filter privacy-preserving record linkage ('PPRL') with randomized response bit-flipping and balanced padding, (epsilon, delta)-differential privacy ('DP') federated statistics with a formal privacy budget accountant and minimum-cell k-anonymity suppression, site-package exporters for 'Flower', 'NVIDIA FLARE', and 'OpenFL', and cryptographic 'site_admin' outbound approval gating. |
| Authors: | Yee How Lau [aut, cre, cph] |
| Maintainer: | Yee How Lau <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 0.1.0 |
| Built: | 2026-11-14 15:54:02 UTC |
| Source: | https://github.com/lauyeehow1986-hub/dicomtk.fl |
Aggregate Differentially Private Site Summaries Across a Federation
dp_aggregate_sites(site_summaries)dp_aggregate_sites(site_summaries)
site_summaries |
List of |
A list with n_sites, total_count, weighted_mean, and site_ids.
Tracks cumulative (epsilon, delta) privacy budget expenditure across
federated queries and aborts with dicomtk_fl_dp_budget_exceeded_error
whenever a query would exceed the configured privacy ceiling.
max_epsilonMaximum allowed cumulative epsilon.
max_deltaMaximum allowed cumulative delta.
spent_epsilonCumulative epsilon spent so far.
spent_deltaCumulative delta spent so far.
new()
Initialize a privacy budget accountant.
dp_budget_accountant$new(max_epsilon = 3, max_delta = 1e-05)
max_epsilonPositive numeric ceiling for epsilon.
max_deltaNon-negative numeric ceiling for delta.
spend()
Spend (epsilon, delta) privacy budget for a named query.
dp_budget_accountant$spend(epsilon, delta = 0, query_name = "dp_query")
epsilonPositive numeric epsilon cost.
deltaNon-negative numeric delta cost.
query_nameDescriptive label for the audit ledger.
Invisibly returns self.
remaining()
Return remaining (epsilon, delta) privacy budget.
dp_budget_accountant$remaining()
Named list with epsilon and delta.
history()
Return the privacy expenditure ledger as a tibble.
dp_budget_accountant$history()
A tibble.
clone()
The objects of this class are cloneable with this method.
dp_budget_accountant$clone(deep = FALSE)
deepWhether to make a deep clone.
Enforces minimum cohort size k_min, clips values to [lower, upper] to
bound global sensitivity, and releases noisy count, mean, and variance.
dp_federated_summary( x, lower, upper, epsilon = 1, delta = 1e-06, k_min = 10L, accountant = NULL, site_id = "SITE_1" )dp_federated_summary( x, lower, upper, epsilon = 1, delta = 1e-06, k_min = 10L, accountant = NULL, site_id = "SITE_1" )
x |
Numeric vector of local site measurements. |
lower |
Lower clipping bound. |
upper |
Upper clipping bound ( |
epsilon |
Total epsilon budget for this site summary. |
delta |
Total delta budget for Gaussian mean/variance release. |
k_min |
Minimum cohort size required before release (default |
accountant |
Optional |
site_id |
Site identifier string. |
A list of class "dicomtk_fl_site_summary".
Gaussian (epsilon, delta)-Differential Privacy Mechanism
dp_gaussian_mechanism( value, sensitivity, epsilon, delta, accountant = NULL, query_name = "gaussian_query" )dp_gaussian_mechanism( value, sensitivity, epsilon, delta, accountant = NULL, query_name = "gaussian_query" )
value |
Numeric scalar or vector true statistic. |
sensitivity |
L2 global sensitivity of |
epsilon |
Positive privacy parameter. |
delta |
Failure probability in |
accountant |
Optional |
query_name |
Audit label for |
Perturbed numeric vector.
Laplace Differential Privacy Mechanism
dp_laplace_mechanism( value, sensitivity, epsilon, accountant = NULL, query_name = "laplace_query" )dp_laplace_mechanism( value, sensitivity, epsilon, accountant = NULL, query_name = "laplace_query" )
value |
Numeric scalar or vector true statistic. |
sensitivity |
L1 global sensitivity of |
epsilon |
Positive privacy parameter. |
accountant |
Optional |
query_name |
Audit label for |
Perturbed numeric vector.
Suppress Small Contingency Cells for k-Anonymity
dp_suppress_small_cells(counts, k_min = 10L)dp_suppress_small_cells(counts, k_min = 10L)
counts |
Numeric or integer vector of cell counts. |
k_min |
Minimum non-zero cell count allowed without suppression (default |
Integer vector with 0 < count < k_min replaced by NA_integer_.
Package-level federated audit & configuration helper
fl_capabilities()fl_capabilities()
A named list describing dicomtk.fl capabilities and defaults.
fl_capabilities()fl_capabilities()
Validates a signed site_admin approval receipt against cohort_manifest,
then writes a framework-specific site configuration bundle ("flower",
"nvflare", or "openfl") to out_dir.
fl_export_site_package( cohort_manifest, out_dir, framework = c("flower", "nvflare", "openfl"), approval_gate, approval_receipt, dp_config = list(clip_norm = 1, noise_multiplier = 1.1) )fl_export_site_package( cohort_manifest, out_dir, framework = c("flower", "nvflare", "openfl"), approval_gate, approval_receipt, dp_config = list(clip_norm = 1, noise_multiplier = 1.1) )
cohort_manifest |
Named list describing the local site cohort and feature schema. |
out_dir |
Output directory path where the site bundle is written. |
framework |
Target FL framework: |
approval_gate |
A |
approval_receipt |
Signed |
dp_config |
Optional differential privacy hyperparameters ( |
Invisibly returns a list summarizing the exported bundle and written files.
Enforces that no federated learning site bundle or summary table leaves an
institution without an explicit cryptographic sign-off from an authenticated
site_admin principal, verifying minimum-cell k-anonymity and manifest
SHA-256 integrity.
k_minMinimum cell count required for outbound approval.
new()
Initialize an outbound approval gate.
fl_site_approval_gate$new(gate_secret, k_min = 10L)
gate_secretSecret HMAC-SHA256 signing key held by the site governance enclave.
k_minMinimum cell count threshold (default 10L).
manifest_digest()
Compute canonical SHA-256 digest of an outbound manifest.
fl_site_approval_gate$manifest_digest(manifest)
manifestNamed list describing the outbound cohort/model manifest.
Hexadecimal SHA-256 digest string.
approve_export()
Issue a signed site_admin approval receipt for an outbound manifest.
fl_site_approval_gate$approve_export( principal, manifest, dp_epsilon = NULL, dp_delta = 0, min_cell_count )
principalList or RBAC principal containing user_id and role.
manifestNamed list describing the outbound cohort/bundle.
dp_epsilonOptional declared DP epsilon budget.
dp_deltaOptional declared DP delta budget.
min_cell_countMinimum cell count in the outbound dataset/summary.
An object of class "dicomtk_fl_approval_receipt".
verify_receipt()
Verify a site_admin approval receipt against an outbound manifest.
fl_site_approval_gate$verify_receipt(receipt, manifest)
receiptA "dicomtk_fl_approval_receipt" object.
manifestNamed list matching the approved manifest.
TRUE if valid; otherwise aborts with dicomtk_fl_unauthorized_export_error.
revoke_receipt()
Revoke a previously issued approval receipt.
fl_site_approval_gate$revoke_receipt(receipt_id)
receipt_idCharacter scalar receipt ID.
clone()
The objects of this class are cloneable with this method.
fl_site_approval_gate$clone(deep = FALSE)
deepWhether to make a deep clone.
Computes a cryptographically unlinkable project- and site-specific
pseudonym from a root TTP master_pseudonym using keyed HMAC-SHA256
domain separation, and seals an AES-256-GCM envelope so a TTP can re-key
the pseudonym for another project without exposing the root identity.
pep_derive_site_token( master_pseudonym, project_id, site_id, pep_key, context_salt = "v1" )pep_derive_site_token( master_pseudonym, project_id, site_id, pep_key, context_salt = "v1" )
master_pseudonym |
Root TTP pseudonym (character scalar). |
project_id |
Target research project identifier. |
site_id |
Participating hospital/site identifier. |
pep_key |
Secret PEP master key. |
context_salt |
Optional protocol version/context salt (default |
An object of class "dicomtk_fl_pep_token".
tok <- pep_derive_site_token("TTP-1234", "PROJ_A", "SITE_1", "secret-key") tok$pseudonymtok <- pep_derive_site_token("TTP-1234", "PROJ_A", "SITE_1", "secret-key") tok$pseudonym
Unwraps the sealed AES-256-GCM PEP envelope at the TTP and derives a new project- and site-scoped pseudonym without returning the root identity.
pep_rekey_pseudonym( token, target_project_id, target_site_id, pep_key, context_salt = "v1" )pep_rekey_pseudonym( token, target_project_id, target_site_id, pep_key, context_salt = "v1" )
token |
A |
target_project_id |
Destination project identifier. |
target_site_id |
Destination site identifier. |
pep_key |
Secret PEP master key. |
context_salt |
Optional protocol context salt (default |
A new "dicomtk_fl_pep_token" scoped to target_project_id and target_site_id.
Compute Sorensen-Dice Similarity Between Two Bloom Filters
pprl_dice_similarity(bf1, bf2)pprl_dice_similarity(bf1, bf2)
bf1 |
A |
bf2 |
A |
Numeric scalar similarity in [0, 1].
Encodes patient quasi-identifiers into character q-grams hashed via
keyed HMAC-SHA256 double-hashing into an m-bit Bloom filter, with optional
randomized response bit-flipping (flip_prob) and constant-weight
balanced padding (balanced = TRUE) to resist frequency cryptanalysis.
pprl_encode_bloom( record, secret_key, m = 1024L, k = 15L, q = 2L, flip_prob = 0, balanced = TRUE )pprl_encode_bloom( record, secret_key, m = 1024L, k = 15L, q = 2L, flip_prob = 0, balanced = TRUE )
record |
Named list (or 1-row data.frame) of quasi-identifiers. |
secret_key |
Shared consortium HMAC-SHA256 linkage key. |
m |
Base Bloom filter length in bits (default |
k |
Number of hash functions per q-gram (default |
q |
Character q-gram width (default |
flip_prob |
Randomized response bit-flipping probability in |
balanced |
Logical; if |
An object of class "dicomtk_fl_bloom".
Privacy-Preserving Record Linkage Across Two Site Cohorts
pprl_link_cohorts( cohort_a, cohort_b, secret_key, id_col = "record_id", threshold = 0.85, m = 1024L, k = 15L, flip_prob = 0, balanced = TRUE )pprl_link_cohorts( cohort_a, cohort_b, secret_key, id_col = "record_id", threshold = 0.85, m = 1024L, k = 15L, flip_prob = 0, balanced = TRUE )
cohort_a |
Data frame with |
cohort_b |
Data frame with |
secret_key |
Shared consortium HMAC-SHA256 linkage key. |
id_col |
Name of the identifier column (default |
threshold |
Minimum Dice similarity for a match (default |
m |
Bloom filter base length (default |
k |
Number of hash functions (default |
flip_prob |
Randomized response bit-flipping probability (default |
balanced |
Use balanced constant-weight Bloom filters (default |
A tibble with id_a, id_b, and dice_similarity.
R6 client for interacting with a Mainzelliste Trusted Third-Party (TTP) pseudonymisation service, with an offline deterministic mode for air-gapped testing and simulation.
base_urlBase URL of the Mainzelliste REST service.
modeEither "offline" or "mainzelliste".
new()
Initialize a Mainzelliste TTP client.
ttp_mainzelliste_client$new(
base_url = NULL,
api_key = NULL,
mode = c("offline", "mainzelliste"),
ttp_secret = "dicomtk-fl-default-ttp-secret"
)base_urlOptional Mainzelliste REST URL.
api_keyOptional API key for Mainzelliste REST calls.
mode"offline" (default) or "mainzelliste".
ttp_secretSecret key used for deterministic offline TTP IDs.
create_session()
Create a TTP session.
ttp_mainzelliste_client$create_session()
A list with session_id, mode, and created_at.
request_pseudonym()
Request a root TTP pseudonym for patient identifying attributes.
ttp_mainzelliste_client$request_pseudonym(session_id, idat)
session_idActive session identifier from create_session().
idatNamed list of identifying attributes (e.g., vorname, nachname, geburtsdatum).
A list containing pid, temp_id, and mode.
resolve_temp_id()
Resolve an offline temporary token back to its root TTP pseudonym.
ttp_mainzelliste_client$resolve_temp_id(temp_id)
temp_idTemporary ID returned by request_pseudonym().
Character scalar root TTP pseudonym.
clone()
The objects of this class are cloneable with this method.
ttp_mainzelliste_client$clone(deep = FALSE)
deepWhether to make a deep clone.