Missing records for an Encounter in a new module

[Sobhym]

I created a simple module "Test_Encounter" using Synthea Generic Module Builder, that contains two states, a ConditionOnset and an ambulatory Encounter (all with direct transitions). The "Test_Encounter" module file:

{
  "name": "Test_Encounter",
  "remarks": [
    "A blank module"
  ],
  "states": {
    "Initial": {
      "type": "Initial",
      "direct_transition": "Examplitis"
    },
    "Terminal": {
      "type": "Terminal"
    },
    "Examplitis": {
      "type": "ConditionOnset",
      "codes": [
        {
          "system": "SNOMED-CT",
          "code": "123",
          "display": "Examplitis"
        }
      ],
      "direct_transition": "Examplotomy_Encounter"
    },
    "Examplotomy_Encounter": {
      "type": "Encounter",
      "encounter_class": "ambulatory",
      "codes": [
        {
          "system": "SNOMED-CT",
          "code": "ABC",
          "display": "Examplotomy Encounter"
        }
      ],
      "direct_transition": "End_Examplotomy_Encounter"
    },
    "End_Examplotomy_Encounter": {
      "type": "EncounterEnd",
      "direct_transition": "Terminal"
    }
  }
}

I added the module file to the correct path (src/main/resources/modules/) and rebuilt Synthea (not sure if the rebuild is necessary, is it?). As per my understanding, both the ConditionOnset and the Encounter should be reflected in the patient history. All the patients has records for the example Condition in 'conditions.csv' file, but, there are only few records for the example Encounter in 'encounter.csv' file. For example, when simulating a population of size 10, there are 10 records with the code 'Examplitis' in 'conditions.csv', but there are only 2 records with the code 'ABC' in 'encounter.csv'.

[dehall]

I suspect what happened here is that the ABC code was added to the record but then filtered out by the export filter before writing the file. By default, Synthea only keeps record entries from within the past 10 years, including any "open" items from more than 10 years ago. This is done for a few reasons, including reducing file size, the fact that real patient health records rarely contain a full lifetime of history, and the fact that our modules are based on contemporary medical practices, so the further back in time you look the less realistic the record tends to be. In this specific instance, the Examplitis 123 condition is still open (has no end date) so it's preserved, but the Examplotomy_Encounter contains no "open" conditions or medications so it can be filtered out.

If you want to ensure that all entries are kept in the record, there is a configuration setting exporter.years_of_history in synthea.properties, which you can change to 0 to keep all history and not do any filtering, or change to another higher number to keep more years. https://github.com/synthetichealth/synthea/wiki/Common-Configuration

Note that a full rebuild of the code is not necessary to pick up new modules, just a restart of the app.

@jawalonoski do you think there should be something more prominent explaining this feature? At the moment it feels a little buried in the wiki

[jawalonoski]

Probably. We should add a new wiki section called I added a module. Where is the data for X? or something like that.

[Sobhym]

@dehall thanks for the explanation. I changed exporter.years_of_history to 0 and all the patient history records are reflected correctly. @jawalonoski I think the section you mentioned will be useful, or a question and answers section. I am creating a new module using the Generic Module Framework and have some other questions:

1. Is it possible to decide what type of provider (hospitals, primarycare, urgentcare, etc.) a person will go or be refereed to?
2. Can I get information about the provider chosen by Synthea, for example the value of quality attribute for the provider? What are the attributes that are accessible inside a module?

@Righolt

[jawalonoski]

You can decide what type of provider it is by setting the Encounter.encounter_class property. See https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework%3A-States#encounter-classes

Legal values are from the EncounterType enumeration: https://github.com/synthetichealth/synthea/blob/6dbf88c6ab83425fb5964c99f04a8d6a1a921ecf/src/main/java/org/mitre/synthea/world/concepts/HealthRecord.java#L291

Regarding attributes, I'm planning to add another wiki page that lists all the attributes available for patients and providers. Currently, the base provider attributes are those read from the provider files. See the column headers on these files: https://github.com/synthetichealth/synthea/tree/master/src/main/resources/providers, specifically hospitals.csv, primary_care_facilities.csv, urgent_care_facilities.csv, and va_facilities.csv. The other files are not currently used today.

Additional provider attributes track the amount of care provided. See the attributes labeled encounters-*, procedures-*, labs-*, and prescriptons-* -- where * is wildcard for any EncounterType. So, for example you can see encounters-urgentcare if you want.

[Sobhym]

