Funding acknowledgement. This work was supported by the Centers for Disease Control and Prevention grant # R01-TS000341.
Registry Forge¶
Registry Forge is the open-source pipeline described in JAMIA Open for registries whose participants share their electronic health records through SMART on FHIR. It reads C-CDA XML, FHIR R4 Bundles, RTF notes, PDFs and HTML, links every file to one participant, and produces a record viewer, OMOP CDM v5.4 tables, GA4GH Phenopackets, a code inventory, note extraction and counts-only reports. It was built and first run in the ALS Therapy Development Institute's ARC Study.
Everything needed to run it is on this site: the code, a notebook for Jupyter, Google Colab or Amazon SageMaker AI, an invented ALS cohort to practice on, and the reports that cohort produces.
Location extraction added 13 November 2026¶
The optional location extraction module finds address candidates in notes, preserves source evidence and creates a restricted queue after human review. Run it separately from run_all.py.
Run it where you work¶
Registry Forge is plain Python 3.10 or later and runs on a laptop, in Jupyter, in Google Colab, on AWS or on another approved platform. Where to run it has the full steps for each.
Approvals to confirm before using real records
Before you run real participant records, confirm that the computer or cloud service you will use is approved for them. That might be your own computer, an institutional server, a Jupyter server, Colab Enterprise, Amazon SageMaker AI or a Databricks workspace.
- Your protocol, the Institutional Review Board (IRB) determination and any data use agreement allow the records to be processed there.
- For a cloud service, your institution has a business associate agreement (BAA) with the provider that covers that specific service, not only the provider in general.
- Your information security office has approved it for identified health data.
Run the invented cohort there first to check that everything works. Use the free version of Google Colab for the invented cohort only, never for real records.
unzip RegistryForge.zip && cd RegistryForge
python -m pip install -r requirements.txt
python examples/make_synthetic_cohort.py --out practice_run
python pipeline/run_all.py --base-dir practice_run --cutoff 2026-10-31
Reports go to practice_run/reports/; open pipeline/dashboard.html and load practice_run/dashboard_data.json for the record viewer.
Unzip the package, open notebooks/run_registry_forge.ipynb in JupyterLab, Jupyter Notebook or JupyterHub, check the settings cell and run the cells in order. The notebook checks Python, packages and disk space, installs what is missing, runs everything and lists where each output went.
Download run_registry_forge.ipynb, open Google Colab, choose File, then Upload notebook, and run the cells. The notebook fetches the pipeline from this site and runs the invented cohort. Files are deleted when the Colab session ends. Real records need Colab Enterprise under the institution's Google Cloud BAA, if approved.
Run in the AWS account that already holds the exports, after confirming the AWS BAA is accepted in AWS Artifact. In SageMaker AI (JupyterLab), copy the zip from S3, unzip it and run the notebook; on EC2, run the commands under "Your computer". Read inputs from S3 with an IAM role limited to the export, and write outputs to an encrypted prefix. Step-by-step for AWS.
The Databricks export writes the chunked CSV files the pipeline reads. Run the pipeline itself wherever the institution has approved identified data: copy in the zip, install requirements.txt, run the invented cohort once, then run run_all.py or the notebook on your working directory. Notes for each platform.
The article¶
Boyce D, Premasiri A, Sullivan S, Levine B, Vieira FG. JAMIA Open. 2026;9(5):ooag200. doi:10.1093/jamiaopen/ooag200. Open access under CC BY 4.0. The software release is archived at doi:10.71944/2P5C-NG50.
The article describes a pipeline that takes the files a registry receives when participants retrieve their records through SMART on FHIR and turns them into outputs researchers can review. In the ARC Study, only a small share of the documents participants contributed were full C-CDA XML; most were HTML and RTF, which is why the pipeline reads every format and why so much of the clinical detail has to be found in text.
ALS measures such as ALSFRS-R scores, forced vital capacity, El Escorial category and genetic results are usually written in notes and reports rather than recorded as coded values. The note extraction, the cohort summary and the drug repurposing module are set up for those facts, and every candidate found in text is marked for review.
Try the live demos¶
Each demo is the output of the code on this site, run over an invented ALS cohort (Jane and John Doe shells, no real records) when the site was last built. Pick Show here to open a demo in the window below, or open it in a new tab. Every demo is a single page that loads nothing from the internet, and the summary reports hold counts only, with counts below 5 held back for cell size.
-
Record viewer
Browse invented participants or search every record and note for
ALSFRS,riluzole,BiPAPorEl Escorial. Identifiers are hidden, as they are by default with real records. -
Note extraction summary
Participants with candidates for ALSFRS-R, pulmonary function, diagnosis, family history and genes, ECAS and FTD, and treatment milestones, with every pattern and its context cues.
-
Cohort summary
Demographics, data volume, observation periods, vocabularies, ALS markers and the most frequent codes.
-
Drug repurposing report
The motor neuron disease cohort, follow-up to the data cut-off, the ALS clinical-interest medicines and landmark Kaplan-Meier medians.
-
Device summary
Speech-generating devices, wheelchairs, respiratory, feeding, transfer and bathing equipment, and equipment referrals, from codes and text.
-
Exposure summary
Military service, smoking, pesticides, heavy metals, solvents, head trauma and other exposures studied in ALS, with the ECTO term where one is recorded.
-
Phenopacket
One de-identified GA4GH Phenopacket: pseudonymous subject, ages in place of dates, a Mondo disease term, LOINC measurements and RxNorm treatments.
-
Note extraction review version
The review dashboard with masked excerpts, published here only because every participant is invented; with real records it stays in
restricted/.
What Registry Forge produces¶
The core pipeline, run_pipeline.py, runs stages 1 to 7 and writes the bundle every other module reads. run_all.py runs the core and every add-on module in order and sorts the outputs into identified files, a restricted/ folder and a counts-only reports/ folder.
| Output | What it holds | Details |
|---|---|---|
| Bundle and record viewer | One structured bundle per run, and a browser viewer with keyword search; identifiers hidden by default | Record viewer |
| Patient master CSV and code inventory | Every coded record with demographics joined on, and every vocabulary and code with counts | Patient master, Code inventory |
| Note extraction | ALSFRS-R, FVC, El Escorial, onset, family history and genes, ECAS and FTD, and dated milestones, as candidates for review | Note extraction |
| OMOP CDM v5.4 | Standard tables, every "Maps to" target kept, and a DEATH table | OMOP |
| GA4GH Phenopackets | One per participant, de-identified by default | Phenopackets |
| Counts-only reports | Cohort summary, note, device and exposure dashboards, and the drug repurposing report, with small cells held back | Cohort summary, Drug repurposing |
| Code lists | ICD-10-CM, SNOMED CT and OMOP codes for a Mondo disease and its descendants | Mondo-OMOP bridge |
What stays with your team¶
Registry Forge automates the engineering: parsing every format, normalizing code systems, harmonizing vocabularies, reassembling chunked exports, and building the OMOP, Phenopacket, device and note outputs. It does not replace the team's clinical, methodological and editorial judgment. Many registries find that the work continues after the first run: reviewing which source codes mapped to which standard concepts, deciding which participants belong in an analysis, adding disease mappings before a Phenopacket is shared, and tuning note patterns to the way their own clinicians write. The OHDSI Book of OHDSI chapter on extract, transform and load describes that work well.
Registry Forge has been built and tested on ARC Study data. It has not yet been tested on data from other organizations, EHR vendors or registries. If you would like to try it with your own data and help show how it performs elsewhere, please get in touch.
Where to start¶
-
Run the core pipeline on the single-patient sample, then everything on the invented cohort.
-
The whole pipeline in one zip, each file on its own, the run notebook, templates, sample data and the invented cohort.
-
Write the chunked CSV files the pipeline reads from your warehouse.
-
The automated tests, checks for each run, consistency across outputs and clinical review.
About, citation and contact¶
Registry Forge was developed by Danielle Boyce, MPH, DPA, of the ALS Therapy Development Institute (ALS TDI), as part of the ARC Study natural history registry. De-identified ARC data are being made available through the ARC Data Commons. Registry Forge is released under the MIT License. See About and license for acknowledgements and contact details, and Resources and related tools for related tools and training.