Multi-site useComparable local extraction only

Each hospital runs the same extraction without sending its notes to the other hospital

Each hospital runs the same recorded extraction inside its own approved environment. Matching analysis_id values prove that the recipe, dictionary, schema, selected writers, and WSD model match across sites, while each execution keeps its own run_id. The wrapper stops at comparable local extraction; the study protocol still owns the feature definition, permitted outbound payload, trainer, coordination, authentication, and privacy controls.

Raw notes: Stay at each site
Extraction definition: Matched by analysis_id
Execution audit: Local run_id
Shared content: Protocol decides
Trainer: Not in this repo
Secure aggregation: Not in this repo

The same extraction runs inside each hospital

Site A holds one batch of USDHUB notes, one text file per note whose name carries that site's HubID and NoteID identifiers. Site B holds a different batch. Each site runs Apache cTAKES, a clinical text-processing system, through the USDHUB wrapper on its own notes. The source notes, the SQLite database, any XMI, logs, built-in viewer sessions, and optional browser exports stay inside that site's approved environment; SQLite is the database that lives in one file, and XMI is the XML serialization of the complete in-memory analysis, the CAS.

Both sites install exact release 2.1.19_2026AA.r1_6.0.0, the same dictionary bytes, the same recipe (the ordered list of cTAKES engines, stored as a small .piper file), and the same SQLite table layout. Normal setup downloads and verifies the main cTAKES/dictionary asset and its separate release-matched word-sense disambiguation (WSD) asset, then stages the same WSD model and SQLite JDBC jar at each site. A run at either site records the same analysis_id, the identity derived from that exact extraction definition, while each execution keeps its own run_id, the identity of one run with its UTC start time and a unique suffix. Once setup passes, extraction needs nothing from outside the site.

Site A and Site B keep notes and full-note artifacts local, use the same cTAKES USDHUB analysis identity, and release only protocol-approved features or aggregates. — Figure 1. The wrapper stops at comparable local extraction and receipt generation. The study protocol controls the next boundary.

Site ALocal notes and rowscTAKES USDHUBrun_id A

Site BLocal notes and rowscTAKES USDHUBrun_id B

Study approvedDerived features, aggregates, or model updates

Only the exact payload named by the protocol leaves a site.

The analysis identity includes the recipe, dictionary, schema, and WSD model

Two sites can both say “cTAKES 6.0.0” while using different dictionaries, recipes, wrapper code, SQLite schemas, or WSD settings. Those differences can change the candidates or fields before any federated model sees them.

Identity	Same across sites?	Reason
`release_id`	Yes	Confirms the same wrapper version, dictionary release name, and cTAKES version family.
`analysis_id`	Yes	Confirms exact wrapper source, normalized recipe, dictionary DB hash, SQLite schema, and WSD model/profile.
`run_id`	No	Each site and execution keeps its own audit identity.
Thread/heap/path	May differ	Resource settings can differ when they do not alter the extraction definition.
Output field headers	Yes	Both sites must use the same 13/16 workbook-selected delivery contract or the study features will not align.

analysis_id is the executable extraction definition. It is not a patient identifier and not a global batch ID. How it works walks all three identities on the synthetic note.

Read the identity mechanism: scripts/release_identity.py builds the release and analysis identities, while scripts/check_run.py checks the completed local result.

Federated learning trains across sites without centralizing the raw records

After each site has comparable local features, a federated trainer can send a model or training task to each site. Each site calculates an approved update from its local data. A coordinator combines those updates without collecting the underlying notes.

Concrete stone-feature example. A protocol can define one local feature called stone_CUI_positive. Site A sets it to 1 only when the agreed stone CUI (a Concept Unique Identifier, the shared concept code from the UMLS terminology system) appears in the local extraction with polarity=POS; Site B applies the same rule to its own rows. The source note, excerpt, CUI row, and patient identifier stay local. Only the specifically approved feature, aggregate, or model update may cross the site boundary. In this output contract, POS means the assertion model did not mark that mention as negated. It is not proof of a diagnosis.

That general design reduces central raw-data movement, but it does not automatically make the process private. Model updates, counts, rare features, small cohorts, and logs can still leak information. The study needs secure aggregation or another approved exchange, authentication, privacy accounting, minimum cohort rules, monitoring, named owners, and written study rules.

Four parts that are outside this wrapper

