Module Builder Tutorial

[idhamari]

I tried the module builder tutorial and I have some questions:

I tried different prevalence values, in chance of CHF state, of a person having the CHF disease, here are the results (I am checking the conditions.csv file ):

• (original from the tutorial) 0.99905 to 0.00095 I got 2 patients with CHF disease in 7.88 minutes
• 0.999 to 0.001 I got 2 patients with CHF disease in 7.92 minute
• 0.99 to 0.01 I got 10 patients with CHF disease in 7.13 minutes
• 0.90 to 0.10 I got 45 patients with CHF disease in 7.42 minutes

1. is the prevalence related to the state population? or -p argument?
2. how can I use the prevalence correctly to represent the state population and get a realistic number of patients in the output? e.g. assuming a city with 3000000 people and the disease has 1/1000 prevalence which means the output should have 3000 patients with this disease.
3. why the generation is too slow on my laptop around 7.5 minutes to generate 1000? the generate.thread_pool_size = -1
4. When using the keep module, -k, no patients were generated at all using prevalence of 0.90 to 0.10. and waiting for more than 10 minutes. I had to terminate the execution.

Here is the command I am using:

      run_synthea -s 1685524531456 -p 1000 -d ./modulesTemp 
      run_synthea -s 1685524531456 -p 1000 -d ./modulesTemp -k  ./keepModule.json 

the folder modulesTemp has only one file chf.json with this contents:

        {
          "name": "CHF",
          "remarks": [
            "My CHF module",
            ""
          ],
          "states": {
            "Initial": {
              "type": "Initial",
              "direct_transition": "age delay"
            },
            "Terminal": {
              "type": "Terminal"
            },
            "CHF Condition Start": {
              "type": "ConditionOnset",
              "target_encounter": "",
              "codes": [
                {
                  "system": "SNOMED-CT",
                  "code": 423430072,
                  "display": "CHF Disease",
                  "value_set": "aaa2"
                }
              ],
              "direct_transition": "CHF Initial Workup Encounter"
            },
            "CHF Initial Workup Encounter": {
              "type": "Encounter",
              "encounter_class": "ambulatory",
              "reason": "",
              "telemedicine_possibility": "none",
              "codes": [
                {
                  "system": "SNOMED-CT",
                  "code": 1853470012,
                  "display": "CHF Initial",
                  "value_set": "bbb2"
                }
              ],
              "direct_transition": "Terminal"
            },
            "age delay": {
              "type": "Delay",
              "distribution": {
                "kind": "EXACT",
                "parameters": {
                  "value": 50
                }
              },
              "unit": "years",
              "direct_transition": "chance of CHF"
            },
            "CHF symptom onset 1": {
              "type": "Symptom",
              "symptom": "shortness of breath",
              "cause": "Congestive Heart Failure",
              "probability": 1,
              "distribution": {
                "kind": "EXACT",
                "parameters": {
                  "value": 1
                }
              },
              "direct_transition": "CHF Condition Start"
            },
            "chance of CHF": {
              "type": "Delay",
              "distribution": {
                "kind": "EXACT",
                "parameters": {
                  "value": 1
                }
              },
              "unit": "years",
              "distributed_transition": [
                {
                  "transition": "CHF symptom onset 1",
                  "distribution": 0.01
                },
                {
                  "transition": "Terminal",
                  "distribution": 0.99
                }
              ]
            }
          },
          "gmf_version": 2
        }

/keepModule.json has this contents:

        {
            "name": "keep",
            "remarks": [
              "Module to keep patients with a specific disease"
            ],
            "states": {
              "Initial": {
                "type": "Initial",
                "conditional_transition": [
                  {
                    "transition": "Keep",
                    "condition": {
                      "condition_type": "Attribute",
                      "attribute": "Condition",
                      "operator": "==",
                      "value": "CHF Disease"
                    }
                  },
                  {
                    "transition": "Terminal"
                  }
                ]
              },
              "Terminal": {
                "type": "Terminal"
              },
              "Keep": {
                "type": "Terminal"
              }
            },
            "gmf_version": 2
          }

