-
Notifications
You must be signed in to change notification settings - Fork 663
Generic Module Framework: Basics
A new module must minimally have a name
and a set of states
that comprise the module. Every module must have an "Initial"
state. Most modules also have a "Terminal"
state. Additionally, remarks
may be used to add comments throughout the module.
{
"name": "The Name of the Module",
"remarks": [
"Additional comments about the module, ",
"perhaps on multiple lines. Links to sources ",
"also go here."
],
"states": {
"Initial": {
"type": "Initial",
"remarks": [
"Every module needs an initial state. Most ",
"modules should also have a Terminal state."
],
"direct_transition": "Terminal"
},
"Terminal": {
"type": "Terminal"
}
}
}
States are the core of a Generic Module Framework. There are two categories of states, clinical and control. Clinical states effect disease progression and care, while control states effect flow control. Modules typically have many states. Common states includes Encounter
, ConditionOnset
, Procedure
, and MedicationOrder
. While states
can have any string as a name, the best practice is to use Upper_Snake_Case
for state names. State names must be unique within the same module but may conflict across modules.
All states must minimally have a type
identifying the type of state.
"Hello_World": {
"type": "Simple"
}
Remarks are comments added GMF module files. All remarks
sections are ignored by Synthea and are used for references, calculations, and details about part of the module. Remarks should always be a list[]
of strings
, for example:
{
"remarks": [
"Remarks describe their parent object or detail important ",
"aspects of the module. Links to sources may be included here: ",
"http://www.example.com/source/ ",
"You may write use extra newlines to separate out remarks."
]
}
Attributes allow modules to store, reference, and share medications, conditions, procedures, etc. as well as as arbitrary strings. Attributes are generic containers that you can assign states, strings, and numeric values to for easy access and reference. Attributes can be assigned using assign_to_attribute
or using a SetAttribute
state. A special kind of Attribute is a Counter
, defined using the Counter
state.
While the name of an attribute
can be any string, the best practice is to use lower_snake_case
for attribute names. Attribute names must be unique across all modules.
Good:
{
"assign_to_attribute": "opioid_prescription"
}
Bad:
{
"assign_to_attribute": "Type of Alzheimer's"
}
Valid units of time are "years"
, "months"
, "weeks"
, "days"
, "hours"
, "minutes"
, and "seconds"
.
{
"quantity": 4,
"unit": "hours"
}
Valid units of age are "years"
, "months"
, "weeks"
, "days"
, "hours"
, "minutes"
, and "seconds"
.
{
"quantity": 40,
"unit": "years"
}
Any string is a valid unit of measurement. Metric units are typically used.
{
"unit": "cm"
}
Where codes are used, a system
, code
, and display
are required fields.
ValueSets can be used optionally. In order for ValueSets to be used, you need to specify a FHIR terminology server using the generate.terminology_service_url
property and have a module with a ValueSet specified.
ValueSets can be specified in any State that contains a code
. Just add a value_set
attribute in addition to the system, code, and display.
For example:
{
"system": "SNOMED-CT",
"code": "2501000087107",
"display": "MRI of right knee with contrast",
"value_set": "http://snomed.info/sct?fhir_vs=ecl/<<2491000087104"
}
SNOMED Clinical Terms (SNOMED-CT) describe clinical findings, symptoms, diagnoses, procedures, body structures, organisms and other etiologies, substances, pharmaceuticals, devices and specimens. In the Generic Module Framework these codes are used to describe Encounter
, Procedure
, ConditionOnset
, and CarePlanStart
states.
For a searchable directory of valid SNOMED codes see the IHTSDO SNOMED CT Browser.
{
"system": "SNOMED-CT",
"code": "44054006",
"display": "Diabetes"
}
RxNorm codes describe prescriptions and medications. They include dosage information and common Brands. In the Generic Module Framework these codes are used only for MedicationOrder
states.
For a searchable directory of RxNorm codes see the U.S. National Library of Medicine RxNorm Browser.
Note: When picking an RxNorm code, you must use something that has an NDC on the market, now or in the past. Otherwise, the code represents something that is not prescribe-able. See this issue.
{
"system": "RxNorm",
"code": "575971",
"display": "oxaliplatin 5 MG/ML [Eloxatin]"
}
LOINC codes describe tests, measurements, and observations. In the Generic Module Framework these codes are used only for Observation
states.
For a searchable directory of LOINC codes see the LOINC Browser.
{
"system": "LOINC",
"code": "33756-8",
"display": "Polyp size greatest dimension by CAP cancer protocols"
}
DICOM-DCM codes describe the modality used to take a series of images in an ImagingStudy. In the Generic Module Framework these codes are only used for ImagingStudy
states.
{
"system": "DICOM-DCM",
"code": "MR",
"display": "Magnetic Resonance"
}
DICOM-SOP codes describe an individual image instance taken in a series of images during an ImagingStudy. Specifically, SOP codes describe the Subject-Object Pair (SOP) that constitutes the image. In the Generic Module Framework these codes are only used for ImagingStudy
states.
{
"system": "DICOM-SOP",
"code": "1.2.840.10008.5.1.4.1.1.1.1",
"display": "Digital X-Ray Image Storage"
}