Synthea

https://github.com/synthetichealth/synthea
Admin
Synthea is a synthetic patient population simulator that generates realistic, de-identified patient...
Tokens:131,856
Snippets:911
Trust Score:9.1
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Synthea settings file example

Source: https://github.com/synthetichealth/synthea/wiki/Common-Configuration

Example of a Synthea settings file format. Each line sets a configuration option; lines starting with # are comments. This sample enables FHIR R4 export while disabling CCDA, STU3, and DSTU2 exports.

```properties
# this is a comment
exporter.ccda.export = false
exporter.fhir.export = true
exporter.fhir_stu3.export = false
exporter.fhir_dstu2.export = false
```

--------------------------------

### Run Synthea with custom modules directory (basic setup)

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Running-New-Modules

Command for the basic setup to run Synthea with a custom modules directory. Replace 'path/to/modules/directory' with the actual path.

```bash
java -jar synthea-with-dependencies.jar -d path/to/modules/directory
```

--------------------------------

### Install Ruby gems and clone Synthea

Source: https://github.com/synthetichealth/synthea/wiki/Windows-installation

Commands to clone the Synthea repository and install required gems.

```bash
cd c:\git
git clone https://github.com/synthetichealth/synthea.git
cd synthea
gem install bundler
bundle install
```

--------------------------------

### Run Synthea with custom settings (basic setup)

Source: https://github.com/synthetichealth/synthea/wiki/Common-Configuration

Run Synthea with a custom settings file using the basic setup. The -c flag specifies the path to the settings file.

```bash
java -jar synthea-with-dependencies.jar -c path/to/settings/file
```

--------------------------------

### Example output from default run

Source: https://github.com/synthetichealth/synthea/wiki/Basic-Setup-and-Running

Example output after running the default command. Shows module loading, run options, and a generated patient record.

```text
Scanned 60 modules and 36 submodules.
Loading submodule modules/breast_cancer/tnm_diagnosis.json
Loading submodule modules/allergies/allergy_incidence.json
Loading submodule modules/dermatitis/moderate_cd_obs.json
...
Loading module modules/opioid_addiction.json
Loading module modules/dialysis.json
...
Loading module modules/hypertension.json
Running with options:
Population: 1
Seed: 1570658792125
Provider Seed:1570658792125
Location: Massachusetts
Min Age: 0
Max Age: 140
1 -- Arthur650 Carroll471 (39 y/o M) Southwick, Massachusetts 
{alive=1, dead=0}
```

--------------------------------

### Run Synthea with custom settings (developer setup)

Source: https://github.com/synthetichealth/synthea/wiki/Common-Configuration

Run Synthea with a custom settings file using the developer setup. The -c flag specifies the path to the settings file.

```bash
./run_synthea -c path/to/settings/file
```

--------------------------------

### Run Synthea with custom modules directory (developer setup)

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Running-New-Modules

Command for the developer setup to run Synthea with a custom modules directory. Replace 'path/to/modules/directory' with the actual path.

```bash
./run_synthea -d path/to/modules/directory
```

--------------------------------

### Example overrides file snippet

Source: https://github.com/synthetichealth/synthea/wiki/Module-Overrides

Example snippet of an overrides file showing how to set distribution values for specific transitions in the congestive_heart_failure and atopy modules.

```properties
congestive_heart_failure.json\:\:$['states']['Age_70-79-Chance\ of\ CHF']['distributed_transition'][0]['distribution'] = 0.024
congestive_heart_failure.json\:\:$['states']['Age_80-Chance\ of\ CHF']['distributed_transition'][0]['distribution'] = 0.045
atopy.json\:\:$['states']['Initial']['complex_transition'][0]['distributions'][0]['distribution'] = 0.917
atopy.json\:\:$['states']['Initial']['complex_transition'][1]['distributions'][0]['distribution'] = 0.033
```

--------------------------------

### run_synthea example invocations

Source: https://github.com/synthetichealth/synthea/wiki/Developer-Setup-and-Running

A list of example commands demonstrating various run_synthea options, such as specifying location, seed, population size, age range, gender, and FHIR export settings.

```bash
run_synthea -h
```

```bash
run_synthea Massachusetts
```

```bash
run_synthea Alaska Juneau
```

```bash
run_synthea -s 12345
```

```bash
run_synthea -p 1000
```

```bash
run_synthea -a 30-40
```

```bash
run_synthea -g F
```

```bash
run_synthea -s 987 Washington Seattle
```

```bash
run_synthea -s 21 -p 100 Utah "Salt Lake City"
```

```bash
run_synthea --exporter.fhir.use_us_core_ig true --exporter.fhir.us_core_version 4.0.0
```

--------------------------------

### BFD end_state.properties example

Source: https://github.com/synthetichealth/synthea/wiki/BFD-RIF-Export

Example of the end_state.properties file that captures the final values of monotonically increasing or decreasing configuration options after a Synthea BFD export run. Use these values with the -c command line switch to override the configured values so subsequent runs start where the prior run ended.

