Earlydoc Guide Modeling Language

Earlydoc formalizes health industry guidelines by using a "domain specific language" to translate natural language medical advice into structured data. This document describes how to author guides using this modeling language.

Overview

The main principle of the modeling language is to keep the formalized guidelines as similar as possible to the original source literature in order to facilitate professional review and minimize interpretation errors. Because logical complexity is unavoidable, the idea is not to make complex things simple, but rather to make them clear; an important distinction.

Guides can be written in any text editor, and then read by Earlydoc's various health modules for analysis or patient triage.

The modeling language is "declarative", and authoring a guide entails writing a number of statements, one per line, each of which defines a piece of data for the guide, for example a question, diagnosis, or outcome. Authors, then, simply write a series of facts, mostly describing relationships between data. The style is designed to be read linearly, in the same manner as clinical staff would read the original guides.

The following is an example question about a patient's fever formalized in the modeling language:

question :do_you_have_fever do
  required
  explanation :measure_and_indicate_temp
  answer :no_fever
  answer :fever_higher_then_40
end

The important thing is to get a sense of the structure of the language; the specifics of the commands themselves are explained further below.

Blocks

In the example question, the content is indented in a "do..end" block. This convention signifies that the statements inside the block refer to the question. This block convention is used for various statements in the language as a way to define context, but also to help visually group related information for the author/reader.

Blocks can be nested, and in fact the guide itself always acts as the parent block for all of its content.

Keys

All text in the modeling language is specified using "keys", short underscored phrases that begin with a colon, e.g. :some_key_word_phrase.

Keys serve several purposes, the first and foremost being a way to easily refer to much longer sentences or paragraphs of text. Because of this, keys should be named using minimal words necessary to summarize the text to which they refer, striking a balance between information and brevity.

The text referred to by keys will also be translated to other languages, which is another reason to write the guides using keys instead of actual text as it would appear to a patient: it's necessary to abstract the text away from the guide formalization for localization purposes.

