Multi-site useComparable local extractionComparable local extraction only

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

The wrapper makes the local cTAKES result comparable. The study still has to define what may leave each site and supply the training, coordination, authentication, and privacy system.

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 has its own USDHUB note batch. Site B has a different batch. Each site keeps its source notes, SQLite database, XMI, logs, and clinician viewer in its approved environment. Both sites install the same wrapper release, dictionary bytes, recipe, schema, and WSD model.

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 protocol controls the next boundary.

Site ALocal notes and outputscTAKES USDHUBrun_id A

Site BLocal notes and outputscTAKES USDHUBrun_id B

Protocol approvedDerived features, aggregates, or model updates

The study defines the exact payload.

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 26/34 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.

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 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. The clinical-basics page gives the shorter orientation.

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.
`clinician_viewer.html`	Local	Full notes embedded in one portable file.
Concepts/drugs CSV	Local by default	Identifiers and original source excerpts can remain PHI.
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 26/34 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.

python3 -m json.tool /approved/usdhub/results/run_manifest.json
python3 -m json.tool /approved/usdhub/results/sanity_report.json

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.