Generating Synthetic Patient Data with Synthea

You cannot develop, test, or demo a clinical NLP pipeline on real PHI without a
mountain of governance — and you shouldn't have to. Synthea (MITRE's
Synthetic Patient Population Simulator) generates statistically realistic,
fully synthetic patients: complete longitudinal records as FHIR R4 bundles,
C-CDA documents, and flat CSV, with zero real-PHI risk. Use it for OpenMed
dev fixtures, CI, demos, and — importantly — as **held-out test sets for
de-identification leakage gates**, where you need known-synthetic "PHI" to
measure recall.

When to use

• Building or demoing an OpenMed ingestion pipeline (FHIR, C-CDA) and need

shareable input that is safe to commit and pass around.

• Creating deterministic CI fixtures so tests don't depend on protected data.
• Producing a leakage-gate test corpus: synthetic notes with known fake

identifiers, so you can score whether openmed.deidentify removed them all.

• Teaching/onboarding without a data-use agreement.

Quick start

Synthea is a Java tool. Generate a small population in multiple formats:

# Requires Java 11+. Clone and build once.
git clone https://github.com/synthetichealth/synthea && cd synthea
./gradlew build -x test

# Generate 50 patients in Massachusetts as FHIR R4 + C-CDA + CSV.
./run_synthea -p 50 Massachusetts \
  --exporter.fhir.export=true \
  --exporter.ccda.export=true \
  --exporter.csv.export=true \
  --exporter.baseDirectory=./output

# Reproducible runs: fix the seed so fixtures are stable across CI.
./run_synthea -s 12345 -p 20 --exporter.baseDirectory=./fixtures

Output lands under output/fhir/, output/ccda/, and output/csv/. Feed the
FHIR bundles to parsing-... skills, or hand narrative straight to OpenMed:

import json, openmed

bundle = json.load(open("output/fhir/Patient_xyz.json"))
for entry in bundle.get("entry", []):
    res = entry.get("resource", {})
    div = (res.get("text") or {}).get("div", "")     # narrative XHTML
    if div.strip():
        deid = openmed.deidentify(div, method="replace", policy="hipaa_safe_harbor")
        result = openmed.analyze_text(deid.text, output_format="dict")

Synthea data is synthetic, so de-identifying it is exercising the pipeline,
not a privacy requirement — which is exactly what makes it a great test bed.

Workflow

1. Choose scale & geography. -p N sets population; the state/location

argument shapes demographics and addresses. Start small (10–50) for fixtures.

1. Pick formats. Enable FHIR (exporter.fhir.export), C-CDA

(exporter.ccda.export), and/or CSV per your ingestion path. FHIR R4 is the
default and pairs with fetching-fhir-resources; C-CDA pairs with
parsing-ccda-documents.

1. Pin a seed (-s) for reproducible fixtures so test assertions are stable.
2. Select modules (optional). Synthea ships disease modules

(-m "diabetes*" to filter); choose modules matching the entities your
OpenMed pipeline targets.

1. Use as a leakage-gate corpus. Synthea emits known fake names, MRNs,

addresses, and dates — inject/collect these as ground-truth PHI spans and
score openmed.deidentify recall with openmed.eval
(evaluating-with-leakage-gates). Because the "PHI" is synthetic and known,
you can measure misses without exposing anyone.

1. Commit fixtures under your test tree (e.g. tests/fixtures/synthea/) —

it is safe to version-control synthetic output.

Hand-off to / from OpenMed

• To OpenMed (as input): Synthea FHIR/C-CDA narrative → openmed.deidentify

→ openmed.analyze_text, via the fetching-fhir-resources and
parsing-ccda-documents skills.

• To OpenMed eval: use Synthea's known synthetic identifiers as ground truth

for openmed.eval de-identification leakage gates — the daily-release thesis
gates on leakage, not F1 alone, and synthetic data lets you build that test
set without governance overhead.

• Adjacent, not in-pipeline: Synthea is a source of safe data; it does not

call OpenMed and OpenMed does not call it. Keep it in dev/CI, never as a
production data source.

Edge cases & gotchas

• Synthetic ≠ statistically perfect. Synthea reproduces realistic disease

progression and demographics but is not a substitute for real-world
distribution validation; never report clinical model accuracy only on
synthetic data.

• Narrative is templated. FHIR text.div narrative is generated from

templates, so it is more regular than dictated notes. For NER robustness,
supplement with varied real (de-identified) text where governance allows.

• Determinism needs the seed. Without -s, every run differs — CI fixtures

will churn. Always pin the seed for committed fixtures.

• Version drift. Synthea modules and FHIR profile output change across

releases; pin the Synthea version (git tag) alongside your fixtures.

• Large populations are heavy. -p 100000 produces gigabytes; size to need.
• Licensing. Synthea and its generated output are permissively licensed

(Apache-2.0), so output is safe to redistribute — unlike MIMIC/i2b2/n2c2,
which require data-use agreements and must stay user-supplied.

Standards & references

• Synthea project & docs: https://github.com/synthetichealth/synthea
• Synthea wiki (running, modules, exporters):

https://github.com/synthetichealth/synthea/wiki

• Walonoski J, et al. "Synthea: An approach, method, and software mechanism for

generating synthetic patients..." JAMIA 2018:
https://doi.org/10.1093/jamia/ocx079

• FHIR R4: https://hl7.org/fhir/R4/
• C-CDA R2.1: https://www.hl7.org/ccdasearch/