Generic Module Framework: Logic - synthetichealth/synthea GitHub Wiki

The Guard state, conditional_transition, and complex_transition use conditional (boolean) logic. The following condition types are currently supported:

• Gender, Socioeconomic Status, Race
• Age, Date
• Symptom, Observation, Vital Sign
• Active Allergy, Active Condition, Active Medication, Active CarePlan
• Attribute, PriorState
• And, Or, Not
• At Least, At Most
• True, False

The following condition types should be considered for future versions:

• PriorEvent: check if a patient event occurred

The Gender condition type tests the patient's gender.

The following Gender condition will return true if the patient is male; false otherwise:

{
  "condition_type": "Gender",
  "gender": "M" 
}

The Age condition type tests the patient's age.

The following Age condition will return true if the patient is 40 years old or more:

{
  "condition_type": "Age",
  "operator": ">=",
  "quantity": 40,
  "unit": "years"
}

The Date condition type tests the current year, month, or date being simulated. For example, this may be used to drive different logic depending on the suggested medications or procedures of different time periods, or model different frequency of conditions.

The following Date condition will return true if the year is 1990 or later:

{
  "condition_type": "Date",
  "operator": ">=",
  "year": 1990
}

The following Date condition will return true if the month is 4 (April):

{
  "condition_type": "Date",
  "operator": "==",
  "month": 4
}

The following Date condition will return true if the date is July 4th, 2018 at 1 hour, 0 minutes, 0 seconds and 0 milliseconds or earlier:

