GDL Guideline Tutorial V – FLIPI – Guideline Definition Language (GDL)

1. Start a new guideline, import the archetypes, and name the new guideline as "Lymphoma International Prognostic Score".

To start to create the guideline, open the GDL Editor if not already open (if help needed refer to the previous chapters).
Import all archetypes by importing archetypes.zip file
If you have another guideline open, click on the Create New Guideline item in the menu to start an empty guideline.
Import all archetypes by importing archetypes.zip file
Fill in the Description tab. You need to fill in the name of the guideline and author’s name. The other fields are optional, but recommended, unless you use it for your own learning purposes only. A possible fill can be seen in the screenshot.

The description tab of the Follicular Lymphoma International Prognostic Score guideline

The description tab of the Follicular Lymphoma International Prognostic Score guideline. You need to fill in the name of the guideline and author's name (both marked with red box). The other fields are optional, but recommended, unless you use it for your own learning purposes only. A possible fill can be seen in the screenshot, optional fields marked with yellow box.

2. Instantiate Follicular Lymphoma international prognostic index (with elements >4 nodal sites, LDH elevated and Stage III-IV), Basic demography (with element Birthdate) and Lab test full blood count (with element Haemoglobin) as inputs, and Lymphoma international prognostic index (with all subscores), Basic demography (with element Age) as outputs.

First, instantiate the input archetypes by dragging every time the Archetype instantiation button to the Input entities field and choosing the relevant archetype.
In the Follicular Lymphoma international prognostic index archetype (openEHR-EHR-OBSERVATION.follicular_Lymphoma_international_prognostic_index) instantiate the following elements: >4 nodal sites, LDH elevated and Stage III-IV
In the Basic demography (openEHR-EHR-OBSERVATION.basic_demography) archetype instantiate the Birthdate element
In the Lab test full blood count (openEHR-EHR-OBSERVATION.lab_test-full_blood_count) archetype instantiate the Haemoglobin element.
After instantiating all the elements you should see the same screen as in the screenshot. If confused, skip to the next steps instantiating the output archetypes and elements, and then come back to this step following the details there.

Screenshot showing all inputs (archetypes and elements) to be instantiated

Screenshot showing all inputs (archetypes and elements) to be instantiated. The guideline needs three archetypes to be instantiated: openEHR-EHR-OBSERVATION.follicular_Lymphoma_international_prognostic_index (with elements >4 nodal sites, LDH elevated and Stage III-IV), openEHR-EHR-OBSERVATION.basic_demography (with element Birthdate) and openEHR-EHR-OBSERVATION.lab_test-full_blood_count (with element Haemoglobin). If confused, skip to the next steps instantiating the output archetypes and elements, and then come back to this step following the details there.
Add a new empty archetype to the output by dragging the Archetype instantiation button to the Output entities field.
Click on the Data binding label
You will see the dialog box shown in the screenshot, after dragging the Archetype instantiation to the outputs field and clicking on the Data binding label. Search for basic_demography archetype by entering part of its name into the Filter input field. From the search results choose openEHR-EHR-OBSERVATION.basic_demography (the archetype without anything after “demography”) and then click on the check mark to confirm your selection.

Adding Basic demography archetype to the outputs

Adding Basic demography archetype to the outputs. You will see the dialog box shown in the screenshot, after dragging the Archetype instantiation to the outputs field and clicking on the Data binding label. Search for basic_demography archetype by entering part of its name into the Filter input field (green box). From the search results choose the correct one (highlighted with a yellow box, the archetype without anything after "demography") and then click on the check mark (red box) to confirm your selection.
Drag the Element instantiation button to the newly created archetype instance.
Click on the Element label.
You will see the dialog box shown in the screenshot. Select Age element and then click on the check mark to confirm your selection.

Adding Age to the Basic demography archetype