```properties
exporter.bfd.hicn_start=T01000020A
exporter.bfd.mbi_start=1S00E00AA20
exporter.bfd.clm_grp_id_start=-100003266
exporter.bfd.pde_id_start=-100000996
exporter.bfd.fi_doc_cntl_num_start=-100000575
exporter.bfd.bene_id_start=-1000020
exporter.bfd.carr_clm_cntl_num_start=-100001695
exporter.bfd.clm_id_start=-100002270
```

--------------------------------

### Install Graphviz and run rake task to generate diagram

Source: https://github.com/synthetichealth/synthea/wiki/Graphviz-Rules-Diagram

Install Graphviz via Homebrew, then run the rake task to generate the flowchart diagram. The output is saved as output/graphviz/synthea_rules.png.

```bash
brew install graphviz
bundle exec rake synthea:graphviz
```

--------------------------------

### CallSubmodule state example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Calls the 'medications/otc_pain_reliever' submodule in the current time step. The submodule's states are processed immediately, starting from its Initial state, and execution resumes after its Terminal state is reached.

```json
"Medication_Submodule": {
  "type": "CallSubmodule",
  "submodule": "medications/otc_pain_reliever"
}
```

--------------------------------

### Example output from run_synthea

Source: https://github.com/synthetichealth/synthea/wiki/Developer-Setup-and-Running

Shows the expected output when running ./run_synthea, including module loading, run options, and a sample patient line.

```text
example@hostname ~/synthea $ ./run_synthea

> Task :run
Loading C:\Users\example\synthea\build\resources\main\modules\allergic_rhinitis.json
Loading C:\Users\example\synthea\build\resources\main\modules\allergies\allergy_incidence.json
[... many more lines of Loading ...]
Loading C:\Users\example\synthea\build\resources\main\modules\wellness_encounters.json
Loaded 68 modules.
Running with options:
Population: 1
Seed: 1519063214833
Location: Massachusetts

1 -- Jerilyn993 Parker433 (10 y/o) Lawrence, Massachusetts
```

--------------------------------

### Run Synthea with custom exporter (Basic Setup)

Source: https://github.com/synthetichealth/synthea/wiki/Custom-Exporters

Add the custom exporter JAR to the classpath and run Synthea with the -cp flag. Other options may be appended to the end of the command.

```sh
java -jar synthea-with-dependencies.jar -cp path/to/custom-exporter-template.jar
```

--------------------------------

### run_synthea help output

Source: https://github.com/synthetichealth/synthea/blob/master/README.md

Full usage information printed by passing the -h option. Shows all available options and example invocations.

```bash
$ ./run_synthea -h

> Task :run
Usage: run_synthea [options] [state [city]]
Options: [-s seed]
         [-cs clinicianSeed]
         [-p populationSize]
         [-r referenceDate as YYYYMMDD]
         [-g gender]
         [-a minAge-maxAge]
         [-o overflowPopulation]
         [-c localConfigFilePath]
         [-d localModulesDirPath]
         [-i initialPopulationSnapshotPath]
         [-u updatedPopulationSnapshotPath]
         [-t updateTimePeriodInDays]
         [-f fixedRecordPath]
         [-k keepMatchingPatientsPath]
         [--config*=value]
          * any setting from src/main/resources/synthea.properties

Examples:
run_synthea Massachusetts
run_synthea Alaska Juneau
run_synthea -s 12345
run_synthea -p 1000
run_synthea -s 987 Washington Seattle
run_synthea -s 21 -p 100 Utah "Salt Lake City"
run_synthea -g M -a 60-65
run_synthea -p 10 --exporter.fhir.export=true
run_synthea --exporter.baseDirectory="./output_tx/" Texas
```

--------------------------------

### Flexporter value functions example

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

Example of using value functions in a Flexporter create_resource configuration. Demonstrates getField, findRef, and randomCode with a ServiceRequest based on a Procedure.

```yaml
 -  create_resource: 
     - resourceType: ServiceRequest
       based_on: 
         resource: Procedure
       fields:
         - location: ServiceRequest.intent
           value: plan
         - location: ServiceRequest.encounter.reference
           value: $getField([Procedure.encounter.reference])
         - location: ServiceRequest.subject.reference
           value: $findRef([Patient])
         - location: ServiceRequest.code.coding
           value: $randomCode([http://hl7.org/fhir/us/mcode/ValueSet/mcode-laterality-vs])
```

--------------------------------

### Direct transition example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Transitions

Shows a direct_transition from an Initial state to the 'Delay_For_Encounter' state. The value is simply the name of the target state.

```json
"Initial": {
  "type": "Initial",
  "direct_transition": "Delay_For_Encounter"
}
```

--------------------------------

### Run Synthea with default options

Source: https://github.com/synthetichealth/synthea/wiki/Basic-Setup-and-Running

Run Synthea from the directory where the binary was downloaded. The command starts a default simulation generating one patient in Massachusetts.

```bash
cd /directory/you/downloaded/synthea/to
java -jar synthea-with-dependencies.jar
```

--------------------------------

### Simple state definition example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Basics

