Generic Module Framework: Logic

The Guard state and Conditional transition use conditional (boolean) logic. The following condition types are currently supported: Gender, Age, Date, Socioeconomic Status, Symptom, PriorState, Active Condition, Observation, Attribute, And, Or, Not, True, and False.

The following condition types should be considered for future versions:

• PriorEvent: check if a patient event occurred

Gender

The Gender condition type tests the patient's gender.

Supported Properties

• condition_type: must be "Gender" (required)
• gender: the gender to test for. Synthea currently defines the following gender values: M: male, and F: female (required)

Example

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

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

Age

The Age condition type tests the patient's age. The following units are supported: years, months, weeks, days, hours, minutes, and seconds.

Supported Properties

• condition_type: must be "Age" (required)
• operator: indicates how to compare the actual age against the quantity. Valid operator values are: <, <=, ==, >=, >, and !=. (required)
• quantity: the number, corresponding to the unit, to indicate the age to test against (required)
• unit: the unit corresponding to the quantity. Valid unit values are: years, months, weeks, days, hours, minutes, and seconds. (required)

Example

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

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

Date

The Date condition type tests the current year 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.

Supported Properties

• condition_type: must be "Date" (required)
• operator: indicates how to compare the current year of simulation against the year. Valid operator values are: <, <=, ==, >=, >, and !=. (required)
• year: the year to test the current year of simulation against (required)

Example

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

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

Socioeconomic Status

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", "Medium", or "Low".

Supported Properties

• condition_type: must be "Socioeconomic Status" (required)
• category: the gender to test for. Synthea currently defines the following categories: High, Middle, or Low. (required)

Example

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

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

Symptom

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.

Supported Properties

• condition_type: must be "Symptom" (required)
• symptom: the name of the symptom to test against. (required)
• operator: indicates how to compare the current symptom score against the value. Valid operator values are: <, <=, ==, >=, >, and !=. (required)
• value: the value to test the current symptom score against (required)

Example

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
}

Observation

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

Implementation Warnings

• 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.

Supported Properties

• condition_type: must be "Observation" (required)
• codes[]: a list of codes indicating the observation(optional, required if referenced_by_attribute is not set)_
  • system: the code system. Currently, only LOINC is allowed. (required)
  • code: the code (required)
  • display: the human-readable code description (required)
• referenced_by_attribute: the name of the Attribute in which a previous Observation state recorded an observation (optional, required if codes[] is not set)
• operator: indicates how to compare the actual attribute value against the value. Valid operator values are: <, <=, ==, >=, >, !=, is nil, and is not nil. (required)
• value: the value to test the most recent observation value against (required, unless operator is is nil or is not nil)

Example

The following Observation condition will return true if the most recent Observation for LOINC '72107-6' [Mini Mental State Examination] on the patient 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"
}

Active Condition

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

Future Implementation Considerations

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.

Supported Properties

• condition_type: must be "Active Condition" (required)
• codes[]: a list of codes indicating the condition (optional, required if referenced_by_attribute is not set)
  • system: the code system. Currently, only SNOMED-CT is allowed. (required)
  • code: the code (required)
  • display: the human-readable code description (required)
• referenced_by_attribute: the name of the Attribute in which a previous ConditionOnset state added a condition (optional, required if codes[] is not set)

Example

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 "Alzheimer's Variant" on the patient is currently active. In other words, if any condition has onset and is stored in attribute "Alzheimer's Variant", this condition will return true.

{
    "condition_type" : "Active Condition",
    "referenced_by_attribute" : "Alzheimer's Variant"
}

Active CarePlan

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

Supported Properties

• condition_type: must be "Active CarePlan" (required)
• codes[]: a list of codes indicating the condition (optional, required if referenced_by_attribute is not set)
  • system: the code system. Currently, only SNOMED-CT is allowed. (required)
  • code: the code (required)
  • display: the human-readable code description (required)
• referenced_by_attribute: the name of the Attribute in which a previous CarePlanStart state added a care plan (optional, required if codes[] is not set)

Example

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"
}

PriorState

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).

Supported Properties

• condition_type: must be "PriorState" (required)
• name: the name of the state to check for in the module's history. (required)

Example

The following PriorState condition will return true if the patient has already passed through a state called 'EmergencyEncounter', false otherwise.

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

Attribute

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

Supported Properties

• condition_type: must be "Attribute" (required)
• attribute: the name of the attribute to test against (required)
• operator: indicates how to compare the actual attribute value against the value. Valid operator values are: <, <=, ==, >=, >, !=, is nil, and is not nil. (required)
• value: the value to test the attribute value against (required, unless operator is is nil or is not nil)

Example

The following Attribute condition will return true if attribute 'Opioid Prescription' on the patient is set to 'Vicodin'.

{
  "condition_type": "Attribute",
  "attribute": "Opioid 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"
}

And

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.

Supported Properties

• condition_type: must be "And" (required)
• conditions[]: an array of sub-conditions to test (required)

Example

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"
    }
  ]
}

Or

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.

Supported Properties

• condition_type: must be "Or" (required)
• conditions[]: an array of sub-conditions to test (required)

Example

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"
    }
  ]
}

Not

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.

Supported Properties

• condition_type: must be "Not" (required)
• condition: the sub-condition to test (required)

Example

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

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

True

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.

Supported Properties

• condition_type: must be "True" (required)

Example

The following True condition always returns true.

{
  "condition_type": "True"
}

False

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.

Supported Properties

• condition_type: must be "False" (required)

Example

The following False condition always returns false.

{
  "condition_type": "False"
}