Adding Age to the Basic demography archetype. You will see the dialog box shown in the screenshot, after dragging the Element instantiation to the Basic demography archetype and clicking on the Element label. Select Age element (highlighted with a yellow box) and then click on the check mark (red box) to confirm your selection.
Add yet another empty archetype to the output by dragging the Archetype instantiation button to the Output entities field and then click on the Data binding label
You will see the dialog box shown in the screenshot. Search for follicular_Lymphoma_international_prognostic_index archetype by entering part of its name into the Filter input field. From the search results choose the correct one (the archetype within the OBSERVATION category) and then click on the check mark to confirm your selection.

Adding Follicular Lymphoma Prognostic Index archetype to the outputs

Adding Follicular Lymphoma Prognostic Index archetype to the outputs. You will see the dialog box shown in the screenshot, after once again dragging the Archetype instantiation to the outputs field and clicking on the Data binding label. Search for follicular_Lymphoma_international_prognostic_index archetype by entering part of its name into the Filter input field (green box). From the search results choose the correct one (highlighted with a yellow box, the archetype within the OBSERVATION category) and then click on the check mark (red box) to confirm your selection.
Drag the Element instantiation button to the newly created archetype instance.
Click on the Element label.
You will see the dialog box shown in the screenshot. Select Age element and then click on the check mark to confirm your selection.

Adding Age subscore to the Lymphoma International Prognostic Index archetype

Adding Age subscore to the Lymphoma International Prognostic Index archetype. You will see the dialog box shown in the screenshot, after dragging the Element instantiation to the Lymphoma International Prognostic Index archetype and clicking on the Element label. Select Age > 60 years element (highlighted with a yellow box) and then click on the check mark (red box) to confirm your selection.
Similarly to Age, you should instantiate the subscore Hemoglobin <120 g/L or 12 g/dL as well. After the instantiation you should see the following screen.

All subscores initiated in the Lymphoma International Prognostic Index archetype

The Hemoglobin <120 g/L or 12 g/dL subscore initiated in the Lymphoma International Prognostic Index archetype similarly to the Age subscore.
After adding all subscores, you should instantiate the total score. Drag the Element instantiation button to the Lymphoma International Prognostic Index archetype and then click on the Element label.
You will see the same dialog box as in the previous instantiations. Select Total score element and then click on the check mark to confirm your selection.

Adding Total score to the Lymphoma International Prognostic Index archetype

Adding Total score to the Lymphoma International Prognostic Index archetype. After adding all subscores, you should instantiate the total score. You will see the dialog box shown in the screenshot, after dragging the Element instantiation to the Lymphoma International Prognostic Index archetype and clicking on the Element label. Select Total score element (highlighted with a yellow box) and then click on the check mark (red box) to confirm your selection.
After finishing all instantiation by adding Total score, you should see the following screen.

The complete definition tab

The complete definition tab. After finishing all instantiation by adding Total score, you should see the following screen.

3. Add a rule called Calculate age, which checks whether Birthdate is present among the inputs, and then calculates age as the difference of the years between the current year and the year of birth.

Open the Rule list tab.
Create a new rule by clicking on the Add new rule label and typing its name: Calculate age.
Add a condition to the new rule. To start creating a condition for the first rule, add an Element existence condition by dragging the button to the Rule conditions field.

First steps of creating a condition for the first rule

First steps of creating a condition for the first rule. To start creating a condition for the first rule, add an Element existence condition by dragging the button (red box) to the Rule conditions field (yellow box).
To continue, click on the Element label to choose which Element to be checked for existence.

Second step of creating a condition for the first rule

Second step of creating a condition for the first rule. To continue, click on the Element label (red box) to choose which Element to be checked for existence.
A dialog box will show up to choose the element to be checked for existence. You should choose “Birthdate” and confirm your selection by clicking the check mark.

Dialog box to choose the element to be checked for existence

Dialog box to choose the element to be checked for existence. You should choose "Birthday" (highlighted with yellow box) and confirm your selection by clicking the check mark (red box).
Choose “exists” in the drop-down list inside the condition.
After finishing the previous steps, you should see the following screenshot.