Shows the minimal definition of a state, which requires a 'type' field. This example defines a state named 'Hello_World' with type 'Simple'. State names must be unique within a module and are typically written in Upper_Snake_Case.

```json
"Hello_World": {
  "type": "Simple"
}
```

--------------------------------

### Apply Profiles action example

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

Example of the Apply Profiles action. It adds the qicore-patient profile to all Patient resources and qicore-encounter to all Encounters. The applicability field is a FHIRPath that selects resources to which the profile is added.

```yaml
 - name: Apply Profiles
   profiles:
   - profile: http://hl7.org/fhir/us/qicore/StructureDefinition/qicore-patient
     applicability: Patient
   - profile: http://hl7.org/fhir/us/qicore/StructureDefinition/qicore-encounter
     applicability: Encounter
```

--------------------------------

### Synthea physiology generator input/output YAML example

Source: https://github.com/synthetichealth/synthea/wiki/Physiology-Models

Example YAML configuration for a Synthea physiology generator, showing an input mapping from a patient expression to the R_sys parameter and an output mapping to Left ventricular Ejection fraction. The fromExp field supports patient chart variables via #{foo}, if-then-else logic, and functions like Max() and Min(). The variance field sets allowable input variance to avoid running the simulation.

```yaml
inputs:
#  # Effects of age and BMI loosely estimated from a comprehensive study on adult blood pressure
#  # percentiles (https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4553889/)
#  # More research is needed to determine appropriate age / BMI effects on all model parameters.
 - fromExp: "1.1889 + 0.025 * (#{BMI} - 21.7) + (if #b{blood_pressure_controlled} then 0 else (0.0112 * #{age}))"
   to: R_sys
   variance: 0.25 # Allowable variance in input to avoid running simulation
   
outputs:
 - fromExp: "((Max(#{V_lv}) - Min(#{V_lv})) / Max(#{V_lv}))*100"
   to: Left ventricular Ejection fraction
```

--------------------------------

### CarePlanStart state example with diabetes care plan

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Example of a CarePlanStart state that prescribes a diabetes self-management plan during the Annual_Checkup encounter, citing the Diabetes ConditionOnset as the reason. It assigns the care plan to the attribute 'diabetes_careplan' and includes a diabetic diet activity.

```json
"Diabetes_CarePlan": {
  "type": "CarePlanStart",
  "assign_to_attribute": "diabetes_careplan",
  "reason": "Diabetes",
  "codes": [
    {
      "system": "SNOMED-CT",
      "code": "698360004",
      "display": "Diabetes self management plan"
    }
  ],
  "activities": [
    {
      "system": "SNOMED-CT",
      "code": "160670007",
      "display": "Diabetic diet"
    }
  ]
}
```

--------------------------------

### File Structure for MDT Submodule

Source: https://github.com/synthetichealth/synthea/wiki/Medication-Diversification-Tool-(MDT)

Example file structure showing where to place the submodule JSON and transition table CSV files within the Synthea resources directory.

```text
synthea/
├─ src/
│  ├─ main/
|  │  ├─ resources/
|  │  │  ├─ modules/
|  │  │  │  ├─ medication/
|  │  │  │  │  ├─ maintenance_inhaler.json
|  │  │  │  │  ├─ ...
|  │  │  │  ├─ lookup_tables/
|  │  │  │  │  ├─ maintenance_inhaler_ingredient_distribution.csv
|  │  │  │  │  ├─ maintenance_inhaler_fluticasone_product_distribution.csv
|  │  │  │  │  ├─ maintenance_inhaler_budesonide_product_distribution.csv
|  │  │  │  │  ├─ maintenance_inhaler_beclomethasone_product_distribution.csv
|  │  │  │  │  ├─ maintenance_inhaler_mometasone_product_distribution.csv
|  │  │  │  │  ├─ ...
|  │  │  │  ├─ asthma.json
|  │  │  │  ├─ ...
```

--------------------------------

### Reuse inspector container for subsequent runs

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

Start the existing inspector container with docker start -i to inspect the output volume again. Docker already knows the volume and TTY settings.

```bash
$ docker start -i inspector
$ cd /mnt/synthea && ls
```

--------------------------------

### Example sequence of commands to evolve a population

Source: https://github.com/synthetichealth/synthea/wiki/Evolving-a-Population

Commands that create output directories, generate an initial population of 5 records, save a snapshot, then load and evolve the population for 100 days twice, saving updated snapshots. Each step uses a different output directory to avoid export failures.

```sh
$ mkdir -p output/1 output/2 output/3
$ ./run_synthea -p 5 -u output/1/snap --exporter.baseDirectory output/1
$ ./run_synthea -i output/1/snap -u output/2/snap -t 100 --exporter.baseDirectory output/2
$ ./run_synthea -i output/2/snap -u output/3/snap -t 100 --exporter.baseDirectory output/3
```

--------------------------------

### Abridged example for United Kingdom zip codes CSV

Source: https://github.com/synthetichealth/synthea/wiki/Zip-or-Postal-Codes

