README
¶
Simulated Hospital
Simulated Hospital is a tool that generates realistic and configurable hospital patient data in HL7v2 format.
Disclaimer: This is not an officially supported Google product.
Overview
A hospital's Electronic Health Record (EHR) system contains patients' health information. EHRs use messages to communicate clinical actions like the admission of a patient, ordering a blood test, or getting test results. This flow of messages describes the lifetime of a patient's stay in a hospital.
Most EHRs use a message format called HL7v2, which is ugly and tedious to type. Simulated Hospital generates messages in HL7v2 format from sequences of clinical actions. The generated HL7v2 messages can be sent to an MLLP host, saved to a txt file, or printed to the console.
Simulated Hospital helps developers build and test clinical apps without access to real data. It makes it easy to generate HL7v2 messages that reproduce realistic situations in clinical settings.
Basic Concepts
The basic behavior of Simulated Hospital can be summarized as follows:
- Simulated Hospital creates patients at a configurable rate.
- When Simulated Hospital creates a patient, it associates the patient with a pathway.
- A pathway models the events that will occur to the patient.
- Simulated Hospital runs events when they are due, in real time.
- When events run, they generate HL7v2 messages.
Pathways
A pathway is a sequence of clinical actions or events that describe the lifetime of a patient's stay in a hospital. An example of a simple pathway could be: the patient is admitted, a doctor orders an X-ray, the X-ray is taken, and the patient is discharged. Each action typically generates one or more HL7v2 messages.
Simulated Hospital runs pathways. You can configure Simulated Hospital to run the pathways that you want, including how frequently to run each one. The application includes a few built-in pathways (see the folder "config/pathways") but most people will want to write their own.
Pathways are written using YAML or JSON and are human readable. The events are defined with words that are common in clinical settings such as "admission", "discharge", etc., and utility actions such as time delays.
Next steps
-
Get started by downloading & running Simulated Hospital.
-
See an example of the messages that Simulated Hospital generates.
-
Write pathways to create patients with specific conditions, for instance, a patient with appendicitis that has sets of Vital Signs taken periodically.
-
Change the default behavior of Simulated Hospital using command-line arguments, including:
- What pathways Simulated Hospital runs and their distribution, i.e., what pathways should run more frequently than others.
- What specific values to set for some fields in the HL7v2 messages in order to comply, or not, with the values in the HL7v2 standard. For instance, you can configure what should be set as the Sending Facility in the generated messages, or what keyword to use to represent that a set of laboratory results is amended.
- The demographics of the patients that are generated: names, surnames, ethnicity, etc. For instance, you can configure how many patients will have middle names, or what is the probability that a patient will have pre-existing allergies.
-
Control a running instance Simulated Hospital using its Dashboard (screenshot). Using the dashboard, you can do the following:
- Change the message-sending rate of a self-running simulation.
- Start an ad-hoc pathway or send an HL7v2 message.
-
Extend Simulated Hospital with advanced functionality using source code. For instance, you can change the format of the identifiers that Simulated Hospital generates, or create your own behavior for some events.
Quickstart
Prerequisites: install docker.
Run the latest version of Simulated Hospital:
docker run --rm -it -p 8000:8000 eu.gcr.io/simhospital-images/simhospital:latest health/simulator
Stop the simulator with Ctrl-C.
See more instructions on how to download & run Simulated Hospital.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
simulator
Binary simulator creates and runs an open-source version of Simulated Hospital.
|
Binary simulator creates and runs an open-source version of Simulated Hospital. |
|
pkg
|
|
|
clock
Package clock provides convenient functionality to manage the time.
|
Package clock provides convenient functionality to manage the time. |
|
config
Package config provides functionality for the configuration of Simulated Hospital, especially around loading such configuration from files.
|
Package config provides functionality for the configuration of Simulated Hospital, especially around loading such configuration from files. |
|
constants
Package constants contains constant variables used in pathway definition.
|
Package constants contains constant variables used in pathway definition. |
|
doctor
Package doctor provides functionality to manage doctors.
|
Package doctor provides functionality to manage doctors. |
|
files
Package files supports reading and writing files from local directories or GCS.
|
Package files supports reading and writing files from local directories or GCS. |
|
gender
Package gender contains the functionality to convert gender values.
|
Package gender contains the functionality to convert gender values. |
|
generator
Package generator implements functionality to generate various patient related information, including, but not limited to: - person information, ie: name, surname, ethnicity, address, etc., - patient type and class, - orders and test results, - allergies, - diagnosis, - procedures.
|
Package generator implements functionality to generate various patient related information, including, but not limited to: - person information, ie: name, surname, ethnicity, address, etc., - patient type and class, - orders and test results, - allergies, - diagnosis, - procedures. |
|
generator/address
Package address contains functionality to generate addresses.
|
Package address contains functionality to generate addresses. |
|
generator/codedelement
Package codedelement contains functionality to generate Coded Elements that have a Code and a Description.
|
Package codedelement contains functionality to generate Coded Elements that have a Code and a Description. |
|
generator/document
Package document contains functions needed to generate a ir.Document object.
|
Package document contains functions needed to generate a ir.Document object. |
|
generator/header
Package header contains functionality to generate headers.
|
Package header contains functionality to generate headers. |
|
generator/id
Package id provides the functionality to generate identifiers.
|
Package id provides the functionality to generate identifiers. |
|
generator/names
Package names provides functionality to generate names for humans.
|
Package names provides functionality to generate names for humans. |
|
generator/notes
Package notes contains functions needed to generate a ir.ClinicalNote object given the pathway.ClinicalNote object.
|
Package notes contains functions needed to generate a ir.ClinicalNote object given the pathway.ClinicalNote object. |
|
generator/order
Package order provides functionality to generate order and set results.
|
Package order provides functionality to generate order and set results. |
|
generator/person
Package person provides functionality to generate a person.
|
Package person provides functionality to generate a person. |
|
generator/text
Package text contains functions needed to generate random sentences.
|
Package text contains functions needed to generate random sentences. |
|
hardcoded
Package hardcoded contains features to manage hardcoded messages in Simulated Hospital.
|
Package hardcoded contains features to manage hardcoded messages in Simulated Hospital. |
|
hl7
Package hl7 provides functions for manipulating and handling HL7 messages, native HL7 types, and reading and writing messages over MLLP.
|
Package hl7 provides functions for manipulating and handling HL7 messages, native HL7 types, and reading and writing messages over MLLP. |
|
hospital
Package hospital implements the main functionality of Simulated Hospital.
|
Package hospital implements the main functionality of Simulated Hospital. |
|
hospital/runner
Package runner implements the main functionality of Simulated Hospital.
|
Package runner implements the main functionality of Simulated Hospital. |
|
hospital/runner/authentication
Package authentication provides functionality for authentication.
|
Package authentication provides functionality for authentication. |
|
ir
Package ir contains data structures related to internal representations of entities within Simulated Hospital.
|
Package ir contains data structures related to internal representations of entities within Simulated Hospital. |
|
location
Package location provides functionality to manage locations.
|
Package location provides functionality to manage locations. |
|
logging
Package logging provides functionality for logging.
|
Package logging provides functionality for logging. |
|
monitoring
Package monitoring contains functionality for metrics.
|
Package monitoring contains functionality for metrics. |
|
orderprofile
Package orderprofile is responsible for parsing and generating Order Profiles.
|
Package orderprofile is responsible for parsing and generating Order Profiles. |
|
pathway
Package pathway contains definition of pathway in Simulated Hospital, as well as functionality to parse pathways and manage them.
|
Package pathway contains definition of pathway in Simulated Hospital, as well as functionality to parse pathways and manage them. |
|
processor
Package processor contains configurations for event processors.
|
Package processor contains configurations for event processors. |
|
rate
Package rate contains functionality to deal with rates.
|
Package rate contains functionality to deal with rates. |
|
resource
Package resource contains functionality for generating resources from PatientInfo.
|
Package resource contains functionality for generating resources from PatientInfo. |
|
resource/cloud
Package cloud contains functionality to write to a Cloud FHIR store.
|
Package cloud contains functionality to write to a Cloud FHIR store. |
|
sample
Package sample includes the functionality for sampling from a discrete distribution.
|
Package sample includes the functionality for sampling from a discrete distribution. |
|
starter
Package starter contains functionality to start pathways by an endpoint.
|
Package starter contains functionality to start pathways by an endpoint. |
|
state
Package state contains definitions of stateful objects in Simulated Hospital.
|
Package state contains definitions of stateful objects in Simulated Hospital. |
|
state/persist
Package persist contains persist-specific interfaces.
|
Package persist contains persist-specific interfaces. |
|
test
Package test contains functionality to define test configs.
|
Package test contains functionality to define test configs. |
|
test/testaddress
Package testaddress contains functionality to generate deterministic addresses for testing.
|
Package testaddress contains functionality to generate deterministic addresses for testing. |
|
test/testclock
Package testclock provides a convenient Clock implementation for testing.
|
Package testclock provides a convenient Clock implementation for testing. |
|
test/testdate
Package testdate includes functionality to generate deterministic dates for testing.
|
Package testdate includes functionality to generate deterministic dates for testing. |
|
test/testhl7
Package testhl7 contains utility functions and helpers for testing with HL7 messages.
|
Package testhl7 contains utility functions and helpers for testing with HL7 messages. |
|
test/testhospital
Package testhospital contains functionality to test hospitals.
|
Package testhospital contains functionality to test hospitals. |
|
test/testid
Package testid contains functionality to generate identifiers in a deterministic way.
|
Package testid contains functionality to generate identifiers in a deterministic way. |
|
test/testlocation
Package testlocation contains utility functions and helpers for testing with locations.
|
Package testlocation contains utility functions and helpers for testing with locations. |
|
test/testmetrics
Package testmetrics gets information from metrics for testing.
|
Package testmetrics gets information from metrics for testing. |
|
test/testnotes
Package testnotes contains functionality to generate deterministic notes for testing.
|
Package testnotes contains functionality to generate deterministic notes for testing. |
|
test/testperson
Package testperson contains test Person data.
|
Package testperson contains test Person data. |
|
test/testresource
Package testresource contains utilities for testing with resources.
|
Package testresource contains utilities for testing with resources. |
|
test/teststate
Package teststate provides test-only implementation for state-specific interfaces.
|
Package teststate provides test-only implementation for state-specific interfaces. |
|
test/testtext
Package testtext contains functionality to generate deterministic text for testing.
|
Package testtext contains functionality to generate deterministic text for testing. |
|
test/testwrite
Package testwrite contains functionality to write files for testing.
|
Package testwrite contains functionality to write files for testing. |