{
  "condition_type": "Date",
  "operator": "<=",
  "date": {
    "year": 2018,
    "month": 7,
    "day": 4,
    "hour": 1,
    "minute": 0,
    "second": 0,
    "millisecond": 0
}

The Socioeconomic Status condition type tests the patient's socioeconomic status. Socioeconomic status is based on income, education, and occupation, and is categorized in Synthea as "High", "Middle", or "Low".

The following Socioeconomic Status condition will return true if the patient is "Middle" Socioeconomic Status; false otherwise:

{
  "condition_type": "Socioeconomic Status",
  "category": "Middle"
}

The Race condition type tests a patient's race. Synthea supports the following races:

"White", "Native" (Native American), "Hispanic", "Black", "Asian", and "Other".

The following Race condition will return true if the patient is "Hispanic"; false otherwise:

{
  "condition_type": "Race",
  "race": "Hispanic"
}

The Symptom condition type tests a patient's current symptoms. Synthea tracks symptoms in order to drive a patient's encounters, on a scale of 1-100. A symptom may be tracked for multiple conditions, in these cases only the highest value is considered. See also the Symptom state.

The following Symptom condition will return true if the patient's symptom score for "Chest Pain" is greater than or equal to 50:

{
  "condition_type": "Symptom",
  "symptom" : "Chest Pain",
  "operator": ">=",
  "value": 50
}

The Observation condition type tests the most recent observation of a given type against a given value.

• Synthea does not support conversion between arbitrary units, so all observations of a given type are expected to be made in the same units.
• The given observation must have been recorded prior to performing this logical check, unless the operator is is nil or is not nil. Otherwise, the GMF will raise an exception that the observation value cannot be compared as there has been no observation made.

The following Observation condition will return true if a previous Observation with code LOINC [72107-6] Mini Mental State Examination has a value greater than 22:

{
  "condition_type": "Observation",
  "codes": [
    {
      "system": "LOINC",
      "code": "72107-6",
      "display": "Mini Mental State Examination"
    }
  ],
  "operator": ">",
  "value": 22
}

The following Observation condition will return true if the most recent Observation referenced by the attribute "diabetes_test_performed" on the patient has any value that is not nil. In other words, if any observation has been made and stored in attribute diabetes_test_performed, this condition will return true:

{
  "condition_type": "Observation",
  "referenced_by_attribute": "diabetes_test_performed",
  "operator": "is not nil"
}

The Vital Sign condition type tests a patient's current vital signs. Synthea tracks vital signs in order to drive a patient's physical condition, and are recorded in observations. See also the Vital Sign state.

The following Vital Sign condition will return true if the patient's Systolic Blood Pressure vital sign is greater than 120:

{
    "condition_type" : "Vital Sign",
    "vital_sign" : "Systolic Blood Pressure",
    "operator" : ">",
    "value" : 120
  },

The Active Allergy condition type tests if a patient has an active allergy.

The following Active Allergy condition will return true if the patient currently has an active allergy to Penicillin:

{
  "condition_type": "Active Allergy",
  "codes": [
    {
      "system": "RxNorm",
      "code": "7984",
      "display": "Penicillin V"
    }
  ]
}

The following Active Allergy condition will return true if the allergy referenced by the attribute "penicillin_allergy" on the patient is currently active. In other words, if any allergy has started and is stored in the attribute "penicillin_allergy", this condition will return true:

{
  "condition_type" : "Active Allergy",
  "referenced_by_attribute" : "penicillin_allergy"
}

The Active Condition condition type tests whether a given condition is currently diagnosed and active on the patient.

Currently to check if a condition has been added but not diagnosed, it is possible to use the PriorState condition to check if the state has been processed. In the future it may be preferable to add a distinct "Present Condition" logical condition to clearly specify the intent of looking for a present but not diagnosed condition.

The following Active Condition condition will return true if the patient currently has an active diagnosis of SNOMED-CT 73211009 [Diabetes mellitus]:

{
  "condition_type": "Active Condition",
  "codes": [
    {
      "system": "SNOMED-CT",
      "code": "73211009",
      "display": "Diabetes mellitus"
    }
  ]
}

The following Active Condition condition will return true if the condition referenced by the attribute "alzheimers_variant" on the patient is currently active. In other words, if any condition has onset and is stored in the attribute "Alzheimer's Variant", this condition will return true:

{
  "condition_type": "Active Condition",
  "referenced_by_attribute": "alzheimers_variant"
}

The Active Medication condition type tests whether a given medication is currently prescribed and active for the patient.

The following Active Medication condition will return true if the patient currently has an active medication of RxNorm 849727 Naproxen sodium 220 MG [Aleve]:

{
  "condition_type": "Active Medication",
  "codes": [
    {
      "system": "RxNorm",
      "code": "849727",
      "display": "Naproxen sodium 220 MG [Aleve]"
    }
  ]
}

The following Active Medication condition will return true if the medication referenced by the attribute "pain_medication" on the patient is currently active. In other words, if any medication order has started and is stored in the attribute "pain_medication", this condition will return true:

{
  "condition_type" : "Active Medication",
  "referenced_by_attribute" : "pain_medication"
}

The Active CarePlan condition type tests whether a given care plan is currently prescribed and active for the patient.

The following Active CarePlan condition will return true if the patient currently has an active care plan of SNOMED-CT 698360004 [Diabetes self management plan]:

{
  "condition_type": "Active CarePlan",
  "codes": [
    {
      "system": "SNOMED-CT",
      "code": "698360004",
      "display": "Diabetes self management plan"
    }
  ]
}

The following Active CarePlan condition will return true if the care plan referenced by the attribute "diabetes_careplan" on the patient is currently active. In other words, if any care plan has started and is stored in attribute "diabetes_careplan", this condition will return true:

{
  "condition_type" : "Active CarePlan",
  "referenced_by_attribute" : "diabetes_careplan"
}

The PriorState condition type tests the progression of the patient through the module, and checks if a specific state has already been processed (in other words, the state is in the module's state history). The search for the state may be limited by time or the name of another state.

The following PriorState condition will return true if the patient has already passed through a state called "Emergency_Encounter", false otherwise:

{
  "condition_type": "PriorState",
  "name": "Emergency_Encounter"
}

The following PriorState condition will return true if the patient has passed through a state called "Emergency_Encounter" within the last 3 years, or false if the patient has never passed through the state, or last passed through the state more than 3 years ago:

{
  "condition_type": "PriorState",
  "name": "Emergency_Encounter",
  "within": { "quantity": 3, "unit" : "years"}
}

The following PriorState condition will return true if the patient has already passed through a state called "Emergency_Encounter" since last passing through a state called "Followup", false otherwise. (In other words, if the patient hit state "Emergency_Encounter" more recently than state "Followup". Note that it is not necessary for the state "Followup" to have been hit for this to return true.)

{
  "condition_type": "PriorState",
  "name": "Emergency_Encounter",
  "since" : "Followup"
}

The Attribute condition type tests a named attribute on the patient entity.

The following Attribute condition will return true if attribute "opioid_prescription" on the patient is set to "Vicodin":

{
  "condition_type": "Attribute",
  "attribute": "opiod_prescription",
  "operator": "==",
  "value": "Vicodin"
}

The following Attribute condition will return true if attribute "opioid_prescription" on the patient has any value that is not nil:

{
  "condition_type": "Attribute",
  "attribute": "opioid_prescription",
  "operator": "is not nil"
}

The And condition type tests that a set of sub-conditions are all true. If all sub-conditions are true, it will return true, but if any are false, it will return false.

The following And condition will return true if the patient is male and at least 40 years old; false otherwise:

{
  "condition_type": "And",
  "conditions": [
    {
      "condition_type": "Gender",
      "gender": "M" 
    },
    {
      "condition_type": "Age",
      "operator": ">=",
      "quantity": 40,
      "unit": "years"
    }
  ]
}

The Or condition type tests that at least one of its sub-conditions is true. If any sub-condition is true, it will return true, but if all sub-conditions are false, it will return false.

The following Or condition will return true if the patient is male or the patient is at least 40 years old; false otherwise:

{
  "condition_type": "Or",
  "conditions": [
    {
      "condition_type": "Gender",
      "gender": "M" 
    },
    {
      "condition_type": "Age",
      "operator": ">=",
      "quantity": 40,
      "unit": "years"
    }
  ]
}

The At Least condition type tests that a minimum number of conditions from a set of sub-conditions are true. If the minimum number or more sub-conditions are true, it will return true, but if less than the minimum are true, it will return false. (If the minimum is the same as the number of sub-conditions provided, this is equivalent to the And condition. If minimum is 1, this is equivalent to the Or condition.)

The following "At Least" condition will return true if 2 or more of the following 3 conditions are met: 1) the patient is male, 2) the patient is at least 40 years old, 3) the patient has an active Diabetes self management plan; false otherwise. For example, if the patient is Male, age 46, and does not have a Diabetes self management plan, this condition will return true. If the patient is Female, age 67, and does not have a Diabetes self management plan, this condition will return false:

