Archetype Tutorial I
This tutorial guide is a supplement to the Archetypes guide, utilizing existing models to provide a step-by-step demonstration on how to design basic archetypes for different types of clinical decision support (CDS) applications using the openEHR Archetype Editor.
Before starting the modelling process, it is of vital importance to understand that the model of a clinical concept must be constructed based upon a solid scientific basis. It is therefore essential to thoroughly review the available scientific literature prior to commencing the construction of the archetype to minimise the potential risk of errors. Once the model has been published, users should be able to quickly access the scientific material upon which the model is based upon; always make sure to list the references.
Resources containing more in-depth information are available on the Links & Resources page. There is also a link to Cambio Healthcare Systems CDS Apps Showcase Page on GitHub available in this section, containing over 100 demo applications (using 250+ archetypes and 200+ guidelines).
The guide has been written by the Clinical Modelling Group at Cambio Healthcare Systems. If you have any questions or would like to provide feedback on this document, please send us a message by visiting the Contact Us page.
This tutorial will focus solely on archetypes for CDS applications which primary function is to perform calculations. Archetypes used in calculation applications generally make use of the quantity data element that stores both numerical values AND units (for more information on the quantity date element, see the archetype introduction guide).
Examples of clinical applications using calculations are: albumin/creatinine ratio, Basal Metabolic Rate, Body Mass Index, Body Surface Area, corrected calcium, fractional excretion of sodium/urea, Ideal Body Weight, Glomerular Filtration Rate, Mean Arterial Pressure, Parkland formula, and TIMI Risk Index. This tutorial will focus on the clinical concept Ideal Body Weight (IBW). All of the applications mentioned are available in our common-clinical-models repository at GitHub, and can be tested via the CDS Apps Overview page in the Links and Resources section.
To demonstrate how to create archetypes with the intention of being used in CDS applications performing calculations, we will use ideal body weight. The IBW application uses the Devine formula to calculate the ideal body weight:
- Ideal Body Weight (men) = [50kg + 2.3kg * ( Height(in) – 60 inches )]
- Ideal Body Weight (women) = [45.5kg + 2.3kg *( Height(in) – 60 inches )]
A screenshot of the Ideal Body Weight CDS application is presented below.
The IBW guideline (IBW.v1) is composed of three different archetypes:
The height.v1 archetype contains patient height (quantity data element), and the basic_demographic.v1 archetype contains patient gender (text data element). The IBW guideline uses the patient gender to determine which of the two formulas to calculate, and the patient height as input for the equation. The resulting value is then stored in the ideal_body_weight.v1 (quantity data element) archetype along with the correct unit. It is this archetype that we are going to model in this guide. All of the archetypes can be downloaded and tested by forking our common-clinical-models repository on GitHub.
Upon launching the openEHR Archetype Editor, the start-up menu below will automatically be displayed. Choose the proper component and fill in the short concept label as shown below.
Create the archetype:
- Choose OBSERVATION from the Component drop-down menu.
- Name the archetype in the Short concept label box.
- Click OK to create the archetype.
Recall from the archetype introduction guide that observation archetypes are used to document and store data components and values related to a clinical concept that can be observed or gathered at a specific point in time.
To add data elements to the archetype, head directly to the Definition tab. The first data element we are going to add is the quantity data element. Follow the instructions illustrated below to perform this task.
Add quantity element:
- Drag and drop the Q (quantity element) from the toolbar into the main modelling area.
- Name the element: “Ideal Body Weight”.
- Enter a description of the element – in this case, a description of the Devine formula used for calculating IBW has been added.
- From the Property drop-down menu, choose Mass.
- Use the plus button to add both kg and Ib as units of mass.
The reason for choosing the quantity data element for the ideal body weight is that it must be able to store both a value (integer or float data type) AND units (kg or lb). The quantity data element is the only option that meets those requirements.
Next, we are going to add a text element.
Add text element:
- Drag and drop the T (text element) from the toolbar into the main modelling area.
- Name the element: “Comment”.
- Enter description of the element – in this case, additional information that could not be captured in other fields.
- Select the option Free text or coded to make the data element function as a text box where the user can enter additional information regarding the calculation of ideal body weight.
Once all the data elements have been added, a structured overview of the newly added content can be viewed under the Terminology tab along with the assigned at-codes:
It is highly recommended to use this tab when translating the data elements of the archetype at a later stage.
Lastly, click on the Interface tab to view an interactive graphical user interface of the finished archetype. The calculated ideal body weight result can be entered in the numerical field and the appropriate units can be selected from the accompanying drop-down menu:
Additionally, a Comment text box is available into which the user can enter free text about the calculation of the ideal body weight:
After this step has been completed, the foundation of the CDS application has been laid. Now, all that remains is the metadata. After the metadata has been added, we are ready to design the Ideal Body Weight guideline (IBW.v1) using Cambio Healthcare Systems GDL Editor.
Once the archetype has been modelled, detailed information about the model – metadata – should be added to the archetype. This provides the user with key facts about the clinical concept related to the specific model.
To add metadata, begin in the Header tab by writing a short summary of the clinical concept in the Description box as shown below. The Concept can also be adjusted if needed.
To add additional information about the clinical concept to the archetype model, go to the Description tab (indicated by the thick arrow in the screenshot below) where the following sections should be filled in: Purpose, Use, Misuse, Copyright, and References.
- In the Purpose section, enter a descriptive text explaining the purpose of the clinical concept.
- In the Use section, detailed information regarding the clinical concept can be inserted. In this case – how the ideal body weight is calculated for men and women respectively along with some additional information. When applicable, information on score interpretation and clinical significance should also be added here.
- The Misuse section should contain information on potential misuse of the archetype. If there are any restrictions on the use of the archetype in specific settings or contexts, they should be entered here.
- Select Author draft from the drop-down menu on Authorship lifecycle since the archetype is under development.
- Insert copyright if relevant.
- Add keywords using the + button.
- Save the model.
The next subtab is the Authorship tab. This is where contact details of the author should be added – shown at number 1 on the image:
If there are several modellers working on the archetype, they should be added as Contributors:
2. Click on the + button.
3. Enter the name of the contributor.
4. Click OK to accept the entry.
Lastly, open the References/other details tab to access an overview of the underlying sources of the archetype. The references relevant to Ideal Body Weight are listed below:
The final result: