Disease Modules

Disease Modules

Synthea ships with 231 disease modules — JSON-based state machines that simulate the progression of conditions over a patient's lifetime.

Module Categories

Cardiovascular

Module	Key Codes
atrial_fibrillation	SNOMED 49436004
cardiac_arrest	SNOMED 410429000
coronary_heart_disease	SNOMED 53741008
heart_failure	SNOMED 84114007
hypertension	SNOMED 59621000
stroke	SNOMED 230690007

Cancer

breast_cancer, colorectal_cancer, lung_cancer, prostate_cancer, skin_cancer, thyroid_cancer

Respiratory

asthma, chronic_obstructive_pulmonary_disease, covid19, influenza, pneumonia, lung_cancer

Metabolic & Endocrine

diabetes, prediabetes, metabolic_syndrome_disease, hypothyroidism, hyperlipidemia

Mental Health

attention_deficit_disorder, anxiety, bipolar, depression, opioid_addiction, schizophrenia, substance_use_disorder

Infectious Disease

allergic_rhinitis, bronchitis, covid19, ear_infections, lyme_disease, sexually_transmitted_infections, urinary_tract_infections, viral_sinusitis

Musculoskeletal

back_pain, fibromyalgia, gout, lupus, osteoarthritis, osteoporosis, rheumatoid_arthritis

Chronic / Other

alzheimers_and_dementias, chronic_kidney_disease, epilepsy, gallstones, macular_degeneration, migraine

Pediatric

childhood_respiratory_disease, cystic_fibrosis, epilepsy, growth tracking (CDC charts), immunization schedules

---

Viewing All Modules

# Print all 231 module names
uv run synthea --list-modules

# Visualise the state machine as a graph
uv run synthea --graphviz diabetes
dot -Tpng diabetes.dot -o diabetes.png

---

Module Structure

Modules are JSON files in resources/modules/. Each module is a directed graph of states connected by transitions.

{
  "name": "My Condition",
  "states": {
    "Initial": {
      "type": "Initial",
      "direct_transition": "Check_Condition"
    },
    "Check_Condition": {
      "type": "Simple",
      "distributed_transition": [
        { "distribution": 0.10, "transition": "Onset" },
        { "distribution": 0.90, "transition": "Terminal" }
      ]
    },
    "Onset": {
      "type": "ConditionOnset",
      "codes": [{
        "system": "SNOMED-CT",
        "code": "44054006",
        "display": "Diabetes mellitus type 2"
      }],
      "direct_transition": "Wait"
    },
    "Wait": {
      "type": "Delay",
      "range": { "low": 1, "high": 5, "unit": "years" },
      "direct_transition": "Terminal"
    },
    "Terminal": { "type": "Terminal" }
  }
}

State Types

Type	Purpose
Initial	Entry point — every module must have exactly one
Terminal	Exit point — patient leaves this module
Simple	No action, just a transition hub
Delay	Advance simulation time
ConditionOnset	Diagnose a condition
ConditionEnd	Resolve a condition
MedicationOrder	Prescribe a medication
MedicationEnd	Stop a medication
Encounter	Record a clinical encounter
EncounterEnd	Close an encounter
Procedure	Perform a procedure
Observation	Record a lab result or vital
ImagingStudy	Record an imaging study
Symptom	Set a symptom value
Death	Mark the patient as deceased
SetAttribute	Store a value on the patient
Guard	Block until a condition is true
CallSubmodule	Invoke another module inline

Transition Types

Type	Behaviour
direct_transition	Always goes to the named state
distributed_transition	Probabilistic — weights must sum to 1.0
conditional_transition	Evaluates a logic condition
complex_transition	Condition + distribution combination
table_transition	Lookup-table-driven probability

Writing a Custom Module

1. Create a JSON file in resources/modules/ or in a custom -d directory.
2. Validate it:

   uv run python -m synthea.validate_module resources/modules/my_module.json

3. Generate using your module:

   uv run synthea -p 50 -m my_module

4. Visualise the state graph:

   uv run synthea --graphviz my_module
   dot -Tpng my_module.dot -o my_module.png

Logic Conditions (used in transitions and Guards)

{
  "condition_type": "And",
  "conditions": [
    { "condition_type": "Age", "operator": ">=", "quantity": 40, "unit": "years" },
    { "condition_type": "Gender", "gender": "M" },
    {
      "condition_type": "Attribute",
      "attribute": "diabetes",
      "operator": "==",
      "value": true
    }
  ]
}

Available condition types: Age, Gender, Race, Socioeconomic Status, Attribute, Symptom, Active Condition, Active Medication, Date, And, Or, Not.