Partial example showing the CSV format for UK postal codes, with a region (West Midlands) used as the state. The first column is ignored by Synthea.

```csv
,USPS,ST,NAME,ZCTA5,LAT,LON
0,West Midlands,WMS,Shrewsbury,SY1,52.7081,-2.7549
1,West Midlands,WMS,Shrewsbury,SY2,52.7083,-2.7546
2,West Midlands,WMS,Shrewsbury,SY3,52.7089,-2.7543
```

--------------------------------

### Run Synthea with Flexporter mapping file

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

Run Synthea with the Flexporter mapping file. The -fm flag specifies the mapping file, and the optional -ig flag specifies an implementation guide folder.

```bash
./run_synthea -fm mapping_file [-ig ig_folder]
```

--------------------------------

### ImagingStudy state example for ankle X-ray

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Example of an ImagingStudy state that captures a single X-Ray image of the patient's ankle. The state must occur during an Encounter and adds both an ImagingStudy and a Procedure to the patient's record. The series includes a body_site, modality, and instances with a title and sop_class.

```json
"Ankle_X_Ray": {
  "type": "ImagingStudy",
  "procedure_code": {
    "system": "SNOMED-CT",
    "code": "19490002",
    "display": "Ankle X-ray"
  },
  "series": [
    {
      "body_site": {
        "system": "SNOMED-CT",
        "code": "344001",
        "display": "Ankle"
      },
      "modality": {
        "system": "DICOM-DCM",
        "code": "DX",
        "display": "Digital Radiography"
      },
      "instances": [
        {
          "title": "Image of ankle",
          "sop_class": {
            "system": "DICOM-SOP",
            "code": "1.2.840.10008.5.1.4.1.1.1.1",
            "display": "Digital X-Ray Image Storage"
          }
        }
      ]
    }
  ]
}
```

--------------------------------

### Units of measurement example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Basics

Shows a unit of measurement. Any string is valid, but metric units are typically used.

```json
{
  "unit": "cm"
}
```

--------------------------------

### AllergyOnset state with target_encounter and reactions

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Example of an AllergyOnset state that is diagnosed at the "ED_Visit" Encounter. In this example, 21% of individuals passing through this state will have an allergy to peanuts with a mild cough as a reaction, while the other 79% will have an allergy to peanuts with no reactions listed.

```json
"Peanut_allergy": {
  "type": "AllergyOnset",
  "allergy_type": "allergy",
  "category": "food",
  "target_encounter": "ED_Visit",
  "codes": [
    {
    "system": "SNOMED-CT",
    "code": "762952008",
    "display": "Peanut (substance)"
    }
  ],
  "reactions": [
    {
      "reaction": {"system":  "SNOMED-CT", "code": "49727002", "display":  "Cough (finding)"},
      "possible_severities": [
         {"level":  "mild", "value": 0.21},
         {"level":  "none", "value":  0.79}
      ]
    }
 ...
}

```

--------------------------------

### Flexporter mapping file structure

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

Example mapping file showing the top-level fields: name, applicability, variables, customValueSets, and actions. Variables can be referenced in FHIRPath expressions using %variableName. customValueSets are loaded into Synthea at startup and can be referenced by URL.

```yaml
---
# name is just a friendly name for this mapping
name: Flexporter Mapping

# applicability determines whether this mapping applies to a given file.
# for now the assumption is 1 file = 1 synthea patient bundle.
# this should be a FHIRPath which should return a "truthy" value if the mapping applies
applicability: true

# variables (optional) allow for defining variables to be used in FHIRPath expressions, 
# for example the `primaryCancerConditionCodes` variable defined as a list below may be referenced elsewhere with the FHIRPath expression
# `Condition.code.coding.where($this.code in %primaryCancerConditionCodes)`
# Variables may be of any YAML type.
variables:
  primaryCancerConditionCodes:
    - '188151006' # Malignant neoplasm of central part of female breast (disorder)
    - '254837009' # Malignant neoplasm of breast (disorder) (B)
    - '93761005' # Primary malignant neoplasm of colon (C)

# customValueSets (optional) allow for defining ValueSets within the mapping file itself. ValueSets defined here will be loaded into Synthea at startup and can be referenced by URL anywhere in Synthea that a ValueSet is used. 
# A primary intent for this is to make it easier to load simple valuesets without having to configure Synthea to point to a terminology server. 
# The format of a customValueSet is the YAML equivalent of a FHIR R4 ValueSet: https://hl7.org/fhir/R4/valueset.html
customValueSets:
 - url: http://example.org/encounterType
   compose:
     include:
       - system: http://terminology.hl7.org/CodeSystem/encounter-type
         concept:
           - code: ADMS
             display: Annual diabetes mellitus screening
           - code: OKI
             display: Outpatient Kenacort injection


# actions is a list of Action objects. see below for details
actions:
 - name: Apply Profiles
...
```

--------------------------------

### JSON lookup_table_transition example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Transitions

Defines a Simple state with a lookup_table_transition array containing two transitions, each specifying a transition name, default_probability, and lookup_table_name. The default_probability is used when the lookup table has no match.

