clinosim

Clinically Realistic Hospital Data Simulator — generate FHIR R4 EHR data from a virtual hospital.

Developed at InterSystems · Not an official InterSystems product (details)

📚 Documentation site | 🇯🇵 README.ja.md

⚠️ Synthetic data only — fully synthetic output. Not for clinical use. clinosim does not ingest, reference, or reproduce any real patient data / PHI / PII.

What is clinosim?

clinosim generates synthetic EHR data through forward simulation from a population. Every patient carries a hidden 14-variable physiological state (clinosim/types/clinical.py::PhysiologicalState), and every observation (labs, vitals, medications, diagnoses) is derived from that state — so the data is clinically coherent by construction.

Primary use cases:

• Training data for medical AI / ML models
• EHR system testing and QA
• Clinical-research method development
• Educational case datasets

Install

Requires Python 3.11 or newer.

pip install clinosim

Development install from a clone:

git clone https://github.com/TomoOkuyama/clinosim.git
cd clinosim
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Quick start

Generate a small US cohort and inspect its FHIR output:

clinosim simulate --country US --population 100 --seed 42 \
  --output ./out --format fhir-r4
ls ./out/fhir_r4/          # Patient.ndjson, Encounter.ndjson, ...

For the JP cohort, named-preset datasets, hospital-config override, and the full CLI reference, see docs/getting-started/configuration.md.

See it in action

For a JP warfarin-anticoagulated patient, clinosim's physiology engine places the patient in the therapeutic PT-INR band and emits a lab value (e.g. 2.7) inside that range — not by sampling a "PT-INR normal range", but because the hidden state chose it. Remove the warfarin and next run's INR drops back to ~1.0.

Full JSON walkthrough → docs/getting-started/first-cohort.md

Why clinosim?

Most synthetic-EHR tools produce records by sampling from disease distributions. clinosim runs the disease — the CKD patient's ED creatinine is elevated even when presenting for something unrelated; the sepsis patient shows the WBC / CRP / lactate cascade.

• Clinical coherence by construction — physiology model makes incoherent labs impossible.
• JP + US natively — JP Core profile compliance for 16 primary FHIR resource types, JLAC10 / MHLW YJ codes, JP names / addresses / insurance out of the box.
• YAML-driven extension — 32 inpatient diseases + 46 ED / outpatient conditions are all data files, not code.
• Longitudinal service lines — oncology (10 cancer sites incl. male breast, chemo regimen cycles, radiation therapy Procedure, tumor-marker labs) + obstetrics (pregnancy modelled as a time-boxed TemporalStatePeriod lifecycle — annual conception, prenatal visits at gestational weeks 12/24/36, mother-side delivery Encounter with Z37.0 discharge dx + delivery Procedure + newborn Patient chain, postpartum visits at 7 d / 28 d) emit at correct temporal cadence, not as flat annotations. See docs/reference/oncology-obstetric-service-lines.md.

Prior-art comparison (Synthea): docs/synthea-comparison.md.

Learn more

Community

• Code of Conduct — CODE_OF_CONDUCT.md (Contributor Covenant 2.1)
• Security policy — SECURITY.md (private disclosure via GitHub Security Advisories)
• Starter tasks — good first issue label
• Issue templates — .github/ISSUE_TEMPLATE/ (structured bug / feature forms)
• Citation — GitHub "Cite this repository" button (backed by CITATION.cff)

Affiliation

clinosim is developed by an engineer at InterSystems and released under the MIT License as an open-source contribution to the healthcare AI developer community.

It is not an official InterSystems product. It is not part of InterSystems IRIS for Health or any other commercial offering, and it carries no InterSystems support, warranty, or roadmap commitment. Issues and pull requests are handled here on GitHub, not through InterSystems support channels.

License

MIT — see LICENSE. Bundled code-system data follows each upstream registry's licence; details in clinosim/codes/README.md.

Note: the top-level clinosim/ Python package has no dedicated README by design. Module-level documentation lives under clinosim/modules/, and framework docs sit alongside each subsystem — audit/, eval/, codes/, benchmarks/.