Part	Plain-language definition
Local trainer	Code that runs inside each hospital boundary, reads the approved local features, and calculates that site's model update without sending the underlying rows.
Coordinator	A service that distributes the agreed model or task, tracks eligible site rounds, combines accepted updates, and versions the resulting model.
Secure aggregation	A cryptographic exchange in which the coordinator can recover an allowed aggregate, such as a sum of updates, without reading each hospital's individual update. It still needs authentication, failure rules, and an explicit threat model.
Privacy accounting	The formal record of privacy loss across releases or training rounds when a mechanism such as differential privacy is used. It is not replaced by removing note text or by keeping the trainer local.

Step	cTAKES USDHUB supplies	Study infrastructure supplies
Local source interpretation	Same note-to-concept/medication extraction and receipts.	Approved cohort and source-note access.
Feature definition	Stable output fields and candidate evidence.	The exact modeling variables, exclusions, normalization, and missing-value rules.
Local training	Nothing beyond the local extracted data.	Training code, model, compute job, and update calculation.
Exchange	Nothing automatically leaves the output folder.	Authentication, encryption, secure aggregation or parameter exchange, and audit.
Privacy	Source notes can remain local.	Threat model, privacy accounting, suppression thresholds, and review.
Coordination	Comparable `analysis_id` and local `run_id`.	Coordinator, retry/version policy, site eligibility, and final model registry.

Review which output files still contain note text or identifiers before defining any exchange. How it works shows the same two-site boundary on the synthetic note.

Full-note and identifier-bearing artifacts stay local unless the protocol explicitly permits transfer

Artifact	Default multi-site treatment	Why
Source `.txt` notes	Local	Full clinical narrative and identifiers.
`annotations.sqlite`	Local	Full notes, identifiers, concept/medication rows, and run metadata.
XMI	Local	Full note and complete CAS.
Built-in TUI viewer session	Local	Displays full notes directly from SQLite.
`clinician_viewer.html` (optional)	Local	Full notes embedded in one portable browser file.
Concepts/drugs CSV	Local by default	The selected contract removes free-text excerpt columns but retains identifiers and clinical values that can remain PHI (protected health information).
Run receipts	Share only fields approved by protocol	Paths, HubID/NoteID, counts, failures, and hashes can expose site information.
Approved aggregate/features/update	May cross under protocol	The protocol, privacy review, and exchange system define the payload.

A site protocol should pin the extraction before the first cohort run

Record the wrapper package hash, release_id, active dictionary manifest/database hashes, WSD model/profile hash, and expected analysis_id.
Use the same strict USDHUB filename policy at every site.
Use the same recipe, default WSD state, writer profile, and 13/16 field headers.
Run a shared synthetic fixture and compare source spans, row identities, headers, and analysis ID.
Run local representative notes and complete the agreed clinical gold review without transferring raw notes outside the approved process.
Accept only batches with manifest complete and sanity pass.
Keep each site's local run_id, logs, timing, storage, and failure receipts for audit.
Define the exact outbound payload, minimum cell/cohort thresholds, encryption, destination, retention, and deletion.

Step 6 uses the same two read-back commands as every batch; they are on Getting started, accept the batch.

The repository does not contain the federated-training system

Implemented here

Local cTAKES extraction.
Strict input identity.
Versioned dictionary and WSD binding.
Canonical output and read-back validation.
Comparable analysis identity.
Local clinician review.

Still required outside this repo

Federated trainer and model code.
Coordinator and site enrollment.
Authentication and authorization.
Secure aggregation or approved exchange.
Privacy accounting and threat model.
Feature contract, monitoring, named owners, and study rules.

What the current evidence can and cannot support

Claim	Current support
Two sites can check whether they used the same extraction definition.	Supported through exact analysis identity inputs and matching field contracts.
Raw notes can remain at the source site during extraction.	Supported by local dictionary/model/JDBC runtime with no required note egress.
The wrapper itself performs federated model training.	Not implemented
Matching analysis IDs prove clinical accuracy at both sites.	Not supported They prove matching extraction inputs, not accuracy.
Extracted CSV rows are safe to centralize.	Not automatic They can contain identifiers and note excerpts.
The current WSD model is clinically validated across sites.	Not evaluated Candidate preservation and abstention are tested; clinical utility still needs gold review.

Nextthe run path from the beginningInstall, run, and check one USDHUB batch