Physiology Models

[awatson1978]

Rebuild of PR #1254

Synthea Physiology Simulations

The simulation configuration files in this directory can be used to execute a single run of a Synthea physiology model via the gradle command line interface. The configuration allows manipulation of the differential equation solver, step size, sim duration, and configuration for output charts if desired. Output files will be in the output/physiology directory.

Note that these are only utilized for the physiology gradle command and are not part of the normal Synthea execution procedure.

Configuration

You will need to set the following two fields to true in the src/main/resources/synthea.properties file.

# Use physiology simulations to generate some VitalSigns
physiology.generators.enabled = true

# Allow physiology module states to be executed
# If false, all Physiology state objects will immediately redirect to the state defined in
# the alt_direct_transition field
physiology.state.enabled = true

Usage

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

Examples

  ./gradlew physiology --args="config/simulations/circadian_clock.yml"
  ./gradlew physiology --args="config/simulations/ecg.yml"
  ./gradlew physiology --args="config/simulations/insulin_signalling_diabetic.yml"
  ./gradlew physiology --args="config/simulations/insulin_signalling_normal.yml"
  ./gradlew physiology --args="config/simulations/liver_metabolism.yml"
  ./gradlew physiology --args="config/simulations/mammalian_circadian_rhythm_non_24hr.yml"
  ./gradlew physiology --args="config/simulations/menstrual_cycle.yml"
  ./gradlew physiology --args="config/simulations/o2_transport_metabolism.yml"
  ./gradlew physiology --args="config/simulations/plasma_melatonin.yml"  
  ./gradlew physiology --args="config/simulations/pulmonary_fluid_dynamics.yml"
  ./gradlew physiology --args="config/simulations/pulmonary_oxygen_intake.yml"
  ./gradlew physiology --args="config/simulations/telomere_associated_dna_damage.yml"
  ./gradlew physiology --args="config/simulations/weight_change.yml"

Output

Graphs and raw data in CVS files will be found in output/physiology folder.

You may also wish to create a large population of 10,000 or more individuals, and search for gallblader patients (which are currently the only patients that have ECG physiology data attached to them.)

# generate the sample patients
run_synthea -p 10000

# then search for gallbladder conditions with any of the following terms:
  - Media
  - 29303009 
  - Electrocardiogram
  - valueSampledData

References

• Smith2004_CVS_human
• Guyton1972_PulmonaryOxygenIntake
• Guyton1972_PulmonaryFluidDynamics
• Lai2007_O2_Transport_Metabolism
• Brännmark2013 - Insulin signalling in human adipocytes (normal condition)
• Brännmark2013 - Insulin signalling in human adipocytes (diabetic condition)
• Talemi2015 - Persistent telomere-associated DNA damage foci (TAF)
• ChowHall2008 Dynamics of Human Weight Change_ODE_1
• Hong2009_CircadianClock
• Brown1997 - Plasma Melatonin Levels
• Leloup2004 - Mammalian Circadian Rhythm models for 23.8 and 24.2 hours
• Roblitz2013 - Menstrual Cycle following GnRH analogue administration
• Kyrylov2005_HPAaxis
• Jerby2010_Liver_Metabolism

[sonatype-lift]

Sonatype Lift is retiring

Sonatype Lift will be retiring on Sep 12, 2023, with its analysis stopping on Aug 12, 2023. We understand that this news may come as a disappointment, and Sonatype is committed to helping you transition off it seamlessly. If you’d like to retain your data, please export your issues from the web console.
We are extremely grateful and thank you for your support over the years.

📖 Read about the impacts and timeline

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (85673df) 76% compared to head (9f613e0) 77%.
Report is 17 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##             master   #1347    +/-   ##
=========================================
  Coverage        76%     77%            
- Complexity     3850    4095   +245     
=========================================
  Files           178     178            
  Lines         24997   25473   +476     
  Branches       3535    3700   +165     
=========================================
+ Hits          19136   19693   +557     
+ Misses         4735    4674    -61     
+ Partials       1126    1106    -20     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[dehall]

The details of the new simulations and models are a little bit over my head so I can't comment too much on those. In general they look fine to me. The 4 new modules though, I'm not super clear on the intent of those and I think that needs to be clear before we decide where to go with this. 3 of the 4 new modules are named "wearables" but wearable devices are only a piece of what's in the module. All of them assign a new Condition to an individual which I see is meant to be the reason an individual uses a wearable but I would want to see more detail in the subsequent clinical progression of the modules. Are they intended to be top-level modules? (ie, are these meant to be run for the entire population?)