```json
"Determine_Condition": {
  "type": "Simple",
  "name": "Determine_Condition",
  "lookup_table_transition": [
    {
      "transition": "Lookuptablitis",
      "default_probability": "0",
      "lookup_table_name": "lookuptablitis.csv"
    },
    {
      "transition": "No_Lookuptablitis",
      "default_probability": "1",
      "lookup_table_name": "lookuptablitis.csv"
    }
  ]
}
```

--------------------------------

### Initial state definition

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Defines the mandatory starting state for a generic module. The state name must be exactly "Initial" and only one such state is allowed per module.

```json
"Initial": {
  "type": "Initial"
}
```

--------------------------------

### Good attribute name example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Basics

Shows a valid attribute name using lower_snake_case. Attribute names must be unique across all modules.

```json
{
  "assign_to_attribute": "opioid_prescription"
}
```

--------------------------------

### Remarks section example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Basics

Shows the structure of a remarks section in a GMF module. Remarks are ignored by Synthea and are used for references and details. They must be a list of strings.

```json
{
  "remarks": [
    "Remarks describe their parent object or detail important ",
    "aspects of the module. Links to sources may be included here: ",
    "http://www.example.com/source/ ",
    
    "You may write use extra newlines to separate out remarks."
  ]
}
```

--------------------------------

### MedicationOrder with as_needed true

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Example of a MedicationOrder with as_needed set to true, indicating the medication may be taken as needed. In this case, dosage information does not need to be specified.

```json
"Examplitol": {
  "type": "MedicationOrder",
  "reason": "Examplitis",
  "codes": [
    {
      "system": "RxNorm",
      "code": "123456",
      "display": "Examplitol 100mg [Examplitol]"
    }
  ],
  "prescription": {
    "as_needed": true
  }
}
```

--------------------------------

### Resulting output files after evolving population

Source: https://github.com/synthetichealth/synthea/wiki/Evolving-a-Population

Shows the output file structure after running the example commands: snapshot files and FHIR JSON files for each of the 5 records in each output directory.

```sh
output/1/snap
output/1/fhir/
    Dominique369_Kirlin939_b7c98c3d-d948-46f1-85eb-c26568aa15bf.json 
    Verdell500_Renner328_fc4a3b26-e0c6-4215-a9aa-1f15edfe4208.json
    Harley673_Heller342_dd96e3c8-fb6c-4371-849c-3f9c31b19644.json
    Kum811_Wintheiser220_32b8d335-473a-4df9-86ae-b75daed3f3ea.json
    Silva841_Hamill307_efe4f638-b8df-48e4-a05d-fc2f2c9e1857.json
output/2/snap
output/2/fhir/
    Dominique369_Kirlin939_b7c98c3d-d948-46f1-85eb-c26568aa15bf.json 
    Verdell500_Renner328_fc4a3b26-e0c6-4215-a9aa-1f15edfe4208.json
    Harley673_Heller342_dd96e3c8-fb6c-4371-849c-3f9c31b19644.json
    Kum811_Wintheiser220_32b8d335-473a-4df9-86ae-b75daed3f3ea.json
    Silva841_Hamill307_efe4f638-b8df-48e4-a05d-fc2f2c9e1857.json
output/3/snap
output/3/fhir/
    Dominique369_Kirlin939_b7c98c3d-d948-46f1-85eb-c26568aa15bf.json 
    Verdell500_Renner328_fc4a3b26-e0c6-4215-a9aa-1f15edfe4208.json
    Harley673_Heller342_dd96e3c8-fb6c-4371-849c-3f9c31b19644.json
    Kum811_Wintheiser220_32b8d335-473a-4df9-86ae-b75daed3f3ea.json
    Silva841_Hamill307_efe4f638-b8df-48e4-a05d-fc2f2c9e1857.json
```

--------------------------------

### Physiology state example: Simulate_CVS

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Example Physiology state that simulates cardiac hemodynamics during an Encounter. Uses the Smith2004_CVS_human.xml model with runge_kutta solver, 0.01s step size, 4.0s duration, and 2.0s lead time. Inputs map patient vital signs/attributes to model parameters; outputs capture model values into patient attributes, including LVEF, SBP, and DBP expressions.

```json
"Simulate_CVS": {
      "type": "Physiology",
      "model": "circulation/Smith2004_CVS_human.xml",
      "solver": "runge_kutta",
      "step_size": 0.01,
      "sim_duration": 4.0,
      "lead_time": 2.0,
      "inputs": [
        {"from": "Pulmonary Resistance", "to": "R_pul"},
        {"from_exp": "#{BMI} * #{BMI Multiplier}", "to": "R_sys"}
      ],
      "outputs": [
        {
          "from": "V_ao",
          "to": "Final Aortal Volume",
          "type": "Attribute"
        },
        {
          "from_list": "P_ao",
          "to": "Arterial Pressure Values",
          "type": "Attribute"
        },
        {
          "from_exp": "((Max(#{V_lv}) - Min(#{V_lv})) / Max(#{V_lv}))*100",
          "to": "LVEF",
          "type": "Attribute"
        },
        {
          "from_exp": "Max(#{P_ao})",
          "to": "SBP",
          "type": "Attribute"
        },
        {
          "from_exp": "Min(#{P_ao})",
          "to": "DBP",
          "type": "Attribute"
        }
      ],
      "direct_transition": "ChartObservation",
      "alt_direct_transition": "ContrivedLVEF"
    }
```