The complete condition for the first rule

The complete condition for the first rule. After finishing the previous steps, you should see the following screenshot, in the drop-down list "exists" should be selected (this also corresponds to the default selection).
Add an Attribute set rule by dragging the Set Attribute to Rule Actions field.
Click on the Element label.
The usual dialog box will appear to choose the element to be set by the first rule action. You should first choose “@unit” below the Age element, and confirm your selection by clicking the check mark.

Dialog box to choose the element to be set by the first rule action

Dialog box to choose the element to be set by the first rule action. You should choose "@unit" (highlighted with yellow box) below the Age element, and confirm your selection by clicking the check mark (red box).
Click on the “Constant” label.
This will show the dialog box shown in the screenshot. Choose “a” (corresponding to “years” as unit) from the drop-down list and then click on the check mark to confirm your choice.

Dialog box to choose the unit for Age

Dialog box to choose the unit for Age. First, click on the "Constant" label, this will show the dialog box shown in the screenshot. Choose "a" from the drop-down list (yellow box) and then click on the check mark (red box) to confirm your choice.
Add another Attribute set rule to set the magnitude of the calculated age. Now, choose “@magnitude” below the Age element in the corresponding dialog box.

Dialog box to choose the element to be set by the second rule action

Dialog box to choose the element to be set by the second rule action. You should choose "@magnitude" (highlighted with yellow box) below the Age element, and confirm your selection by clicking the check mark (red box).
Now, after clicking the Expression label, the expression editor will show up as you can see in the screenshot.
You can edit the expression on the left side of the dialog box. You should double click @year below Age. After double clicking it, the [Birthdate].year expression shows up in the expression editor. You should add “$currentDateTime.year” and a minus sign (-) at the begining of the expression. Pay attention not to miss the “$” sign at the begining of the expression. The complete expression means, that age is calculated as the difference of the current year and the birthdate’s year. This is a first order approximation of calculating age, a more complex calculationis introduced in a later chapter. You should confirm the expression by clicking the check mark.

Expression editor for the first rule action

Expression editor for the first rule action. After clicking the "Expression" label, this dialog box shows up. You can edit the expression on the left side of the dialog box. You should double click @year below Birthdate (highlighted with a yellow box). After double clicking it, the [The code of the variable|Birthdate].year expression shows up in the expression editor. You should add "$currentDateTime.year" and a minus sign (-) at the beginning of the expression (the complete expression highlighted in a green box). Pay attention not to miss the "$" sign at the beginning of the expression. The complete expression means, that age is calculated as the difference of the current year and the birthday's year. This is a first order approximation of calculating age, a more complex calculations introduced in a later chapter. You should confirm the expression by clicking the check mark (red box).

4. Add two rules which set the Age subscore according to the patient's age.

First, add a new rule named “Set Age – No” corresponding to the case when patient is below 60 years. Click on the Add new Rule label, type the name “Set Age – No” and confirm by clicking the check mark.
Instantiate a constant comparision condition, then click on the Element label.
In the usual dialog box, select Age inside the OBSERVATION group, and confirm your selection by clicking the check mark.

Dialog box to choose the element to be compared for the second rule condition

Dialog box to choose the element to be compared for the second rule condition. After you have instantiated a constant comparison condition, you should select Age to be compared. Select Age (highlighted with a yellow box) inside the OBSERVATION group, and confirm your selection by clicking the check mark (red box).
Select “<=” in the drop-down list and choose 60 as the value for comparison.
After finishing all the steps for adding the second rule condition, you should see the same condition as in the screenshot.

The complete condition for the second rule

The complete condition for the second rule. After finishing all the steps for adding the second rule condition, you should see the same condition (highlighted with a red box).
Instantiate a Set Element rule, then click on the Element label.
In the dialog box, you should choose “Age > 60 years” in the OBSERVATION group, and confirm your selection by clicking the check mark.