You can decide what type of provider it is by setting the Encounter.encounter_class property. See https://github.com/synthetichealth/synthea/wiki/Generic-Module-Framework%3A-States#encounter-classes Legal values are from the EncounterType enumeration:

  synthea/src/main/java/org/mitre/synthea/world/concepts/HealthRecord.java

     Line 291
  in
  6dbf88c

       WELLNESS, AMBULATORY, OUTPATIENT, INPATIENT, EMERGENCY, URGENTCARE; 

Regarding attributes, I'm planning to add another wiki page that lists all the attributes available for patients and providers. Currently, the base provider attributes are those read from the provider files. See the column headers on these files: https://github.com/synthetichealth/synthea/tree/master/src/main/resources/providers, specifically hospitals.csv, primary_care_facilities.csv, urgent_care_facilities.csv, and va_facilities.csv. The other files are not currently used today. Additional provider attributes track the amount of care provided. See the attributes labeled encounters-, procedures-, labs-, and prescriptons- -- where * is wildcard for any EncounterType. So, for example you can see encounters-urgentcare if you want.

1. I created an encounter state and set "encounter_class": "urgentcare". In the output data, the encounter type is set correctly as "urgentcare", but the provider is not an urgent care provider (see the example below).

2. I tried to access different provider attributes inside an encounter state but they were not set (see the example below).

Example Module:

{
  "name": "Test_Module",
  "remarks": [
    "A blank module"
  ],
  "states": {
    "Initial": {
      "type": "Initial",
      "direct_transition": "Examplitis"
    },
    "Terminal": {
      "type": "Terminal"
    },
    "Examplitis": {
      "type": "ConditionOnset",
      "codes": [
        {
          "system": "SNOMED-CT",
          "code": "123",
          "display": "Examplitis"
        }
      ],
      "direct_transition": "Examplotomy_Encounter"
    },
    "Examplotomy_Encounter": {
      "type": "Encounter",
      "encounter_class": "urgentcare",
      "codes": [
        {
          "system": "SNOMED-CT",
          "code": "ABC",
          "display": "Examplotomy Encounter"
        }
      ],
      "conditional_transition": [
        {
          "transition": "Examplotomy",
          "condition": {
            "condition_type": "Attribute",
            "attribute": "quality",
            "operator": "is not nil"
          }
        },
        {
          "transition": "End_Examplotomy_Encounter"
        }
      ]
    },
    "End_Examplotomy_Encounter": {
      "type": "EncounterEnd",
      "direct_transition": "Terminal"
    },
    "Examplotomy": {
      "type": "Procedure",
      "duration": {
        "low": 2,
        "high": 3,
        "unit": "hours"
      },
      "codes": [
        {
          "system": "SNOMED-CT",
          "code": "789",
          "display": "Examplotomy"
        }
      ],
      "reason": "Examplitis",
      "direct_transition": "End_Examplotomy_Encounter"
    }
  }
}

1. wellness and urgentcare (Examplotomy_Encounter) has the same provider (a hospital), PROVIDERending by d05a9a79cf11, which is different from the provider for an urgent care encounter created by Synthea (Outpatient procedure (procedure)). From encounters.csv:

   
   Id,START,STOP,PATIENT,PROVIDER,ENCOUNTERCLASS,CODE,DESCRIPTION,COST,REASONCODE,REASONDESCRIPTION
   57a21201-da49-4496-8f26-82b2ffb6e8b9,1984-11-20T10:12:56Z,1984-11-20T10:42:56Z,c9e70606-15a9-44be-8f1f-12e8874bcbd1,fd328395-ab1d-35c6-a2d0-d05a9a79cf11,wellness,185349003,Encounter for check up (procedure),129.16,,
   31fad82c-5103-4c4d-829e-b372fc6b188b,1984-11-20T10:12:56Z,1984-11-20T10:27:56Z,c9e70606-15a9-44be-8f1f-12e8874bcbd1,fd328395-ab1d-35c6-a2d0-d05a9a79cf11,urgentcare,ABC,Examplotomy Encounter,129.16,,
   c223cdf9-e7a1-4ec3-81ee-dc137bc0d5d2,1988-07-12T10:12:56Z,1988-07-12T10:27:56Z,c9e70606-15a9-44be-8f1f-12e8874bcbd1,7ffe74ac-786d-3c6d-bcb9-323352f6149c,urgentcare,371883000,Outpatient procedure (procedure),129.16,,

2. I created a conditional transition to `Examplotomy` procedure, the condition is `quality` attribute (one of the provider attributes) `is not nil`, but there is no record for `Examplotomy` procedure in `procedures.csv`.

[jawalonoski]

1. I'll have to debug this when I get some time.

2. Conditional logic based on attributes refer only to Patient attributes, not the provider attributes. Provider attributes are not currently considered in the module logic whatsoever. Sorry for the confusion.