--------------------------------

### Basic module structure with name, remarks, and states

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Basics

Defines the minimal structure of a Generic Module Framework module. Requires a 'name' and a 'states' object containing at least an 'Initial' state. Includes optional 'remarks' for comments. The example shows an 'Initial' state with a direct transition to a 'Terminal' state.

```json
{
  "name": "The Name of the Module",
  "remarks": [
    "Additional comments about the module, ",
    "perhaps on multiple lines. Links to sources ",
    "also go here."
  ],
  "states": {
    
    "Initial": {
      "type": "Initial",
      "remarks": [
        "Every module needs an initial state. Most ",
        "modules should also have a Terminal state."
      ],
      "direct_transition": "Terminal"
    },
    
    "Terminal": {
      "type": "Terminal"
    }
  }
}
```

--------------------------------

### Create Resource with based_on and writeback

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

Example of the create_resource rule that creates a ServiceRequest based on a Procedure, using $getField and $findRef to populate fields and $setRef for writeback.

```yaml
 - name: testCreateResources_createBasedOn
   create_resource: 
     - resourceType: ServiceRequest
       based_on:
         resource: Procedure
       fields:
         - location: ServiceRequest.intent
           value: plan
         - location: ServiceRequest.encounter.reference
           value: $getField([Procedure.encounter.reference])
         - location: ServiceRequest.subject.reference
           value: $findRef([Patient])
       writeback:
         - location: Procedure.basedOn.reference
           value: $setRef([ServiceRequest])
```

--------------------------------

### Active Allergy condition with referenced_by_attribute example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Logic

Returns true if the allergy referenced by the attribute "penicillin_allergy" is currently active. The attribute must store an allergy that has started.

```json
{
  "condition_type" : "Active Allergy",
  "referenced_by_attribute" : "penicillin_allergy"
}
```

--------------------------------

### Generate synthetic dataset with Synthea

Source: https://github.com/synthetichealth/synthea/wiki/Running-in-the-Cloud-with-AWS

Run this command on the EC2 terminal to generate synthetic data. The instance already has Amazon Corretto and synthea-with-dependencies.jar installed. The -p 1000 flag generates 1000 patients.

```bash
java -jar synthea-with-dependencies.jar -p 1000
```

--------------------------------

### DICOM-SOP Code Example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Basics

Example of a DICOM-SOP code used only for ImagingStudy states to describe an individual image instance.

```json
{
  "system": "DICOM-SOP",
  "code": "1.2.840.10008.5.1.4.1.1.1.1",
  "display": "Digital X-Ray Image Storage"
}
```

--------------------------------

### Run Flexporter standalone

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

Run the Flexporter standalone to post-process FHIR Bundles. The -fm flag specifies the mapping file, -s specifies the source FHIR, and -ig is optional for an implementation guide folder.

```bash
./run_flexporter -fm mapping_file -s source_fhir [-ig ig_folder]
```

--------------------------------

### DICOM-DCM Code Example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Basics

Example of a DICOM-DCM code used only for ImagingStudy states to describe the modality of an image series.

```json
{
  "system": "DICOM-DCM",
  "code": "MR",
  "display": "Magnetic Resonance"
}
```

--------------------------------

### CSV lookup table example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Transitions

CSV file defining the lookup table for the transition. Columns include patient attributes (age, gender, state) and transition probabilities for each transition name. The last columns must match the transition names and contain numeric probabilities between 0.0 and 1.0.

```csv
age,gender,state,Lookuptablitis,No_Lookuptablitis
0-17,M,Massachusetts,0,1
18-44,M,Massachusetts,0.25,0.75
45-64,M,Massachusetts,0.5,0.5
64-140,M,Massachusetts,0.75,0.25
0-17,F,Massachusetts,0,1
18-44,F,Massachusetts,0.3,0.7
45-64,F,Massachusetts,0.8,0.2
64-140,F,Massachusetts,0,1
...
```

--------------------------------

### Execute Script with bundle and resource functions

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

Example of the execute_script rule that runs two JavaScript functions: one on the bundle to add a dummy profile to the first resource, and one on each resource to set birthDate to '2022-02-22' for Patient resources.

```yaml
 - name: testExecuteScript
   execute_script:
     - apply_to: bundle
       function_name: apply
       function: |
          function apply(bundle) {
            bundle['entry'][0]['resource']['meta'] = {profile: ['http://example.com/dummy-profile']}
          }
     - apply_to: resource
       function_name: apply2
       function: |
         function apply2(resource, bundle) {
           if (resource.resourceType == 'Patient') {
             resource.birthDate = '2022-02-22';
           }
         }
```

