Skip to content

Custom Exporters

Jump to bottom Edit New page
Dylan Hall edited this page Sep 18, 2023 · 1 revision

If you require a data format that Synthea doesn't support natively, you have the following options:

1a. Convert data from one of the other industry standard formats (FHIR, CCDA, etc).
1b. Convert data from one of the Synthea-specific formats (CSV, JSON).
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.

This page documents option 3 - writing your own exporter. The main benefit to this option over option 2 above is that you don't have to maintain a fork of Synthea, you can always use the most recent official version. Note this does still require you to write Java code (or at least, code compatible with a JVM - using Kotlin or Scala should also be possible but may require some extra configuration)

Overview

Synthea supports two types of custom exporters: Patient exporters, and Post-completion exporters. A Patient exporter gets called once for each simulated Patient, and a Post-completion exporter only gets called once after the entire simulation has completed.

A Patient exporter is a class that implements the org.mitre.synthea.export.PatientExporter interface with the method:

public void export(Person person, long stopTime, ExporterRuntimeOptions options)

A Post-completion exporter is a class that implements the org.mitre.synthea.export.PostCompletionExporter interface with the method:

public void export(Generator generator, ExporterRuntimeOptions options)

Note that the post-completion exporter is not passed any Patient records directly. Most cases where you want to run a post-completion exporter will also require a Patient exporter.

Quick Start

The easiest method is to use the Custom Exporter Template and follow the directions in the README. Those instructions are copied here:

Setup and Creating a JAR file

This template contains the following files which may be altered for your needs:

  • build.gradle: If you require any software libraries not already included in Synthea, they can be added here. See the notes in this file for the proper way of adding libraries.

  • settings.gradle: Change the name "custom-exporter-template" to whatever you like, this will only affect the name of the final JAR file.

  • src/main/java/org/mitre/synthea/exporters/

    • SamplePatientExporter.java: This file contains the implementation of a Patient exporter, which is called for every Patient in a run of Synthea.
    • SamplePostCompletionExporter.java: This file contains the implementation of a post-completion exporter, which is called once at the end of a run of Synthea. Note that the method in this class does not receive the Patient instances.
    • These two files are the primary entry point and this is where you should add your code, or call another library.
    • These two files may both be moved around and renamed freely. If you do, make sure to update the references to them in the files below. If you only need one of the two types of exporter, you may delete this file and its corresponding service file below.

  • src/main/resources/META-INF/services/

    • org.mitre.synthea.export.PatientExporter: This file points to the location of all classes that implement the PatientExporter interface. If you create multiple classes that implement this interface, make sure to add them here.
    • org.mitre.synthea.export.PostCompletionExporter: This file points to the location of all classes that implement the PostCompletionExporter interface. If you create multiple classes that implement this interface, make sure to add them here.

Once your code is ready, run the following command to produce the jar file:

./gradlew jar

The jar file will be created in ./build/libs/.

Usage

For the basics of running Synthea, please refer to Basic Setup and Running or Developer Setup and Running on the Synthea wiki.

If you are using the "Basic Setup" of Synthea, add your .jar file to the classpath and run Synthea as follows:

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

Other options may be appended to the end of the command as usual.

If you are using the "Developer Setup" of Synthea, add your .jar to its ./lib/custom/ directory, and run synthea with ./run_synthea, with other options appended to the end of the command as usual.

A toy example of using the template to write patients to a Postgres database is available at: https://github.com/dehall/example-exporter-postgres

Details

The Custom Exporter logic uses the Java ServiceLoader to load in JARs containing classes that implement our interfaces. The implementation is fairly simple, all you need is:

  • Class(es) implementing the interface of interest
  • A service locator file, located in the jar at META-INF/services/{fully-qualified interface name}, containing the fully-qualified class name of the implementing class(es), one per line
Add a custom footer
Clone this wiki locally