[idhamari]

@jawalonoski

I appreciate your input on the above questions.

[jawalonoski]

1. is the prevalence related to the state population? or -p argument?

Prevalence is related to the number of patients simulated: -p or generate.default_population

2. how can I use the prevalence correctly to represent the state population and get a realistic number of patients in the output? e.g. assuming a city with 3000000 people and the disease has 1/1000 prevalence which means the output should have 3000 patients with this disease.

There are a number of options.

• Set the prevalence to 0.001 and -p 3000000 and you'll have 3000000 living patients, and approximately 3000 of which will have the disease.
• Set the prevalence to 1 and -p 3000 and you'll have 3000 living patients, all of them with the disease.
• Set the prevalence to anything great than zero, and -p 3000, and use a keep module. You may end up with 3000 patients with the disease, it may time out.

I haven't looked at your keep module yet, so I won't address that in this post.

[jawalonoski]

The keep module is looking for an attribute (or variable) on the patient named Condition and it needs to be equal to CHF Disease.

Does your module create an attribute named Condition? No, it does not. Therefore the Keep state is never reached.

In your CHF module, one option is to edit the "CHF Condition Start" state and click "Add Assign to Attribute" and then assign it to an attribute (in your example, Condition, but personally I wouldn't use such a generic name because it might clash with attributes that other module authors might use). If you do this, then the keep module still won't work, because your "Condition" attribute was assigned to be a Condition object (the diagnosis with SNOMED 423430072), not the string "CHF Disease". You could get the Keep module to work by changing the conditional to be something like Condition is not nil.

You could also alternatively do something like this:

{
  "name": "keep",
  "remarks": [
    "Module to keep patients with a specific disease"
  ],
  "states": {
    "Initial": {
      "type": "Initial",
      "conditional_transition": [
        {
          "transition": "Keep",
          "condition": {
            "condition_type": "Active Condition",
            "codes": [
              {
                "system": "SNOMED-CT",
                "code": 423430072,
                "display": "CHF Disease"
              }
            ]
          }
        },
        {
          "transition": "Terminal"
        }
      ]
    },
    "Terminal": {
      "type": "Terminal"
    },
    "Keep": {
      "type": "Terminal"
    }
  },
  "gmf_version": 2
}

Finally, the tutorial was last updated in 2019, so it may be slightly out of date. One thing that you need to correct in your CHF module, is that you should make sure you have an EncounterEnd state, otherwise the patient never leaves. Another thing is that when you create a Condition BEFORE an Encounter, you MUST set the "Add Target Encounter" field so that the display "Diagnose at XYZ Encounter" shows up (where "XYZ" is the name of your Encounter state).

{
  "name": "CHF",
  "remarks": [
    "My CHF module",
    ""
  ],
  "states": {
    "Initial": {
      "type": "Initial",
      "direct_transition": "age delay"
    },
    "Terminal": {
      "type": "Terminal"
    },
    "CHF Condition Start": {
      "type": "ConditionOnset",
      "codes": [
        {
          "system": "SNOMED-CT",
          "code": 423430072,
          "display": "CHF Disease",
          "value_set": "aaa2"
        }
      ],
      "direct_transition": "CHF Initial Workup Encounter",
      "target_encounter": "CHF Initial Workup Encounter"
    },
    "CHF Initial Workup Encounter": {
      "type": "Encounter",
      "encounter_class": "ambulatory",
      "reason": "",
      "telemedicine_possibility": "none",
      "codes": [
        {
          "system": "SNOMED-CT",
          "code": 1853470012,
          "display": "CHF Initial",
          "value_set": "bbb2"
        }
      ],
      "direct_transition": "End Initial Workup"
    },
    "age delay": {
      "type": "Delay",
      "distribution": {
        "kind": "EXACT",
        "parameters": {
          "value": 50
        }
      },
      "unit": "years",
      "direct_transition": "chance of CHF"
    },
    "CHF symptom onset 1": {
      "type": "Symptom",
      "symptom": "shortness of breath",
      "cause": "Congestive Heart Failure",
      "probability": 1,
      "distribution": {
        "kind": "EXACT",
        "parameters": {
          "value": 1
        }
      },
      "direct_transition": "CHF Condition Start"
    },
    "chance of CHF": {
      "type": "Delay",
      "distribution": {
        "kind": "EXACT",
        "parameters": {
          "value": 1
        }
      },
      "unit": "years",
      "distributed_transition": [
        {
          "transition": "CHF symptom onset 1",
          "distribution": 0.01
        },
        {
          "transition": "Terminal",
          "distribution": 0.99
        }
      ]
    },
    "End Initial Workup": {
      "type": "EncounterEnd",
      "direct_transition": "Terminal"
    }
  },
  "gmf_version": 2
}

[idhamari]

Thanks for your detailed answer.

how can I use the prevalence correctly to represent the state population and get a realistic number of patients in the output? e.g. assuming a city with 3000000 people and the disease has 1/1000 prevalence which means the output should have 3000 patients with this disease.
There are a number of options.
Set the prevalence to 0.001 and -p 3000000 and you'll have 3000000 living patients, and approximately 3000 of which will have the disease.
Set the prevalence to 1 and -p 3000 and you'll have 3000 living patients, all of them with the disease.
Set the prevalence to anything great than zero, and -p 3000, and use a keep module. You may end up with 3000 patients with the disease, it may time out.

I used 1 in the prevalence to get the complete population as patients but I am getting fewer numbers than expected.

Another question, how can I get a specific ratio of male and female e.g. if I have 100 population and all of them patients, I want 90 patients male and 10 patients female?

I tried the answer here but it seems to filter out from the actual population e.g. after generating a random population let's say 100 people, synthea assigns gender and race attributes to them randomly

Here is the updated module:

        {
          "name": "CHF",
          "remarks": [
            "My CHF module",
            ""
          ],
          "states": {
            "Initial": {
              "type": "Initial",
              "direct_transition": "age delay"
            },
            "Terminal": {
              "type": "Terminal"
            },
            "CHF Condition Start": {
              "type": "ConditionOnset",
              "codes": [
                {
                  "system": "SNOMED-CT",
                  "code": 423430072001,
                  "display": "CHF Disease",
                  "value_set": "aaa2"
                }
              ],
              "direct_transition": "CHF Initial Workup Encounter",
              "target_encounter": "CHF Initial Workup Encounter"
            },
            "CHF Initial Workup Encounter": {
              "type": "Encounter",
              "encounter_class": "ambulatory",
              "reason": "",
              "telemedicine_possibility": "none",
              "codes": [
                {
                  "system": "SNOMED-CT",
                  "code": 1853470012001,
                  "display": "CHF Initial",
                  "value_set": "bbb2"
                }
              ],
              "direct_transition": "End Initial Workup"
            },
            "age delay": {
              "type": "Delay",
              "distribution": {
                "kind": "EXACT",
                "parameters": {
                  "value": 50
                }
              },
              "unit": "years",
              "direct_transition": "chance of CHF"
            },
            "CHF symptom onset 1": {
              "type": "Symptom",
              "symptom": "shortness of breath",
              "cause": "Congestive Heart Failure",
              "probability": 1,
              "distribution": {
                "kind": "EXACT",
                "parameters": {
                  "value": 1
                }
              },
              "direct_transition": "CHF Condition Start"
            },
            "chance of CHF": {
              "type": "Delay",
              "distribution": {
                "kind": "EXACT",
                "parameters": {
                  "value": 1
                }
              },
              "unit": "years",
              "distributed_transition": [
                {
                  "transition": "Race",
                  "distribution": 1
                },
                {
                  "transition": "Terminal",
                  "distribution": 0
                }
              ]
            },
            "End Initial Workup": {
              "type": "EncounterEnd",
              "direct_transition": "Terminal"
            },
            "Race": {
              "type": "Simple",
              "complex_transition": [
                {
                  "condition": {
                    "condition_type": "Race",
                    "race": "White"
                  },
                  "distributions": [
                    {
                      "distribution": 0.3,
                      "transition": "Gender"
                    },
                    {
                      "transition": "Terminal",
                      "distribution": 0.7
                    }
                  ]
                },
                {
                  "condition": {
                    "condition_type": "Race",
                    "race": "Black"
                  },
                  "distributions": [
                    {
                      "distribution": 0.6,
                      "transition": "Gender"
                    },
                    {
                      "transition": "Terminal",
                      "distribution": 0.4
                    }
                  ]
                },
                {
                  "condition": {
                    "condition_type": "Race",
                    "race": "Other"
                  },
                  "distributions": [
                    {
                      "transition": "Gender",
                      "distribution": 0.1
                    },
                    {
                      "transition": "Terminal",
                      "distribution": 0.9
                    }
                  ]
                }
              ]
            },
            "Gender": {
              "type": "Simple",
              "complex_transition": [
                {
                  "condition": {
                    "condition_type": "Gender",
                    "gender": "F"
                  },
                  "distributions": [
                    {
                      "distribution": 0.1,
                      "transition": "CHF symptom onset 1"
                    },
                    {
                      "transition": "Terminal",
                      "distribution": 0.9
                    }
                  ]
                },
                {
                  "condition": {
                    "condition_type": "Gender",
                    "gender": "M"
                  },
                  "distributions": [
                    {
                      "transition": "CHF symptom onset 1",
                      "distribution": 0.9
                    },
                    {
                      "transition": "Terminal",
                      "distribution": 0.1
                    }
                  ]
                }
              ],
              "remarks": [
                "test gender ratio",
                ""
              ]
            }
          },
          "gmf_version": 2
        }

[jawalonoski]

I used 1 in the prevalence to get the complete population as patients but I am getting fewer numbers than expected.
Another question, how can I get a specific ratio of male and female e.g. if I have 100 population and all of them patients, I want 90 patients male and 10 patients female?

As I said in the other thread, "The modules don't define demographics of patients... the demographics are determined by census data."

The module you have is doing this:

• Initial State
  • The number of patients starting here is determined by -p
  • The demographics of all of these patients (birth date, race, and gender) is determined by census data.
    • Alternatively, you could use -g for gender and -a for ages. There is no parameter to control race, you have to edit the demographics files.
• Wait 50 years
  • At this point all patients are 50 years old... or they are STUCK in this state until they are 50 years old.
  • If demographics decided to generate a 30 year old, they will NEVER leave this state when the simulation ends.
• Wait another 1 year
  • At this point, patients who made it this far are 51 years old.
• Filter out people by race
  • Remove 70% of white, 40% of black, 90% of other
• Filter out people by gender
  • Remove 90% of females, 10% of males
• Everything else (symptom, condition, encounter, encounter end)

If you generated 100 patients under the age of 50, none of them will have CHF.

If you generated 100 (e.g.,-p 100) white (you can't control this unless you edit the demographics files) female (e.g.,-g F) patients over 51 (e.g.,-a 51-52), then you'd only see 3 patients with CHF (on average, i.e., 100 * 0.3 * 0.1 = 3).

I tried the answer here but it seems to filter out from the actual population e.g. after generating a random population let's say 100 people, synthea assigns gender and race attributes to them randomly

Yes. As I said in the other thread, "The modules don't define demographics of patients... the demographics are determined by census data."

The module just applies its logic (conditional and/or probability) of patients moving from one state to another based on their preexisting demographics.

[idhamari]

Thanks for the detailed answer, it is clear now.