--------------------------------

### MedicationOrder with prescription dosage and instructions

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Example of a MedicationOrder with detailed prescription information: 2 refills, dosage of 1 dose twice per day, duration of 2 weeks, and an instruction to take before food.

```json
"Examplitol": {
  "type": "MedicationOrder",
  "reason": "Examplitis",
  "codes": [
    {
      "system": "RxNorm",
      "code": "123456",
      "display": "Examplitol 100mg [Examplitol]"
    }
  ],
  "prescription": {
    "refills": 2,
    "dosage": {
      "amount": 1,
      "frequency": 2,
      "period": 1,
      "unit": "days"
    },
    "duration": {
      "quantity": 2,
      "unit": "weeks"
    },
    "instructions": [
      {
        "system": "SNOMED-CT",
        "code": "311501008",
        "display": "Half to one hour before food"
      }
    ]
  }
}
```

--------------------------------

### LOINC Code Example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Basics

Example of a LOINC code used only for Observation states. Valid codes can be found in the LOINC Browser.

```json
{
  "system": "LOINC",
  "code": "33756-8",
  "display": "Polyp size greatest dimension by CAP cancer protocols"
}
```

--------------------------------

### MedicationOrder with reason and assign_to_attribute

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Example of a MedicationOrder state that prescribes Metformin during an Encounter, citing the "Diabetes" condition as the reason. It assigns the state to the attribute "diabetes_medication".

```json
"Prescribe_Metformin": {
  "type": "MedicationOrder",
  "assign_to_attribute": "diabetes_medication",
  "reason": "Diabetes",
  "codes": [
    {
      "system": "RxNorm",
      "code": "860975",
      "display": "24 HR Metformin hydrochloride 500 MG Extended Release Oral Tablet"
    }
  ]
}
```

--------------------------------

### RxNorm Code Example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Basics

Example of an RxNorm code used only for MedicationOrder states. Must have an NDC on the market, now or in the past, to be prescribe-able.

```json
{
  "system": "RxNorm",
  "code": "575971",
  "display": "oxaliplatin 5 MG/ML [Eloxatin]"
}
```

--------------------------------

### Synthea run_synthea options for snapshot and evolution

Source: https://github.com/synthetichealth/synthea/wiki/Evolving-a-Population

Shows the command-line options for snapshotting and evolving a population: -u for updated snapshot path, -i for initial snapshot path, and -t for update time period in days.

```text
run_synthea [options] [state [city]]
Options: [-u updatedPopulationSnapshotPath]
         [-i initialPopulationSnapshotPath]
         [-t updateTimePeriodInDays]
```

--------------------------------

### Conditional transition example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Transitions

JSON state definition using a conditional_transition array to route patients based on gender. The first matching condition transitions to the corresponding state; the final element without a condition serves as a fallback for unrecognized genders.

```json
"Initial": {
  "type": "Initial",
  "conditional_transition": [
    {
      "condition": {
        "condition_type": "Gender",
        "gender": "M" 
      },
      "transition": "Male_Patient"
    },
    {
      "condition": {
        "condition_type": "Gender",
        "gender": "F" 
      },
      "transition": "Female_Patient"
    },
    {
      "transition": "Unknown_Gender"
    }
  ]
}
```

--------------------------------

### Clone and Build Synthea with Gradle

Source: https://github.com/synthetichealth/synthea/wiki/Dev-Days

Clones the Synthea repository, changes into the synthea directory, and runs the Gradle test task to build and test the project. Estimated to take 5-10 minutes.

```bash
git clone https://github.com/synthetichealth/synthea.git
cd synthea
./gradlew test
```

--------------------------------

### FHIR output example for UK patient

Source: https://github.com/synthetichealth/synthea/wiki/Other-Areas

Example of the FHIR address output for a generated patient, showing UK postal code and country. The output is abridged.

```json
...abridged...
        "address": [
          {
            "extension": [
              {
                "url": "http://hl7.org/fhir/StructureDefinition/geolocation",
                "extension": [
                  {
                    "url": "latitude",
                    "valueDecimal": -2.7546
                  },
                  {
                    "url": "longitude",
                    "valueDecimal": 52.7083
                  }
                ]
              }
            ],
            "line": [
              "560 Corkery Annex Suite 36"
            ],
            "city": "Shrewsbury",
            "state": "West Midlands",
            "postalCode": "SY1",
            "country": "UK"
          }
        ],
...abridged...
```

--------------------------------

### ConditionOnset state example with target_encounter and assign_to_attribute

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Defines a ConditionOnset state that assigns the condition to the 'appendicitis' attribute and targets the 'ED_Visit' encounter for diagnosis. The codes array uses a SNOMED-CT code with system, code, and display fields.

```json
"Appendicitis": {
  "type": "ConditionOnset",
  "target_encounter": "ED_Visit",
  "assign_to_attribute": "appendicitis",
  "codes": [
    {
    "system": "SNOMED-CT",
    "code": "47693006",
    "display": "Rupture of appendix"
    }
  ]
}
```

