GDL2 Guideline Tutorial V – FLIPI

A common procedure in healthcare to calculate scores from clinical presentation and other health parameters. This scores then can be used to prioritize patients, to define patient groups, to calculate mortality or other risks. This and the next chapter explains how to create guidelines calculating these scores using the example of the Follicular Lymphoma International Prognostic Score and the successive assessment determining the patient group and mortality risk from the previously calculated score.

The Follicular Lymphoma International Prognostic Score – as many other scores in medicine – is made up by summing subscores to a total score. In this case, there are 5 subscores, which can be either 1 or 0 dependending if the patient is considered being in the risk group according to each criteria. The criteria here are:

  • Haemoglobin below 120 mg/L
  • Elevated LDH
  • Age over 60 years
  • Whether the patient is considered being in Stage III or IV, where stage III is a disease involves both sides of the diaphragm, including one organ or area near the lymph nodes or the spleen. In stage IV, diffuse or disseminated involvement of one or more extranodal organs is present, with or without associated lymph node involvement.
  • More than 4 nodal sites

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 Birthday) 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 Birthday element
  • In the Lab test full blood count (openEHR-EHR-OBSERVATION.lab_test-full_blood_count) archetype instantiate the Haemoglobin element.
  • Add Event time element for all input archetypes.
  • 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 Birthday) and openEHR-EHR-OBSERVATION.lab_test-full_blood_count (with element Haemoglobin). All elements have to be the latest, therefore Event time element should be also instantiated and Event time max predicates have to be added. 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 other subscores you can find in the Lymphoma International Prognostic Index archetype: these are >4 nodal sites, LDH elevated, Hemoglobin <120 g/L or 12 g/dL, and Stage III-IV.
  • -After all instantiation you should see the following screen.

    All subscores initiated in the Lymphoma International Prognostic Index archetype

    All subscores initiated in the Lymphoma International Prognostic Index archetype. Similarly to Age, you should instantiate the other subscores you can find in the Lymphoma International Prognostic Index archetype: these are >4 nodal sites, LDH elevated, Hemoglobin <120 g/L or 12 g/dL, and Stage III-IV.

  • 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 Birthday 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 label. 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 “Birthday” 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 [Birthday].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 athe birthday’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 Age (highlighted with a yellow box). After double clicking it, the [Birthday].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 rules to the three remaining subscores, setting them equal to the input.

  • Add a new rule named “Set >4 nodal sites”.
  • Add an element existence condition to this new rule, whether the “>4 nodal sites” input is set.
  • If you click on the Element label, the usual element selection dialog box will show up. You should choose “>4 nodal sites” element inside that observation which has an Event type element, as this is the input. There is another “>4 nodal sites” element, but it corresponds to the output element (and therefore not accompined with an Event Time element). Finally, confirm your selection by clicking the check mark sign. The selection is also shown in the screenshot.

    Dialog box to choose the element to be compared by the sixth rule condition

    Dialog box to choose the element to be compared by the sixth rule condition. You should choose ">4 nodal sites" element (highlighted with a yellow box). Pay attention that the element should be inside that observation (highlighted with a thin green box) which has an Event type element (highlighted with a thick green box), not the other one. Finally, confirm your selection by clicking the check mark (red box).

  • Add a rule action setting the “>4 nodal sites” output element (the subscore corresponding to the nodal sites) to the same value as the input. In this rule there are two “>4 nodal sites” element involved, one is the input and one is the output. The first part of the rule is the output, which you choose by clicking the Element label.
  • In the element selection dialog box, this time you should choose the “>4 nodal sites” element inside that observation which does not have an Event type element. You can check which element to choose in the following screenshot.

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

    Dialog box to choose the element to be set by the sixth rule action. You should choose ">4 nodal sites" element (highlighted with a yellow box), and confirm your selection by clicking the check mark (red box).

  • For the value, select the input “>4 nodal sites”. You can check which to choose on the following screenshot:

    Dialog box to choose the element to be compared by the sixth rule condition

    Dialog box to choose the element to be compared by the sixth rule condition. You should choose ">4 nodal sites" element (highlighted with a yellow box). Pay attention that the element should be inside that observation (highlighted with a thin green box) which has an Event type element (highlighted with a thick green box), not the other one. Finally, confirm your selection by clicking the check mark (red box).

  • -After finishing all the steps, you should see the same screen as in the following screenshot.

    The complete sixth rule

    The complete sixth rule. The name of the rule is "Set >4 nodal sites" (highlighted with red box). It contains an Element existence condition (highlighted with a yellow box), whether the ">4 nodal sites" input is set. If this is satisfied, the rule action is to set the ">4 nodal sites" output element (the subscore corresponding to the nodal sites) to the same value as the input. In this rule there are two ">4 nodal sites" element involved, the input highlighted with a green box and the output highlighted with a yellow box.

  • Similarly, add a rule copying the content of “LDH elevated” from the input to the output. The name of the rule should be “Set LDH elevated”. It should contain an Element existence condition, whether the “LDH elevated” input is set. If this is satisfied, the rule action is to set the “LDH elevated” output element to the same value as the input. As with the previous rule, in this rule there are two “LDH elevated” element involved, the input is used in the condition and in the Value of the action, while the output is used in the Element to be set in the action.

    The complete rule about the subscore for LDH subscore

    The complete rule about the subscore for LDH subscore. The name of the rule is "Set LDH elevated" (highlighted with red box). It contains an Element existence condition (highlighted with a yellow box), whether the "LDH elevated" input is set. If this is satisfied, the rule action (highlighted with a green box) is to set the "LDH elevated" output element (the subscore corresponding to the LDH) to the same value as the input. As with the previous rule, in this rule there are two "LDH elevated" element involved, the input is used in the condition and in the Value of the action, while the output is used in the Element to be set in the action.

  • Lastly, add a rule copying the content of “Stage III-IV” from the input to the output. The name of the rule is “Set Stage III-IV”. It should contain an Element existence condition, whether the “Stage III-IV” input is set. If this is satisfied, the rule action is to set the “Stage III-IV” output element to the same value as the input. As with the previous rule, in this rule there are two “LDH elevated” element involved, the input is used in the condition and in the Value of the action, while the output is used in the Element to be set in the action.

    The complete rule about the subscore for the Stage subscore

    The complete rule about the subscore for the Stage subscore. The name of the rule is "Set Stage III-IV" (highlighted with red box). Like the previous rules, it contains an Element existence condition (highlighted with a yellow box), whether the "Stage III-IV" input is set. If this is satisfied, the rule action (highlighted with a green box) is to set the "Stage III-IV" output element (the subscore corresponding to the LDH) to the same value as the input. As with the previous rule, in this rule there are two "Stage III-IV" element involved, the input is used in the condition and in the Value of the action, while the output is used in the Element to be set in the action.

7. Add a last rule summing the subscores to the Total score.

  • Add a new rule named “Calculate Total Score”.
  • 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).

8. 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.
  • -Fill in all Event time elements by choosing a random date and time.
  • -Click on the Execution button.
  • The output will be displayed in the corresponding field (green box) and can be copied to the Test tab.

    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) and can be copied to the Test tab. Pay attention that not everything is shown on the screen, you have to scroll down.

9. Save your guideline.

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

10. Test your guideline with a test file.

  • 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.

    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.