Dialog box to choose the element to be set by the second rule action

Dialog box to choose the element to be set by the second rule action. You should choose "Age > 60 years" (highlighted with a yellow box) in the OBSERVATION group, and confirm your selection by clicking the check mark (red box).
Click on the Value label and in the dialog box select “0 – No” in the drop-down list, and confirm your selection by clicking the check mark.

Dialog box to select the value for the second rule action

Dialog box to select the value for the second rule action. You should select "0 - No" in the drop-down list (highlighted with a yellow box), and confirm your selection by clicking the check mark (red box).
Create another very similar rule corresponding to the case when the patient is over 60 years. Name it “Set Age – Yes”. The difference here is that the relation in the constant comparision is “>”, and the Value in the rule action should be “1 – Yes”
The other rule can be seen in the following screenshot.

The complete third rule

The complete third rule. The name of the rule is "Set Age - yes" (highlighted with red box). It contains a Constant comparison condition (highlighted with a green box), whether the Age (calculated in the first rule) is above 60 years. If this is satisfied, the rule action is to set the "Age > 60 years" output element (the subscore corresponding to the age) to "1 - Yes".

5. Add rules setting the Haemoglobin subscore according to the patient's haemoglobin lab results.

Similarly, as in the previous step, add a new rule named “Set Haemoglobin – No” and instantiate a constant comparison condition.
In the condition, set the element to be Haemoglobin, the relation to “greater or equal”, and the constant value to compare with to 120 gm/l.
After setting all parameters, you should see the same as in the screenshot.

The complete condition for the forth rule

The complete condition for the forth rule. After dragging the Constant comparison button (green box) you should set the condition parameters as seen in the red box. Element should be set to Haemoglobin, relation to "greater or equal", and the constant value to compare with to 120 gm/l.
Instantiate a Set Element rule, then click on the Element label.
In the dialog box, you should choose “Hemoglobin < 120 g/L or 12 g/dL” in the OBSERVATION group, and confirm your selection by clicking the check mark.

Dialog box to choose the element to be set by the forth rule action

Dialog box to choose the element to be set by the forth rule action. You should choose "Hemoglobin < 120 g/L or 12 g/dL" element (highlighted with a yellow box), and confirm your selection by clicking the check mark (red box).
Click on the Value label and in the dialog box select “0 – No” in the drop-down list, and confirm your selection by clicking the check mark.

Dialog box to select the value for the forth rule action

Dialog box to select the value for the forth rule action. You should select "0 - No" in the drop-down list (highlighted with a yellow box), and confirm your selection by clicking the check mark (red box).
Create another very similar rule corresponding to the case when the patient is over 60 years. Name it “Set Haemoglobin – Yes”. The difference here is that the relation in the constant comparision is “<“, and the Value in the rule action should be “1 – Yes”
The other rule can be seen in the following screenshot.

The complete fifth rule

The complete fifth rule. The name of the rule is "Set Haemoglobin - yes" (highlighted with red box). It contains a Constant comparison condition (highlighted with a green box), whether the Haemoglobin level is below 120 g/L. If this is satisfied, the rule action is to set the "Hemoglobin < 120 g/L or 12 g/dL" output element (the subscore corresponding to the haemoglobin) to "1 - Yes".

6. Add a last rule summing the subscores to the Total score (checking Element Existence).

Add a new rule named “Calculate Total Score”.
Add an Element existence condition for the “>4 nodal sites” element by dragging the Element Existence button to the Rule conditions field and setting the Element to “>4 nodal sites”.

Adding the first Element existence condition to the rule

Adding the first Element existence condition to the rule. Drag the Element existence button (red box) to the Rule conditions field (yellow box).

Assigning the first Element existence condition

Assigning the first Element existence condition. To finish creating the condition click on the Element label (red box) and choose the ">4 nodal sites" input element. Make sure as well that in the drop-down list within the condition "exists" is selected.
Add Element existence condition for the other inputs as well. It is needed as the Editor has to make sure that all inputs used in the following rule are available.