{
  "condition_type": "At Least",
  "minimum": 2,
  "conditions": [
    {
      "condition_type": "Gender",
      "gender": "M" 
    },
    {
      "condition_type": "Age",
      "operator": ">=",
      "quantity": 40,
      "unit": "years"
    },
    {
      "condition_type" : "Active CarePlan",
      "codes": [
        {
          "system": "SNOMED-CT",
          "code": "698360004",
          "display": "Diabetes self management plan"
        }
      ]
    }
  ]
}

The At Most condition type tests that a maximum number of conditions from set of sub-conditions are true. If the maximum number or fewer sub-conditions are true, it will return true, but if more than the maximum are true, it will return false.

The following "At Most" condition will return true if 2 or fewer of the following 3 conditions are met: 1) the patient is male, 2) the patient is at least 40 years old, 3) the patient has an active Diabetes self management plan; false otherwise. For example, if the patient is Male, age 46, and does not have a Diabetes self management plan, this condition will return true. If the patient is Female, age 67, and does not have a Diabetes self management plan, this condition will return true. If the patient is Male, age 41, and has a Diabetes self management plan, this condition will return false:

{
  "condition_type": "At Most",
  "maximum" : 2,
  "conditions": [
    {
      "condition_type": "Gender",
      "gender": "M" 
    },
    {
      "condition_type": "Age",
      "operator": ">=",
      "quantity": 40,
      "unit": "years"
    },
    {
      "condition_type": "Active CarePlan",
      "codes": [
        {
          "system": "SNOMED-CT",
          "code": "698360004",
          "display": "Diabetes self management plan"
        }
      ]
    }
  ]
}

The Not condition type negates its sub-condition. If the sub-condition is true, it will return false; if the sub-condition is false, it will return true.

The following Not condition will return true if the patient is not male; false otherwise:

{
  "condition_type": "Not",
  "condition": {
    "condition_type": "Gender",
    "gender": "M" 
  }
}

The True condition always returns true. This condition is mainly used for testing purposes and is not expected to be used in any real module.

The following True condition always returns true:

{
  "condition_type": "True"
}

The False condition always returns false. This condition is mainly used for testing purposes and is not expected to be used in any real module.

The following False condition always returns false:

{
  "condition_type": "False"
}