Skip to content

Frequently Asked Questions

Jump to bottom Edit New page
Dylan Hall edited this page Sep 28, 2023 · 9 revisions

Table of Contents

(Note to wiki editors: use https://github.com/jonschlinkert/markdown-toc for updating this ToC if you add/change several items)

Does Synthea have data about ___ ?

Synthea includes data representing the progression and treatment of the most common diseases and conditions, but by no means does Synthea include every known disease.

Synthea currently has over 90 different modules which have expanded beyond the original "Two Top Tens" that the project started with (see the table below).

Top 10 Reasons Patients Visit PCP Top 10 Years of Life Lost
Routine infant/child health check Ischemic Heart Disease
Essential Hypertension Lung Cancer
Diabetes Mellitus Alzheimer’s Disease
Normal Pregnancy COPD
Respiratory Infections (Pharyngitis, Bronchitis, Sinusitis) Cerebrovascular Disease
General Adult Medical Examination Road Injuries
Disorders of Lipoid Metabolism Self-Harm
Ear Infections (Otitis Media) Diabetes Mellitus
Asthma Colorectal Cancer
Urinary Tract Infections Drug Use Disorders (limited to Opioids)

The best place to start is by reviewing the modules available in the Module Builder: https://synthetichealth.github.io/module-builder/

Alternatively, you can run the concepts gradle task to create a CSV file at ./src/concepts.csv with all the concepts (codes from SNOMED, LOINC, RxNorm, etc) that Synthea can use to populate records:

$ ./gradlew concepts
Starting a Gradle Daemon (subsequent builds will be faster)

> Task :concepts
Performing an inventory of concepts...
Scanned 76 modules and 90 submodules.
Catalogued 1412 concepts in file `./output/concepts.csv`.
Done.

BUILD SUCCESSFUL in 8s

Note that this requires the Developer setup of Synthea - see Developer Setup and Running for setup instructions. On Windows run gradlew.bat concepts instead.

Does Synthea have data in format ___ ?

Synthea by default supports the following formats:

If your format of interest is not already included, you have a few options:

  1. Convert data from one of the other formats.
    • If the concept of "translation from one format to another" is relevant to your use case, you may want to start with one of the industry standard formats: FHIR, CCDA, etc
    • Otherwise, the CSV and JSON formats are Synthea-specific and intended to be broadly applicable to most use cases. The JSON export in particular includes additional pieces of data used in the simulation which are not exported in other formats. industry standard formats (FHIR, CCDA, etc).
  2. Fork the repository and add your own exporter class.
  3. New: write your exporter as a standalone project with the appropriate structure, and create a JAR to use with Synthea. See Custom Exporters for more information.

Does Synthea have data for region ___ ?

Synthea by default includes demographic data for the entire USA, and if not otherwise specified will generate synthetic patients within the state of Massachusetts.

The Synthea-International repository contains metadata and configuration files for international locations, and instructions on how to apply them to a developer instance of synthea. Currently this contains primarily European countries but we welcome community efforts to add support for any country.

Instructions for creating your own data files to support other regions are on the Other Areas page and its subpages.

How can I generate data for the entire US?

Synthea only supports generating data for one US state at a time.

You can specify a different state and/or city on the command line (see Basic Setup and Running). You can also replace the demographics (see Other Areas, Demographics for Other Areas, and related wiki articles).

If you want to run multiple states, we recommend that users write a script that simply executes Synthea multiple times for each state desired. For example, generating a population at 1/1000 scale of the entire US:

./run_synthea -p 5024 Alabama
./run_synthea -p 733 Alaska
./run_synthea -p 7151 Arizona
./run_synthea -p 3011 Arkansas
...

How do I use Synthea to produce data for my FHIR Implementation Guide?

There is no automated way to "load an IG" into Synthea such that exported data will automatically conform to it. (Barring significant advances in knowledge representation or AI, we don't expect there ever will be. See notes below in Why can't data be automatically generated for any given IG? )

There are a few possible approaches to building data for arbitrary IGs with Synthea:

  1. Modify the Java code of the Synthea engine and FHIR Exporter to support the needs of the IG of interest.
  2. Post-process data generated by data using other tools.
  3. Use the "Flexible Exporter" aka Flexporter. This experimental feature is designed to allow users to define transformations that are applied to Synthea data. This is meant to support a number of use cases but making the data conform to an IG of interest is one of the most important. The Flexporter is most useful when the data is very close to what is needed, for example maybe only a couple of fields are missing or a new resource type needs to be added. See the Flexporter page for more details.

Note that the relevance of the data to the IG is also important to consider. For example, an IG with a clinical focus on a disease not already included in Synthea will also require an additional module to produce relevant data in the first place.

Why can't data be automatically generated for any given IG?

There is no automated way to "load an IG" into Synthea such that exported data will automatically conform to it. Creating data that is structurally conformant any given IG is fairly straightforward, but creating data that is relevant, meaningful, and realistic is nearly impossible.

Consider a profile that makes a field required that is not already exported by Synthea, for example Procedure.complication.

  • Should this profile be applied to all instances of the Procedure resource or just some?
  • What value should be put into the field? In this case this field is a CodeableConcept and the profile may define a value set binding, but there's no way to know which values would make the resource and overall record look realistic, and which values would be irrelevant or contradictory. This is even more difficult for other data types such as numbers, dates, or strings.

For these reasons, we decided the Flexporter concept would require a human to create the mapping. Going forward we hope to improve both the user-friendliness and power of the tool to make it easier for people to generate data for their IG.

How do I get only data for a certain condition of interest?

There are three basic approaches to getting data focused on a single condition (or other criteria) of interest:

  1. Use a Keep Module
    • A Keep Module is a specialized type of Synthea module, used to filter patients out of the simulation. ("Only keep patients matching these criteria.") Keep Modules are constructed using the module builder, which allows for arbitrarily complex logic. Eg. "Keep patients with an active condition of diabetes", "keep patients with an observed HbA1c > 6.5", "Keep patients with one of the following 3 allergies", etc...
  2. Post-process the data to filter to only data of interest
    • Synthea does not provide a built-in filtering capability, but using other scripting languages such as Python make it easy to read in patient data and filter (or otherwise post-process) the data however you like
  3. Only run the module of interest.
    • Do not do this. We mention this option only to point out that we strongly recommend against it for many reasons.
Add a custom footer

Clone this wiki locally