SAGE Guideline Encoding Tools

The SAGE Guideline Workbench include a suite of tools that project members use to create, view, edit, and validate SAGE guidelines that conform to the format of the SAGE Guideline Model and that are executable by the SAGE Execution Engine to provide decision support for guideline-based care. The project has a number of requirements for the guideline workbench. It should be a tool that
  • supports encoding process
  • provides connection to terminology services to be used during encoding
  • allows debugging/validation of guidelines
  • provides a document-oriented view of the guideline knowledge base so that clinicians and knowledge engineers can easily review the content of the knowledge base

We reviewed a number of guideline encoding environments and chose Protégé as the basis for developing the SAGE Guideline Workbench. Protégé is a knowledge-engineering tool that allows not only rapid prototyping of guideline ontologies but also encoding instances of guidelines. In addition, Protégé is an extensible knowledge-engine platform; its plugin architecture allows SAGE-specific extensions and the API allows decision-support applications to access the knowledge base.

Detailed documentation for Protégé

Views of and operations on a Protégé knowledge base are organized into tabs. In addition to the standard Classes and Instances tabs, the following Protégé and SAGE-specific tabs are useful in the guideline encoding process.

Click on the Kwiz Tab, SAGE Tab, PAL Constraint Tab, Facet Constraint Tab, Apelon DTS Tab,
Knowledge Tree Tab, or Kb2doc Document-generation Tab here or in the figure below for more information.

Additional information about the SAGE Guideline Workbench can be found in the reference section.

Knowledge Tree Tab


The KnowledgeTree widgets allow navigation of frames that are directly and indirectly referenced from a selected instance in a tree structure. It allows you to browse and edit, in a single window, all the frames reachable from the top-level instance (usually the top-level Guideline instance). Clicking on a slot name highlights the widget associated with the slot. The following is a screenshot of the KnowledgeTree tab. The left pane displays SAGE Diabetes Guideline as the top-level instance. The right pane shows the instance form for the selected instance Primary Care Clinic Visit recommendation set:

Facet Constraint Tab


The Facet Constraints Tab allows a user to identify and fix all instances in a knowledge base, or instances of selected classes, that have slots whose values violate constraints associated with the slot.

Prior to the development of this tab, if a user wanted to find all instances that had constraint violating facets in his/her ontology, they had to manually iterate through all the instances in their ontology looking for red boxes that identified slots that had constraint violating facets. The Facet Constraints Tab allows a user to accomplish this task with the click of one button.

When a user clicks the "Check Constraints of Selected Classes" button, the tab displays the subset of selected classes which have violating instances (the second column from the left in the figure below). When one of these displayed classes is selected, the violating instances of that class are displayed (third column from the left). When a violating instance is selected, the instance is displayed and a text area in the main window lists each of the facet violations, providing an explanation of why the facet is violating a constraint. A user can then use the provided information to fix the violating instances from within the Facet Constraints Tab, with all changes updating the ontology.

PAL Constraint Tab


PAL, the Protégé Axiom Language, is a subset of first-order logic which can be used to express integrity constraints about a knowledge base. The PAL Constraints Tab is a front-end for this constraint system. This tab allows a user to create, browse, and modify constraints in the knowledge base, and to evaluate constraints (either as a group or individually)

In the SAGE project,we use PAL to define and check integrity constraints that a well-formed guideline encoding should satisfy. For example, in the figure below, we check four constraints: (1) an Action node should either have a subguideline or it should have CIS actions defined as values of the action_spec property; (2) an activity graph that is a subguideline should have a start node; (3) a Context node that does not have an incoming transition should have triggering events that would activate the node, and (4) a decision map should contain a Decision node. The PAL constraint found that the first three constraints are satisfied in the sample knowledge base, but it found an instance "Decision map to set lipid goals" that does not have a Decision node.

Apelon Terminology Service Tab


The SAGE team developed an Apelon terminology tab and plug-in (i.e., and integration between Apelon software and Protégé), that works with Apelon DTS 3.0 server across Internet. The plug-in allows a search of terms from several terminologies, including SNOMED CT , LOINC, and ICD9, and creation of a reference in the Protégé Guideline Workbench, using an HL7 “CodedValue” instance, to a term in a standard terminology.

Documentation about the DTS Plugin is here [pdf].

The figure below shows a search for SNOMED CT terms that begins with "hemoglobin." The search result is shown in the lower-left pane. Details of the selected term "Hemoglobin A1c measurement (procedure)" is shown in the lower-right pane. Clicking on the "OK" button would create a reference to the term in the Protégé environment.

Kwiz Tab


KWIZ is built as an extension to Protégé to improve Protégé’s knowledge-acquisition environment. The main components of KWIZ are:

  • Customizable high-level views of the knowledge base
  • Constrained navigation
  • Reuse of existing knowledge bases
  • Context-sensitive search and help

In the figure below, we show the a Kwiz screen where the left-hand pane keeps track of the navigation path from the set of recommendation sets in the guideline to the current search window. The right-hand-side search window shows the result of search in the "Neonatal Hepatitis Immunization recommendation set set" for all instances of Expression whose instance label contains the string "hepatitis."

Documentation for KWIZ [pdf]



The SAGE Tab provides a self-contained testing environment within Protégé for an encoded guideline. After validating the knowledge base, a user can select data from a test case and run the guideline by simulating the arrival of triggering events. The figure below shows an "Outpatient nurse accesses the patient record" event has been sent for a pediatric patient. The SAGE Execution Engine walks through the steps in the triggered recommendation set, evaluating decision criteria to determine appropriate actions to take (lower-left pane). After evaluating possible immunizations that may be due, it requests information on immunization consent and serious illnesses that may render immunization inadvisable (lower-right pane). Once responses to the questions are submitted, the SAGE Execution Engine will generate its final recommendations for the immunizations that should be given. The operations of the SAGE tab is further described here.

Kb-to-doc Document-generation Tab


It is important for users of SAGE guideline knowledge bases to be able view the content of the encoded guidelines as readily understandable documents, instead of having to navigate through the arcane and abstract classes, instances, and slots of a formal representation in Protégé. To this end, we developed the capability to generate a document-oriented view of the contents of the encoded guideline. To accomplish this, we developed a formalism to annotate the SAGE guideline model with information about which parts of the guideline knowledge base should be printed and how to print the content of instances of any select class.

This specification is saved as a Protégé knowledge base. We then developed a Java program that uses as input an encoded guideline (e.g. immunization guideline) and the document-specification knowledge base to generate an XML version of the knowledge base. We used XSLT to transform the XML export to HTML. The recommendation sets algorithms become clickable images through which a user can navigate to different parts of the document.

Each of the exemplar guidelines has such a HTML page: