tanat-synthea

Synthetic patient journey datasets for longitudinal analysis.

Built on Synthea and designed for use with TanaT and FedBioMed. Supports US, French, and UK cohorts out of the box.

Freely reproducible. No registration, no data access agreement.

Installation

pip install tanat-synthea

Single site

from tanat_synthea import PatientJourney

pj = PatientJourney(
    "data/single_site/",
    name="CHU de Lyon",
    country_code="fr",
    state="Auvergne-Rhone-Alpes",
    population=100,
    seed=42,
    age_range="20-80",
)
pj.generate()

# Demographics (one row per patient)
pj.static_data()

# Clinical records (one row per record)
pj.temporal_data(record_types=["encounter", "condition"])

# Raw reference file
pj.load_file("organizations.csv")

Data is generated automatically on first access if it does not exist yet.

Multi-center (federated)

Quickstart - build on demo preset:

from tanat_synthea import FedPatientJourney

# Preset: 3 centers (US / FR / GB), 50 patients each
fpj = FedPatientJourney.demo()
fpj.generate()          # trigger Synthea for all centers

# Per-center access: isolated FL node
for pj in fpj.iter_centers():
    local = pj.temporal_data(record_types=["encounter", "condition"])

Configure each center manually:

fpj = FedPatientJourney([
    # Center 0
    PatientJourney("data/center_0/", name="CHU de Lyon",
                    country_code="fr", state="Auvergne-Rhone-Alpes",
                    population=100, seed=42, age_range="20-80"),
    # Center 1
    PatientJourney("data/center_1/", name="St Thomas' London",
                    country_code="gb", state="Greater London",
                    population=100, seed=123, age_range="40-85"),
    # Center 2
    PatientJourney("data/center_2/", name="Mass General",
                    country_code="us", state="Massachusetts",
                    population=100, seed=777, age_range="20-60"),
])

Or drive the federation from a YAML config:

fpj = FedPatientJourney.from_yaml("configs/demo.yaml")

TanaT integration

tanat-synthea is designed as a data source for TanaT.

from tanat_synthea import PatientJourney
from tanat import build_intervals, build_events
from tanat import TrajectoryPool

pj = PatientJourney("data/single_site/", state="Massachusetts", population=100)
pj.generate()

static   = pj.static_data()
tables   = pj.temporal_data(by_record_type=True)

# Interval sequences from diagnoses
condition_pool = build_intervals(
    tables["condition"],
    id_column="PATIENT",
    start_column="START",
    end_column="STOP",
    static_data=static,
    store_name="conditions",
)

# Event sequences from lab results
observation_pool = build_events(
    tables["observation"],
    id_column="PATIENT",
    time_column="DATE",
    static_data=static,
    store_name="observations",
)

# Combine into trajectories
tpool = (
    TrajectoryPool.builder()
    .add("conditions", condition_pool)
    .add("observations", observation_pool)
    .build("trajectory", exist_ok=True)
)

The same pattern works per-center in a federated setup (see notebooks/fed_patient_journey.ipynb).

CLI

# Generate all centers defined in a config file
tanat-synthea --config configs/demo.yaml

# Single center only
tanat-synthea --config configs/demo.yaml --center 0

# Preview Synthea commands without running them
tanat-synthea --config configs/demo.yaml --dry-run

The Synthea JAR (~190 MB) is downloaded automatically on first run if missing. See configs/demo.yaml for full documentation of available options.

License

MIT License