Element existence conditions to the Total score rule

All the necessary Element existence conditions (highlighted with a red box).
Add a Set Attribute rule action to the rule, which will sum up the subscores to a Total score.
Set the Element in the usual Choose Element dialog box. You should choose “@magnitude” below “Total score” element, and confirm your selection by clicking the check mark.

Dialog box to choose the attribute to be set by the last rule action

Dialog box to choose the attribute to be set by the last rule action. You should choose "@magnitude" below "Total score" element (highlighted with a yellow box), and confirm your selection by clicking the check mark (red box).
Edit the expression in the expression editor after clicking the “Expression” label. You can edit the expression on the left side of the dialog box. You should double click each @value attribute below “>4 nodal sites”, “Stage III-IV”, “LDH elevated”, and “Haemoglobin” elements and add a “+” sign between the attributes. After double clicking an attribute, the respective [Element].value expression shows up in the expression editor, where you should type in the “+” character. You should add a “+” sign between attributes, indicating that you wish to sum the subscores. After including all subscores in the expression, check if it is the same as in the screenshot, then confirm the expression by clicking the check mark.

Expression editor for the last rule action

Expression editor for the last rule action. After clicking the "Expression" label, this dialog box shows up. You can edit the expression on the left side of the dialog box. You should double click @value attribute below ">4 nodal sites", "Stage III-IV", "LDH elevated", and "Haemoglobin" elements (some of them highlighted with a yellow box). After double clicking it, the respective [Element].value expression shows up in the expression editor. You should add a "+" sign between attributes, indicating that you wish to sum the subscores. After including all subscores in the expression, yous should confirm the expression by clicking the check mark (red box).

7. Check your guideline in the Execution tab.

Now, you are done with your guideline, but first make a quick check that everything works fine.

Open the Execution tab.
Fill in all input values with a relevant number.
Click on the Execution button (red box on the screenshot).
The output will be displayed in the corresponding field (green box). It is also possible to copy the results as a test case to the Test tab by giving a name to the test case (blue box) and then clicking the Add test fixture button (brown box).

Checking your guideline in the Execution tab

Checking your guideline in the Execution tab. Fill in all the input values in the field (yellow box), specifiying a random time and date for all Event time inputs, then click the Execution button (red box). The output will be displayed in the corresponding field (green box). It is also possible to copy the results as a test case to the Test tab by giving a name to the test case (blue box) and then clicking the Add test fixture button (brown box).

8. Save your guideline.

If everything works as intended, we recommend to save your guideline.
Save your guideline with the name “FLIPI.v1”

9. Test your guideline with a test file.

You can always export the Execution results into the Test tab, but it is also possible to use a previously prepared test file. Here we will use the already made test file, available in the GDL2 library or directly downloadable here.

Open the Test tab
To start to load a test file click on the Load button in the Test tab

Screenshot about loading a test file

Screenshot about loading a test file. To start to load a test file click on the Load button (red box) in the Test tab.
You will see a dialog box. Click on the Upload file button. Then choose the test file you want to use.

Dialog box when loading a test file

Dialog box when loading a test file. After clicking the load button a dialog box will show up, click on the Upload file button (red box). Then choose the test file you want to use.
This will load the test file. The content of the loaded test file will show up in the Test fixture field.

The loaded test file

The loaded test file. The content of the loaded test file will show up in the Test fixture field. You can Execute the test file by clicking on the Execute button.
You can Execute the test file by clicking on the Execute button.
The result of the test will show up in the Test result field. If everything is alright, you should have all test results passed and ideally you should have tested 100% of the rules.

The result of the test

The result of the test. After executing the test file, you should see the results in the Test result field (highlighted with a red box). If everything is alright, you should have all test results passed and ideally you should have tested 100% of the rules.

GDL2 Guideline Tutorial V – FLIPI (updated)