--------------------------------

### SupplyList state example with gloves and gown

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Defines a SupplyList state that must occur during an Encounter. It specifies two supplies: 2 gloves (SNOMED 52291003) and 1 examination gown (SNOMED 788177008), each with a quantity and a SNOMED-CT code.

```json
"Necessary_Supplies": {
  "type": "SupplyList",
  "supplies": [
    {
      "quantity": 2,
      "code": {
        "system": "SNOMED-CT",
        "code": "52291003",
        "display": "Glove, device (physical object)"
      }
    },
    {
      "quantity": 1,
      "code": {
        "system": "SNOMED-CT",
        "code": "788177008",
        "display": "Examination gown, single-use (physical object)"
      }
    }
  ]
}
```

--------------------------------

### SNOMED-CT Code Example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Basics

Example of a SNOMED-CT code used in Encounter, Procedure, ConditionOnset, and CarePlanStart states. Valid codes can be found in the IHTSDO SNOMED CT Browser.

```json
{
  "system": "SNOMED-CT",
  "code": "44054006",
  "display": "Diabetes"
}
```

--------------------------------

### Clone and build Synthea with Gradle

Source: https://github.com/synthetichealth/synthea/wiki/Developer-Setup-and-Running

Clones the Synthea repository and runs the Gradle build, check, and test tasks. On Windows, use .\gradlew.bat instead of ./gradlew.

```bash
git clone https://github.com/synthetichealth/synthea.git
cd synthea
./gradlew build check test
```

--------------------------------

### Device state example for an artificial heart

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Defines a Device state for an implantable artificial heart. The state must occur during an Encounter. The code uses SNOMED-CT code 13459008. The manufacturer and model are optional but provided here.

```json
"Artificial_Heart": {
  "type": "Device",
  "code": {
    "system": "SNOMED-CT",
    "code": "13459008",
    "display": "Temporary artificial heart prosthesis, device (physical object)"
  },
  "manufacturer": "SynCardia",
  "model": "Total Artificial Heart"
}
```

--------------------------------

### EncounterEnd state with discharge_disposition

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Defines an EncounterEnd state that ends the current encounter and records a discharge disposition. The discharge_disposition is optional and should use a code from the Discharge Disposition set; this example uses NUBC code 01 for routine discharge to home care or self care.

```json
"End_Encounter" : {
   "type" : "EncounterEnd",
   "discharge_disposition" : {
     "system" : "NUBC",
     "code" : "01",
     "display" : "Discharged to home care or self care (routine discharge)"
   }
 }
```

--------------------------------

### MultiObservation state for Blood Pressure

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Example of a MultiObservation state for blood pressure, embedding two sub-observations (systolic and diastolic) within a single observation. Must be used during an Encounter, after the Encounter state and before EncounterEnd. The 'observations' list contains valid Observation states excluding type and transition.

```json
    "Record_BP": {
      "type": "MultiObservation",
      "category": "vital-signs",
      "codes": [
        {
          "system": "LOINC",
          "code": "55284-4",
          "display": "Blood Pressure"
        }
      ],
      "observations": [
        {
          "category": "vital-signs",
          "vital_sign": "Systolic Blood Pressure",
          "codes": [
            {
              "system": "LOINC",
              "code": "8480-6",
              "display": "Systolic Blood Pressure"
            }
          ],
          "unit": "mmHg"
        },
        {
          "category": "vital-signs",
          "vital_sign": "Diastolic Blood Pressure",
          "codes": [
            {
              "system": "LOINC",
              "code": "8462-4",
              "display": "Diastolic Blood Pressure"
            }
          ],
          "unit": "mmHg"
        }
      ]
    }
```

--------------------------------

### Observation state example for body height

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-States

Defines an Observation state that records body height in centimeters, with a random value chosen between 40 and 60 cm. The state must be used within an Encounter, after the target Encounter state and before EncounterEnd. The codes array uses a valid LOINC code (8302-2) for Body Height.

```json
"Height_Measurement": {
  "type": "Observation",
  "unit": "cm",
  "range": {
    "low": 40,
    "high": 60
  },
  "codes": [
    {
      "system": "LOINC",
      "code": "8302-2",
      "display": "Body Height"
    }
  ]
}
```

--------------------------------

### Build the custom exporter JAR with Gradle

Source: https://github.com/synthetichealth/synthea/wiki/Custom-Exporters

Run this command in the template directory to produce the JAR file, which will be created in ./build/libs/.

```sh
./gradlew jar
```

--------------------------------

### Run physiology simulation with gradle

Source: https://github.com/synthetichealth/synthea/blob/master/config/simulations/README.md

Run a single Synthea physiology simulation with a specified configuration file. The configuration file controls the differential equation solver, step size, simulation duration, and output chart settings. Output files are written to the output/physiology directory.

```bash
./gradlew physiology --args="config/simulations/[config name].yml"
```

--------------------------------

### False condition example

Source: https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework:-Logic

Always returns false. Used for testing purposes.

```json
{
  "condition_type": "False"
}
```
Tokens:
Raw