[dehall]

I recognize you're in a tricky spot here since most of the "physiology" features are not available in the module builder, but I would strongly encourage using the module builder as much as possible anyway, rather than handcrafting things. Trying to view this state actually crashes the builder since Symptom states don't have codes.

[awatson1978]

Hrmmm. There were a few non-terminated paths in earlier versions of the modules (~July), although all of the new modules currently compile in the Module Builder for me. I'm not able to replicate the builder crash based on the codes field. :/

[awatson1978]

Removed codes field from Symptom states.

[dehall]

Hm ok a couple things here. Looking closer at it now, I may have been wrong about the root cause (codes shouldn't break anything but they don't do anything either), but the state still doesn't load in the module builder. The module overall does load, but when you click on the Menstrual_Cramps_Symptom state to view/edit it in the sidebar, the app crashes to a white page. Synthea proper is also going to crash here if it reaches this state so please make sure the unit tests run and try running synthea separately to make sure nothing breaks and the output results look reasonable

[awatson1978]

I overhauled the entire module, and it's now simply an Endometriosis module. I went through and rebuilt most all of the states, using the editor. Turns out the Symptom didn't have a probability %, which was what was causing it to crash. Encounters and Conditions end gracefully. No crashes, recently. Unit tests running good.

[jawalonoski]

The wearables sleep apnea module needs a good scrubbing.

In the image below, you can see a few potential issues:

• The Wellness_Baseline_Encounter is an emergency encounter, which might be fine, but then it probably isn't a "wellness" encounter. And if it is, then maybe click "Add Wellness".
• The Wellness_Baseline_Encounter transitions directly to the SleepStudy_Baseline_Encounter. The module engine will halt at this point, because it is impossible for there to be two simultaneous encounters. The first encounter shall end before the second one begins.
• The SleepStudy_Baseline_Encounter is an emergency encounter, which also seems incorrect.

The Sleep_Apnea_Resolved state is not correct. You can tell, because if you click on it, the module builder does not actually reference a condition. Click "Add Condition Onset" (or "Add Codes") if you prefer.

Similarly, some of the Observation states may be incomplete and could export into invalid FHIR. They have no units of measure, and they have no values, for instance SleepAnaysis state outputs Sleep duration.

[dehall]

Ok I think this is really close but still a few things that should be cleaned up before we merge. I recognize these new modules are meant to be quick demos that get the physiology content into records, rather than comprehensive modules of the conditions in question, but since they'll be part of every synthea population going forward I do want to make sure what these new modules create is as good as we can make it.

[dehall]

This state is going to be hit immediately after birth so the range here doesn't match the name of the state. Maybe call it Age_13-19 ?

[dehall]

The symptoms that get added in this sequence are immediately ended right after, so they don't really do anything. Then the ConditionEnds after that aren't going to work because they point to a Guard instead of a ConditionOnset. I'd suggest just having this whole branch (the "80%" after the guard) go directly to Terminal

[awatson1978]

Wearables ECG Module (wearables_cardiac_monitoring.json)

✅ Fixed Critical Issues:
Renamed module to "Wearables_Cardiac_Monitoring" for clarity
Updated adoption rate from 20% to 30% based on 2024 statistics
Simplified population model - removed complex 9-age-group stratification
Fixed encounter classes - changed from "emergency" to "ambulatory"
Updated documentation with current research citations
Streamlined age targeting to 18-65 years (prime wearable adoption demographic)

Sleep Apnea Module (wearables_sleepapnea.json)

✅ Fixed Critical Logic Error:

Removed problematic Guard condition that prevented sleep apnea onset modeling
Added proper condition onset flow with Sleep_Apnea_Risk_Assessment → Sleep_Apnea_Onset
Added missing probability fields to symptom states
Fixed encounter classes from "emergency" to "ambulatory"
Added age-based risk stratification (≥30 years, 5% risk)

✅ Key Improvements Made:

Runtime Stability - All modules now execute without crashes
Clinical Accuracy - Updated statistics reflect 2024 research
Proper Medical Coding - Fixed medication and encounter coding issues
Realistic Population Modeling - Simplified and updated adoption rates
Logical Flow - Fixed state transition logic throughout

[awatson1978]

Wearables - Cardiac Monitoring

Wearables - Sleep Apnea

Endometriosis

[awatson1978]

Take a look at the updated changes?
@jawalonoski @hadleynet

[jawalonoski]

Take a look at the updated changes? @jawalonoski @hadleynet

Added to my backlog...