Finally, keys are often used within guide logic as a unique identifier for a piece of data, a fact about a patient, or general medical information. This greatly simplifies the data structures which Earlydoc uses, enabling much of the data (e.g. a patient's triage answers) to be modeled as simple lists of keys. If the keys are named in a descriptive way, their meaning should be evident even when viewed out of context.

Ordering

In general, the order in which statements are given in the guide does not matter. So long as a statement is in the correct block, it doesn't matter where it appears relative to others. In the cases where order matters (with outcomes, for example) this is noted in the documentation.

DSL

The DSL comprises a number of commands used to describe medical guides. These guides take the form of a series of questions, along with the medical information (e.g. diagnoses, symptoms) that can be inferred and the actions that can be recommended (e.g. see a doctor) on the basis of answers to these questions.

Command Reference

Index

• Guides
  define
  version_number
  illustration
  description
  ignore_diagnoses_weighted_below

• Complaints
  complaint
  illustration
  given
  explanation

• Outcomes
  outcome
  summarize
  warn
  header
  paragraph
  tip
  given
  recommend
  indicator

• Questions
  group
  question
  illustration required
  explanation
  warning
  given

• Answers
  answer
  illustration
  explanation

• Diagnoses
  diagnose
  description
  disease
  risk
  symptom

Guides

• define

  BLOCK: yes
  PARAMETERS: guide name key
  NOTES: The define block is the only required command in the DSL, and serves as the parent block for all other guide content. The guide name key itself (not its translation) is used throughout the UI and website URLs, and so should be chosen in consideration of usability/SEO.
  EXAMPLE:

    define :my_guide do  
      ...  
    end
  

• version_number

  BLOCK: no
  PARAMETERS: version number
  NOTES: The version number is used to indicate modifications to a guide that may materially change how a patient experiences the triage. This number should be updated whenever a guide is changed in such a way that its content could change a previous triage result. EXAMPLE:

    define :my_guide do  
      version_number '1.0'  
    end
  

• illustration

  BLOCK: no
  PARAMETERS: path to image asset
  NOTES: The illustration references an image asset for the guide used to visually represent it in the triage UI whenever guide thumbnails are displayed.
  EXAMPLE:

    define :my_guide do  
      illustration 'symptoms/my_symptom.png'  
    end  
  

• description

  BLOCK: no
  PARAMETERS: description key
  NOTES: The guide description key text is displayed to the user in the triage UI.
  EXAMPLE:

    define :my_guide do  
      description :my_guide_summary  
    end  
  

• body

  BLOCK: no PARAMETERS: anatomy title key, anatomy explanation text key, anatomy image key NOTES: The body command displays a box of anatomical information about the a part in the triage UI. The anatomy image references an image asset name for the body part used to visually represent it in the triage UI. In order to localize the images, a key is used to refer to the illustration instead of an image path. EXAMPLE:

    define :my_guide do  
      body :how_does_your_body_work, :how_body_works_explanation, :anatomy_image_png  
    end    
  

• ignore_diagnoses_weighted_below

  BLOCK: no PARAMETERS: diagnosis weight threshold NOTES: The ignore_diagnoses_weighted_below command sets the minimum necessary weight for a guide's diagnosis to be considered in a triage. The combined value of the diagnosis risk and sum symptoms weight gives a total weight to each diagnosis, and if this value falls below the diagnosis weight threshold then the diagnosis is excluded from the triage as too unlikely for consideration. EXAMPLE:

    define :my_guide do  
      ignore_diagnoses_weighted_below 5
    end  
  

Complaints

• complain

  BLOCK: yes
  PARAMETERS: complaint name key
  NOTES: A complaint represents an issue causing any number of possible symptoms. A patient is considered to have a complaint if they have provided any of the given answer conditions (see below) in the triage. Multiple complain statements can be given in the guide. The complaint name key text is displayed to the user in the triage UI. EXAMPLE:

    complain :some_complaint do  
      ...  
    end  
  

• illustration

  BLOCK: no
  PARAMETERS: image asset path NOTES: The illustration references an image stored in the image asset path for the complaint used to visually represent it in the triage UI when complaint thumbnails are displayed.
  EXAMPLE:

    complain :some_complaint do  
      illustration 'some_complaint.png'  
    end  
  

• given

  BLOCK: no
  PARAMETERS: answer key
  NOTES: This logical condition associates the complaint with an answer key defined for an answer elsewhere in the guide; if a patient gives that answer, then they are assumed to have the complaint. Multiple given statements can be provided if several possible answers would indicate the complaint.
  EXAMPLE:

    complain :some_complaint do  
      given :answer_one  
      given :answer_two  
    end
  

• explanation

  BLOCK: no
  PARAMETERS: explanation key
  NOTES: The complaint explanation key text is displayed to the user in the triage UI.
  EXAMPLE:

    complain :some_complaint do  
      explanation :info_about_the_complaint  
    end  
  

Outcomes

• outcome

  BLOCK: yes
  PARAMETERS: outcome name key
  NOTES: An outcome represents a recommendation for a patient's next action (visit a doctor or wait) based on answers they provided to the triage. Multiple outcome blocks can be defined in a guide, and the order which they are defined implies an urgency level such that the first outcome defined in the guide is the most urgent and the last outcome the least.
  EXAMPLE:

    outcome :see_a_doctor_now do  
    end  
    ...  
    outcome :see_a_doctor_tomorrow do  
    end
  

• summarize

  BLOCK: no
  PARAMETERS: summary title key, summary text key
  NOTES: The outcome summary is displayed to the user in the triage UI, and consists of two parts: (1) a title and (2) text body.
  EXAMPLE:

    outcome :see_a_doctor_later do  
      summarize :is_it_serious, :your_complaints_are_not_serious  
    end
  

• warn

  BLOCK: no
  PARAMETERS: warning key
  NOTES: The warning key text is displayed to the user in the triage UI.
  EXAMPLE:

    outcome :see_a_doctor_later do  
      warn :this_does_not_replace_doctor_contact  
    end  
  

• sick_days

  BLOCK: no
  PARAMETERS: base number of sick days NOTES: The base number of sick days is the number of days a user is told to wait before s