Medication Diversification Tool (MDT)

Background

In its current state, the process for generating medications in Synthea is manual and limited to a small selection of medications in individual modules. Some modules utilize medication submodules, but even these are hardcoded into the submodule. The open-source Medication Diversification Tool (MDT) (created by CodeRx) leverages publicly-available, government-maintained datasets to enhance Synthea’s Synthetic Patient Generator. The goal for the MDT is to create more diverse synthetic patient medication orders that accurately reflects the heterogeneity of medications being prescribed in the US population.

The MDT automates the process for finding relevant medication codes and calculating a distribution of medications, using medication classification dictionaries from RxClass / RxNorm and population-level prescription data from the Medical Expenditure Panel Survey (MEPS). The medication distributions can be tailored to specific patient demographics (e.g., age, gender, state of residence) and combined with Synthea data to generate medication records for a sample patient population.

Example diagram: Current state versus potential output of the Medication Diversification Tool (MDT) for a hypothyroidism use case.

Complete documentation

For complete documentation on how to use MDT (including examples), please go to our GitHub repo: https://github.com/coderxio/medication-diversification

For a tip sheet on creating and integrating your first MDT submodule, please go to our website: https://coderx.io/projects/medication-diversification#tip-sheet

MDT output

The main output of MDT is:

1. A <module_name>>.json file which is the Synthea submodule itself
2. A lookup_tables/ directory with all transition table CSVs
3. A log/ directory with helpful output logs and debugging CSVs

How to replace a MedicationOrder with a MDT submodule

To replace a MedicationOrder with one of our MDT submodules, replace the MedicationOrder state with a CallSubmodule state.

"Medication_Submodule": {
  "type": "CallSubmodule",
  "submodule": "medications/<<name_of_your_mdt_submodule_here_without_json_file_extension>>"
}

Put the submodule JSON file in the synthea/src/main/resources/modules/medications folder.

Put your transition table CSV files in the synthea/src/main/resources/modules/lookup_tables folder.

Example for asthma module:

Using the existing asthma module as an example...

Change this...

...
    "Prescribe_Maintenance_Inhaler": {
      "type": "MedicationOrder",
      "reason": "asthma_condition",
      "codes": [
        {
          "system": "RxNorm",
          "code": "895994",
          "display": "120 ACTUAT Fluticasone propionate 0.044 MG/ACTUAT Metered Dose Inhaler"
        }
      ],
      "prescription": {
        "as_needed": true
      },
      "direct_transition": "Prescribe_Emergency_Inhaler",
      "chronic": true
    },
...

To this...

...
    "Prescribe_Maintenance_Inhaler": {
      "type": "CallSubmodule",
      "submodule": "medications/maintenance_inhaler",
      "direct_transition": "Prescribe_Emergency_Inhaler"
    },
...

And make sure your submodule JSON and transition table CSVs are in the folder locations specified above.

Put a maintenance_inhaler.json file in the synthea/src/main/resources/modules/medication folder. Put all the transition table CSV files in the synthea/src/main/resources/modules/lookup_tables folder. See below for example file structure:

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
|  │  │  │  ├─ ...

Lastly, if the calling module (in this case, asthma.json) ends medications by a specific State_Name of a previous MedicationOrder state, you will need to change that MedicationEnd state to instead end a medication by attribute. The reason for this is that our MDT JSON module generates different MedicationOrder state names for each potential prescribed product, but they all have the same attribute.

Change this...

...
    "Maintenance_Medication_End": {
      "type": "MedicationEnd",
      "medication_order": "Prescribe_Maintenance_Inhaler",
      "direct_transition": "Emergency_Medication_End"
    },
...

To this...

...
    "Maintenance_Medication_End": {
      "type": "MedicationEnd",
      "referenced_by_attribute": "maintenance_inhaler",
      "direct_transition": "Emergency_Medication_End"
    },
...