{"type":"doc","content":[{"type":"paragraph","content":[{"text":"Status: this page is in development.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"NOTE: In this page, we use the term ‘decision logic module’ (DLM) for convenience, and it should not be taken to be a permanent name. Other names such as ‘computerised guideline module’ (CGM), ‘clinical practice guideline’ (CPG) etc are also common.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#bf2600"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"The problem","type":"text"}]},{"type":"paragraph","content":[{"text":"The aim of this page is to describe the form of a ‘decision logic module’ (DLM) that can be used in at least the following scenarios:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Task Plans, to provide the subject data items and conditions required for decision branches;","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GDL3 guidelines, which in general will have more sophisticated rules, rule-sets, decision tables and so on;","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Form calculators, to provide a way to express the computations of derived fields in an application form, e.g. score-based forms.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Background","type":"text"}]},{"type":"paragraph","content":[{"text":"Recently we created a representation of an NHS CHOPS (chemotherapy) Guideline in the form of:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":" an openEHR Task Planning plan;","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"a ‘subject data set' (subject variables needed to execute rules);","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"a ‘decision support’ module containing rules.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"example may be found here","type":"text","marks":[{"type":"link","attrs":{"href":"https://specifications.openehr.org/releases/PROC/latest/tp_examples.html#_multi_drug_chemotherapy"}}]},{"text":". On this page, based on feedback from ","type":"text"},{"type":"mention","attrs":{"id":"557058:79e1fe9b-7822-4471-8370-76edb144a657","text":"@Rong Chen"}},{"text":" and ","type":"text"},{"type":"mention","attrs":{"id":"557058:fccd0e35-eeb9-49af-9c37-ee414c373af9","text":"@Ian McNicoll"}},{"text":" particularly taking account of GDL experiences to date, is a modified version of the second two parts. One thing Ian and Rong didn't like is my use of ","type":"text"},{"text":"P.bilirubins","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"P.heart_rate","type":"text","marks":[{"type":"code"}]},{"text":" etc to distinguish to ","type":"text"},{"text":"subject variables","type":"text","marks":[{"type":"em"}]},{"text":" from ","type":"text"},{"text":"rule symbols","type":"text","marks":[{"type":"em"}]},{"text":" in a rules module. I am not yet convinced it is a good idea to put all symbols in the same namespace, but for now, I've gone with that approach.","type":"text"}]},{"type":"paragraph","content":[{"text":"The version below is a progression in the evolution, not a final specification. Feedback is welcome.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Decision logic module","type":"text"}]},{"type":"paragraph","content":[{"text":"Task Plans and GDL3 guidelines both require a way of expressing rules and declaring input variables. Guidelines additionally need a way of declaring output variables. These needs are achieved with the flexible use of a single kind of multi-section module called a ","type":"text"},{"text":"decision logic module","type":"text","marks":[{"type":"strong"}]},{"text":" which has the following structure:","type":"text"}]},{"type":"codeBlock","content":[{"text":"dlm \n\n[language\n ]\n \n[description\n ]\n \n[use_model\n ]\n\n-- declare all supplier DLMs\n[use\n : \n : ]\n\n[preconditions\n ]\n \n[reference\n ]\n \n-- declare all variables needed by this DLM, including currency \ninput\n \n \nconditions\n \n \nrules\n \n \n[output\n ]\n \n[bindings\n ]","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Identifiers","type":"text"}]},{"type":"paragraph","content":[{"text":"All identifiers in a DLM are strings with no whitespace, and if the ","type":"text"},{"text":"terminology","type":"text","marks":[{"type":"code"}]},{"text":" section is present, these identifiers are included with linguistic definitions and translations, in the same way as archetypes.","type":"text"}]},{"type":"paragraph","content":[{"text":"Declarations in the ","type":"text"},{"text":"use","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"input","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"conditions","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"rules","type":"text","marks":[{"type":"code"}]},{"text":", and ","type":"text"},{"text":"output","type":"text","marks":[{"type":"code"}]},{"text":" sections create identifiers that may be used in other sections.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Identification","type":"text"}]},{"type":"paragraph","content":[{"text":"DLMs are identified internally using a string identifier of the form:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"openEHR-DLM..vN.N.N","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The final part represents a 3-part version identifier consisting of ","type":"text"},{"text":"major.minor.patch","type":"text","marks":[{"type":"code"}]},{"text":", which follows the ","type":"text"},{"text":"semver.org","type":"text","marks":[{"type":"link","attrs":{"href":"http://semver.org"}}]},{"text":" rules.","type":"text"}]},{"type":"paragraph","content":[{"text":"A reference to a DLM may be effected by quoting the whole identifier, or a form with the minor and / or patch parts of the version missing. Either of these forms identify the most recent matching DLm available. For example, the reference ","type":"text"},{"text":"openEHR-DLM.NHS-chops14.v4","type":"text","marks":[{"type":"code"}]},{"text":" identifies whatever the most recent minor version of the ","type":"text"},{"text":"v4","type":"text","marks":[{"type":"code"}]},{"text":" major version of the NHS-chops DLM is locally available. ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Formal Relationships","type":"text"}]},{"type":"paragraph","content":[{"text":"DLMs as currently conceived have the following formal relationships:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A DLM cannot ‘inherit’ from another DLM","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"a DLM can use other DLMs, by declaring each DLM with an identifier in the ","type":"text"},{"text":"use","type":"text","marks":[{"type":"code"}]},{"text":" section.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Uses","type":"text"}]},{"type":"paragraph","content":[{"text":"A DLM can be used in different ways to represent:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Plan context","type":"text","marks":[{"type":"strong"}]},{"text":": just a ","type":"text"},{"text":"data-set and Boolean conditions","type":"text","marks":[{"type":"em"}]},{"text":", as required for Task Plans;","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"re-usable Guideline","type":"text","marks":[{"type":"strong"}]},{"text":": that may be ","type":"text"},{"text":"referenced","type":"text","marks":[{"type":"em"}]},{"text":" by other DLMs, consisting of data set and rules, e.g. BMI, BSA calculators;","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A ","type":"text"},{"text":"top-level Guideline","type":"text","marks":[{"type":"strong"}]},{"text":": such as for CHOPS-14, consisting of input data set, rules; generally developed from a published guideline.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"An ","type":"text"},{"text":"in-form calculator","type":"text","marks":[{"type":"strong"}]},{"text":" that calculates values for fields derived from other directly input fields.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For these different usages, various sections are mandatory, and optional in others. For example, for deployment as a GDL3 guideline or an in-form calculator, the ","type":"text"},{"text":"bindings","type":"text","marks":[{"type":"code"}]},{"text":" section would be mandatory, whereas for Task Planning, it would not be used. ","type":"text"}]},{"type":"paragraph","content":[{"text":"A ‘raw’ form might be useful, which doesn’t include the sections ","type":"text"},{"text":"language","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code"}]},{"text":", or ","type":"text"},{"text":"terminology","type":"text","marks":[{"type":"code"}]},{"text":". This would allow DLMs to be developed with untranslated variables or other meta-data.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Deployment and Data Binding","type":"text"}]},{"type":"paragraph","content":[{"text":"The intention here is to define a single formalism that can be used flexibly for TP, GDL and other uses (e.g. forms with computational elements). The key semantic differences between the TP and GDL conceptual approach appear to be:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GDL guidelines are executed in a single-shot fashion; they may be re-executed multiple times (e.g. due to new events being notified), but each time is a new execution from scratch; there is no temporal aspect to the execution;","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"GDL subject data is defined by a ","type":"text"},{"text":"pre-defined custom structured data-set","type":"text","marks":[{"type":"strong"}]},{"text":", that contains all the data needed in the guideline, and the ‘variables’ are just mappings to paths within that;","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"for the TP scenario, there is in general no predefined data-set that can be created for one or more TP Work Plans; instead, each work plan references a set of variables it needs, and these are populated by the proxy service as the plan runs;","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"for a form calculator, the form data acts as the data set.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"These differences are shown in the deployment architectures for Task Planning and GDL below.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Task Planning","type":"text"}]},{"type":"paragraph","content":[{"text":"The following shows an operational (i.e. service) architecture for Task Planning, using DLMs to provide the data set and conditions for the Plan decision nodes.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":504,"id":"3603b1fc-4b48-4cde-ba25-c91c37f9cba6","collection":"contentId-842924037","type":"file","height":516}}]},{"type":"paragraph","content":[{"text":"Here, the Subject proxy service provides values for the variables (e.g. ","type":"text"},{"text":"systolic_blood_pressure","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"weight","type":"text","marks":[{"type":"code"}]},{"text":" etc) declared in the GDL3 dataset artefacts. It abstracts away the various source systems and data models / standards, and also tries to obtain needed data at the UI if it cannot be found in e.g. the EMR.","type":"text"}]},{"type":"paragraph","content":[{"text":"The TP engine receives notifications from the EHR indicating e.g. commit of new lab result, new patient creation etc.","type":"text"}]},{"type":"paragraph","content":[{"text":"Variables declared in a DLM input section of an executing guideline are registered in the Subject Proxy service at guideline load time.","type":"text"}]},{"type":"paragraph","content":[{"text":"A Plan context DLM only needs some of the DLM sections, as shown in this example:","type":"text"}]},{"type":"codeBlock","content":[{"text":"dlm simple_cardiology\n\nlanguage\n original_language = <[ISO_639-1::en]>\n \ndescription\n lifecycle_state = <\"stable\">\n original_author = <\n [\"name\"] = <\"Rong Chen\">\n [\"organisation\"] = <\"Acme healthcare\">\n [\"date\"] = <\"2020-03-22\">\n >\n details = <\n [\"en\"] = <\n\t language = <[ISO_639-1::en]>\n\t purpose = <\"Simple cariology example\">\n\t>\n >\n \ninput\n systolic_blood_pressure: Quantity\n currency = 1 min\n ranges = {\n high: |> 140 mm[Hg]|,\n normal: |> 80 mm[Hg] .. <= 140 mm[Hg]|,\n low: |<= 80 mm[Hg]|\n }\n\n resting_heart_rate: Quantity\n currency = 30 sec\n \n resting_heart_rhythm: CodedTerm\n currency = 30 sec\n \nconditions\n high_blood_pressure:\n Result <- systolic_blood_pressure.range = high\n \n heart_rate_irregular:\n Result <- resting_heart_rhythm != regular\n \nterminology\n term_definitions = <\n [\"en\"] = <\n [\"resting_heart_rate\"] = <\n text = <\"heart rate at rest\">\n description = <\"...\">\n >\n ...\n [\"heart_rate_irregular\"] = <\n text = <\"heart rate is irregular\">\n description = <\"...\">\n >\n >\n >","type":"text"}]},{"type":"paragraph","content":[{"text":"This provides 3 variables (","type":"text"},{"text":"systolic_blood_pressure","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"resting_heart_rate","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"resting_heart_rhythm","type":"text","marks":[{"type":"code"}]},{"text":") and 2 conditions (","type":"text"},{"text":"high_blood_pressure","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"has_arrhythmia","type":"text","marks":[{"type":"code"}]},{"text":") that may be used in a Task Plan or other context.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"GDL3","type":"text"}]},{"type":"paragraph","content":[{"text":"The GDL3 architecture is somewhat different, being built around CDS-hooks notifications from the EHR environment. ","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":475,"id":"fc82a7e6-56e1-4518-a81c-6ea9069badc9","collection":"contentId-842924037","type":"file","height":394}}]},{"type":"paragraph","content":[{"text":"The GDL3 engine receives notifications from the EHR indicating e.g. commit of new lab result, new patient creation etc.","type":"text"}]},{"type":"paragraph","content":[{"text":"The subject variables (e.g. ","type":"text"},{"text":"weight","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"is_diabetic","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"neutrophils","type":"text","marks":[{"type":"code"}]},{"text":") defined in a GDL3 guideline DLM are mapped to paths within a custom dataset, which is the basis of data retrieval. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The custom data set thus needs to be defined for GSL e.g. as an openEHR ‘template’ that is retrieved at ‘load’ and possibly subsequent ‘execute’ points in time. The mappings are achieved with an ","type":"text"},{"text":"bindings","type":"text","marks":[{"type":"code"}]},{"text":" section at the bottom of the DLM, as shown below.","type":"text"}]},{"type":"codeBlock","content":[{"text":"dlm simple_cardiology\n\nlanguage\n original_language = <[ISO_639-1::en]>\n \ndescription\n lifecycle_state = <\"stable\">\n original_author = <\n [\"name\"] = <\"Rong Chen\">\n [\"date\"] = <\"2020-03-22\">\n >\n details = <\n [\"en\"] = <\n\t language = <[ISO_639-1::en]>\n\t purpose = <\"Simple cardiology guideline\">\n\t>\n >\n \ninput\n systolic_bp: Quantity\n currency = 1 min\n ranges = {\n high: |> 140 mm[Hg]|,\n normal: |> 80 mm[Hg] .. <= 140 mm[Hg]|,\n low: |<= 80 mm[Hg]|\n }\n\n heart_rate: Quantity\n currency = 30 sec\n \n heart_rhythm: CodedTerm\n currency = 30 sec\n \nrules\n ...\n \nterminology\n term_definitions = <\n [\"en\"] = <\n [\"heart_rate\"] = <\n text = <\"heart rate at rest\">\n description = <\"...\">\n >\n ...\n >\n >\n\nbindings\n datasets = <\n [\"Cardiology_dataset_4\"] = <\n dataset = <\"Cardiology_dataset_4\">\n bindings = <\n [\"systolic_bp\"] = <\"/vital_signs/blood_pressure/systolic\">\n [\"diastolic_bp\"] = <\"/vital_signs/blood_pressure/diastolic\">\n [\"heart_rate\"] = <\"/vital_signs/heart_rate\">\n [\"heart_rhythm\"] = <\"/vital_signs/heart_rhythm\">\n >\n >\n >","type":"text"}]},{"type":"paragraph","content":[{"text":"Questions: ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"how does ‘currency’ work in the custom dataset scheme?","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Form calculator","type":"text"}]},{"type":"paragraph","content":[{"text":"This scenario uses a DLM to define the rules / functions that calculate derived fields in a form from primary input fields. As such, it is deployed within the client application space, not the server side. It would presumably use a ","type":"text"},{"text":"bindings","type":"text","marks":[{"type":"code"}]},{"text":" section to map a set of local variables to form field paths or ids.","type":"text"}]},{"type":"paragraph","content":[{"text":"TBD","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"DLM Semantics","type":"text"}]},{"type":"paragraph","content":[{"text":"Apart from the data-set definition and binding, the rest of the semantic requirements appear to be the same for TP and GDL, i.e. to do with rule representation, handling null values, and so on. Some of these are dealt with below.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"External access","type":"text"}]},{"type":"paragraph","content":[{"text":"The above DLM structure allows a DLM to reference other DLM instances in the ","type":"text"},{"text":"use","type":"text","marks":[{"type":"code"}]},{"text":" section, each of which is locally identified by a convenient identifier. This allows the symbols of the referenced guideline to be accessed via the notation ","type":"text"},{"text":"local_id.symbol","type":"text","marks":[{"type":"code"}]},{"text":", e.g. ","type":"text"},{"text":"BSA.bsa_m2","type":"text","marks":[{"type":"code"}]},{"text":" to mean the symbol ","type":"text"},{"text":"bsa_m2","type":"text","marks":[{"type":"code"}]},{"text":" in a DLM referenced via the declaration ","type":"text"},{"text":"BSA: Body_surface_area","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Null value handling","type":"text"}]},{"type":"paragraph","content":[{"text":"One of the differences between the variables declared in the dataset and in the guideline is that the former values may potentially be null, assuming that no value was available from the Subject Proxy service (bearing in mind that it is responsible for trying to obtain missing data from live users in the circumstance where no data can be found in the EMR or other connected systems). Null data items could be handled two ways in guideline rules:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"guideline rules are written as if all variables are guaranteed to be non-null at time of execution;","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"guideline rules are written to handle null values.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Following the second option means that guideline rules have to continually check for values being defined, e.g. using a predicate check such as:","type":"text"}]},{"type":"codeBlock","content":[{"text":"atrial_fibrillation_risk: Coded_term\n if defined (heart_rate) and defined (heart_rhythm)\n -- expression using heart_rate, heart_rhythm\n else\n -- something else","type":"text"}]},{"type":"paragraph","content":[{"text":"This is likely to be cumbersome, and obscure the clarity of rules from an authoring point of view. Experience with guidelines over the years indicates that the vast majority of guidelines are executable only when values for their rule input variables are available. Nevertheless, some subject variables will be unavailable when a guideline is executed, e.g. test results that have a complex procedure (e.g. biopsy) or take time (e.g. micro culture), and for which missing data are handled in the guideline.","type":"text"}]},{"type":"paragraph","content":[{"text":"A practical approach is to declare such variables as potentially void within the data set declaration. This could be done in a similar way to modern programming languages, using a '?' to indicate a nullable variable, e.g.:","type":"text"}]},{"type":"codeBlock","content":[{"text":"input\n heart_rate: Quantity\n ejection_fraction: Quantity?","type":"text"}]},{"type":"paragraph","content":[{"text":"In the above, the ","type":"text"},{"text":"ejection_fraction","type":"text","marks":[{"type":"code"}]},{"text":" variable is declared as nullable, and within a guideline or in a plan, a null check like ","type":"text"},{"text":"if defined (ejection_fraction)","type":"text","marks":[{"type":"code"}]},{"text":" could be used. Behind the scenes, the ","type":"text"},{"text":"Quantity?","type":"text","marks":[{"type":"code"}]},{"text":" would translate to something like ","type":"text"},{"text":"Data_item","type":"text","marks":[{"type":"code"}]},{"text":", where ","type":"text"},{"text":"Data_item","type":"text","marks":[{"type":"code"}]},{"text":" is a wrapper type with the following definition:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"kotlin"},"content":[{"text":"class Data_item {\n value(): T {\n -- return either raw_value, or \n -- generate a reasonable value\n }\n\n is_null: boolean;\n null_reason: String[0..1];\n \n effective_time: Date_time[0..1];\n \n private raw_value: T?;\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"This achieves the same effect as the openEHR ","type":"text"},{"text":"Element","type":"text","marks":[{"type":"code"}]},{"text":" type, just in a simpler type system. This approach enables typical null-value rules to be defined, such that an expression such as ","type":"text"},{"text":"ejection_fraction > 20%","type":"text","marks":[{"type":"code"}]},{"text":" will not cause an exception even if the ","type":"text"},{"text":"ejection_fraction","type":"text","marks":[{"type":"code"}]},{"text":" raw value is null. Of course it is usually better to test for ","type":"text"},{"text":"defined (ejection_fraction)","type":"text","marks":[{"type":"code"}]},{"text":" first, if ","type":"text"},{"text":"ejection_fraction","type":"text","marks":[{"type":"code"}]},{"text":" was defined as ","type":"text"},{"text":"Quantity?","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"QUESTION: We might have to consider whether using the ‘?' declaration obscures the difference between a 'non-available’ variable (i.e. no value available from the outside world) and one that is simply null in the standard programming language sense. If we assume that the latter can happen within datasets and guidelines, we might want to allow both ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff5630"}}]},{"text":"Type?","type":"text","marks":[{"type":"code"}]},{"text":" and e.g. the use of the explicit type ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff5630"}}]},{"text":"Data_item","type":"text","marks":[{"type":"code"}]},{"text":" to distinguish the two cases.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#ff5630"}}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Effective time","type":"text"}]},{"type":"paragraph","content":[{"text":"Sometimes the clinically significant time of a data item needs to be accessed in rules. This can be done by the reference ","type":"text"},{"text":"x.effective_time","type":"text","marks":[{"type":"code"}]},{"text":", e.g. ","type":"text"},{"text":"ejection_fraction.effective_time","type":"text","marks":[{"type":"code"}]},{"text":" returns when the ejection fraction measurement being used was taken. For a variable like ","type":"text"},{"text":"is_diabetic","type":"text","marks":[{"type":"code"}]},{"text":", it means when the diagnosis was made.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Dataset meta-data / hints","type":"text"}]},{"type":"paragraph","content":[{"text":"In the dataset declarations below, variables are declared under a ","type":"text"},{"text":"input","type":"text","marks":[{"type":"code"}]},{"text":" keyword, which may have structured comments attached to it, e.g.:","type":"text"}]},{"type":"codeBlock","content":[{"text":"input -- \n\n date_of_birth: Date\n\ninput -- \n\n weight: Quantity\n currency = 7 days","type":"text"}]},{"type":"paragraph","content":[{"text":"In the above, there are two meta-data ‘hints’ to potentially be used by the Subject Proxy service to know how to formulate a data request or query. These include:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"time_window","type":"text","marks":[{"type":"code"}]},{"text":": a period denoted by either:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"a symbolic name: ","type":"text"},{"text":"“all” | “current episode” | “prior history”","type":"text","marks":[{"type":"code"}]},{"text":" each of which is convertible to an interval of the form ","type":"text"},{"text":"start = -D1, end = -D2","type":"text","marks":[{"type":"code"}]},{"text":", where D1 and D2 are Durations backward from the current moment.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"an explicit window formed by ","type":"text"},{"text":"|D1..D2|","type":"text","marks":[{"type":"code"}]},{"text":", where D1 and D2 have the same definitions as above.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"source","type":"text","marks":[{"type":"code"}]},{"text":": a name referring to a kind of data or system.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Dataset variable ‘currency’","type":"text"}]},{"type":"paragraph","content":[{"text":"Currency, i.e. how current a variable value is can be set on a dataset variable declaration, as can be seen in the example below. This is used by the Subject Proxy service to determine how often to renew the value (e.g. by reading an EMR, devices etc).","type":"text"}]},{"type":"paragraph","content":[{"text":"For GDL3, currency is performed as a check on recency of the effective clinical time of the dataset elements.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"not clear how this would work for vital signs, ICU, any real-time situation.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Dataset quantitative variable ‘ranges’","type":"text"}]},{"type":"paragraph","content":[{"text":"A set of ranges can be defined for a quantitative variable in a dataset, e.g.:","type":"text"}]},{"type":"codeBlock","content":[{"text":" systolic_blood_pressure: Quantity\n currency = 1 min\n ranges = {\n critical_high: |>= 180 mm[Hg]|,\n very_high: |> 140 mm[Hg]|,\n high: |> 120 mm[Hg]|,\n normal: |>90 mm[Hg] .. <= 120 mm[Hg]|,\n low: |<= 90 mm[Hg]|,\n critical_low: |<= 50 mm[Hg]|\n }","type":"text"}]},{"type":"paragraph","content":[{"text":"These ranges are understood to be those required by the guideline(s) / plan(s) using the data set, and may not be the standard laboratory ranges for a normal healthy person. The idea here is that given such a declaration, expressions like ","type":"text"},{"text":"systolic_blood_pressure.range = high","type":"text","marks":[{"type":"code"}]},{"text":" are now possible within rules. Here, ","type":"text"},{"text":".range","type":"text","marks":[{"type":"code"}]},{"text":" is understood as an argumentless function that converts the variable value to whichever range it falls in, a very common need in guidelines. It also allows decision branches in plans to be defined on the basis of such ranges.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Comments and documentation","type":"text"}]},{"type":"paragraph","content":[{"text":"I have changed the multi-line comment character to the vertical bar, as an experiment. Makes things nice to read. We could potentially consider that any text to the right of one of these bars is assumed to be in Asciidoc markdown or similar.","type":"text"}]},{"type":"paragraph","content":[{"text":"We might potentially consider annotations like in Java e.g. ","type":"text"},{"text":"@xxx","type":"text","marks":[{"type":"code"}]},{"text":" to mark various parts of documentation text for smart extractors.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Implementation","type":"text"}]},{"type":"paragraph","content":[{"text":"Implementation of the rules aspect of DLMs is likely to be relatively straightforward, since it is based on evaluation of statements and expressions that constitute value-returning rules.","type":"text"}]},{"type":"paragraph","content":[{"text":"The more challenging implementation question is to do with the subject dataset representation, and the Subject Proxy service.","type":"text"}]},{"type":"paragraph","content":[{"text":"The primary question here is how a variable access from either a Task Plan or a GDL3 guideline is effected. The use of a variable such as ","type":"text"},{"text":"is_diabetic","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"platelets","type":"text","marks":[{"type":"code"}]},{"text":" within an expression has to ultimately result in a value retrieval, either:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"(TP) from an intermediate cache which is populated by the Subject proxy component / service;","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"(GDL3) from the latest copy of the custom data set.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If we think of how it can work very concretely in the TP environment, using a Subject Proxy component, a symbolic reference like ","type":"text"},{"text":"is_diabetic","type":"text","marks":[{"type":"code"}]},{"text":" from within an expression being evaluated by an interpreter has to result in either a passive data access (like in a typical computer program execution) or a function call. In the former case, the symbol is effectively a data variable or property defined in some ‘class’ or module, and the connection between it and the data retrieval is undefined.","type":"text"}]},{"type":"paragraph","content":[{"text":"A more useful way to understand a variable reference could be as a function call from a local ‘proxy’ object. We could consider that the declaration above of ","type":"text"},{"text":"systolic_blood_pressure: Quantity","type":"text","marks":[{"type":"code"}]},{"text":" above, along with the ","type":"text"},{"text":"currency","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"ranges","type":"text","marks":[{"type":"code"}]},{"text":" really generates an instance of an object of a type such as ","type":"text"},{"text":"ProxyVarQuantity","type":"text","marks":[{"type":"code"}]},{"text":", which looks like this:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"kotlin"},"content":[{"text":"class Proxy_var {\n name: String\n \n currency: Duration\n \n value: T {\n // get the value, e.g. by a call like \n // subject_proxy.get_val(name, currency)\n }\n}\n\nclass Proxy_var_quantity extends Proxy_var {\n // map of named value ranges\n ranges: Map >\n \n // range in which the current value is\n range: Terminology_code {\n // return which range in 'ranges' value is in\n }\n\n // range in which the current value is\n in_range (a_range: Terminology_code): Boolean {\n // return True if range = a_range\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"In an expression such as ","type":"text"},{"text":"platelets < 60 x 10^9/L","type":"text","marks":[{"type":"code"}]},{"text":" , the ","type":"text"},{"text":"platelets","type":"text","marks":[{"type":"code"}]},{"text":" reference is understood as a call to ","type":"text"},{"text":"Proxy_var_quantity.value","type":"text","marks":[{"type":"code"}]},{"text":", which retrieves the actual value (it would require an internal reference to the Subject Proxy to do this). In an expression like ","type":"text"},{"text":"platelets.in_range (low)","type":"text","marks":[{"type":"code"}]},{"text":" , the ","type":"text"},{"text":"platelets.in_range()","type":"text","marks":[{"type":"code"}]},{"text":" is a call to ","type":"text"},{"text":"Proxy_var_quantity.in_range()","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]},{"type":"paragraph","content":[{"text":"According to this scheme, the execution of the declarations of ","type":"text"},{"text":"is_diabetic","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"platelets","type":"text","marks":[{"type":"code"}]},{"text":" causes creation of ","type":"text"},{"text":"Proxy_var_xxx","type":"text","marks":[{"type":"code"}]},{"text":" objects that have access to the Subject Proxy data cache by making calls like ","type":"text"},{"text":"get_value(“is_diabetic”)","type":"text","marks":[{"type":"code"}]},{"text":" or perhaps typed calls like ","type":"text"},{"text":"get_quantity_value(“platelets”)","type":"text","marks":[{"type":"code"}]},{"text":". How the Subject Proxy gets its data depends on the bindings of named variables like ","type":"text"},{"text":"is_diabetic","type":"text","marks":[{"type":"code"}]},{"text":" to back-end binding meta-data such as AQL queries (for openEHR access), HL7 FHIR calls/resources for FHIR, and whatever other methods are available for other kinds of data source.","type":"text"}]},{"type":"paragraph","content":[{"text":"When a ","type":"text"},{"text":"Proxy_var","type":"text","marks":[{"type":"code"}]},{"text":" object is created, it would need to register the named variable, type, currency and possible the ‘hint’ meta-data described earlier, in the Subject Proxy component, for the current patient. ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reworked Example","type":"text"}]},{"type":"paragraph","content":[{"text":"The following is the example referenced at the top of the page reworked as a small number of DLMs, as described on this page.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Core patient state dataset","type":"text"}]},{"type":"codeBlock","content":[{"text":"dlm Core_patient_DS\n\nlanguage\n original_language = <[ISO_639-1::en]>\n \ndescription\n lifecycle_state = <\"unmanaged\">\n original_author = <\n [\"name\"] = <\"Dr Spock\">\n [\"organisation\"] = <\"Acme healthcare\">\n [\"date\"] = <\"2020-03-22\">\n >\n details = <\n [\"en\"] = <\n\t language = <[ISO_639-1::en]>\n\t purpose = <\"Core patient state ...\">\n\t>\n >\n \ninput -- \n date_of_birth: Date\n\n sex: Terminology_term\n\ninput -- \n weight: Quantity\n currency = 7 days\n\n height: Quantity\n\n blood_glucose: Quantity\n currency = 2 hour\n\n is_type1_diabetic: Boolean\n\ninput -- \n\n systolic_blood_pressure: Quantity\n currency = 1 min\n ranges = {\n [critical_high]: |>= 180 mm[Hg]|,\n [very_high]: |> 140 mm[Hg]|,\n [high]: |> 120 mm[Hg]|,\n [normal]: |>90 mm[Hg] .. <= 120 mm[Hg]|,\n [low]: |<= 90 mm[Hg]|,\n [critical_low]: |<= 50 mm[Hg]|\n }\n\n diastolic_blood_pressure: Quantity\n currency = 1 min\n ranges = {\n [high]: |> 80 mm[Hg]|,\n [normal]: |>60 mm[Hg] .. <= 90 mm[Hg]|,\n [low]: |<= 60 mm[Hg]|\n }\n\n resting_heart_rate: Quantity\n currency = 30 sec\n ranges = {\n [critical_high]: |>= 140 /min|,\n [high]: |>= 90 /min|,\n [normal]: |>55 /min .. < 90 /min|,\n [low]: |<= 55 /min|,\n [critical_low]: |<= 39 /min|\n }\n\n oxygen_saturation: Proportion\n currency = 30 sec\n ranges = {\n [low]: |< 92%|\n }\n\nrules\n age: Duration\n Result <- {Env}.current_date() - date_of_birth\n \nterminology\n term_definitions = <\n [\"en\"] = <\n [\"date_of_birth\"] = <\n text = <\"Date of birth\">\n description = <\"Date of birth of subject\">\n >\n [\"sex\"] = <\n text = <\"biological sex\">\n description = <\"Biological sex of subject.\">\n >\n [\"systolic_blood_pressure\"] = <\n text = <\"systolic blood pressure\">\n description = <\"Instantaneous systolic blood pressure (lying).\">\n >\n [\"is_type1_diabetic\"] = <\n text = <\"Type I diabetic status of subject\">\n description = <\"Subject has confirmed diagnosis of type I ...\">\n >\n [\"bmi\"] = <\n text = <\"Body mass index\">\n description = <\"Subject body mass index.\">\n >\n [\"...\"] = <\n text = <\"...\">\n description = <\"...\">\n >\n >\n >","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Reusable Guidelines","type":"text"}]},{"type":"codeBlock","content":[{"text":"dlm Body_surface_area \n\nlanguage\n original_language = <[ISO_639-1::en]>\n \ndescription\n lifecycle_state = <\"unmanaged\">\n original_author = <\n [\"name\"] = <\"Dr Spock\">\n [\"organisation\"] = <\"Acme healthcare\">\n [\"date\"] = <\"2020-03-22\">\n >\n details = <\n [\"en\"] = <\n\t language = <[ISO_639-1::en]>\n\t purpose = <\"Body serface area - Mosteller Formula\n \tBSA = sqrt (weight[kg] x height (m) / 36)\n\t \">\n\t>\n >\n \nreference\n Mosteller_constant: Integer = 36\n \ninput\n weight: Quantity\n currency = 7 days\n\n height: Quantity\n\nrules\n bsa_m2: Real\n Result <- {Math}.sqrt (weight * height / Mosteller_constant)\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"The CHOPS guideline","type":"text"}]},{"type":"paragraph","content":[{"text":"The following is the GDL3 guideline (i.e. ruleset) for CHOPS-21.","type":"text"}]},{"type":"codeBlock","content":[{"text":"dlm RCHOPS21 \n\nlanguage\n original_language = <[ISO_639-1::en]>\n \ndescription\n lifecycle_state = <\"unmanaged\">\n original_author = <\n [\"name\"] = <\"Dr Spock\">\n [\"organisation\"] = <\"Acme healthcare\">\n [\"date\"] = <\"2020-03-22\">\n >\n details = <\n [\"en\"] = <\n\t language = <[ISO_639-1::en]>\n\t purpose = <\"NHS CHOPS-21 chemotherapy guideline ....\">\n\t>\n >\n \nuse\n BSA: Body_surface_area\n \nreference\n paracetamol_dose: Quantity = 1g\n chlorphenamine_dose: Quantity = 10mg\n prednisolone_dose_per_m2: Quantity = 40mg \n rituximab_dose_per_m2: Quantity = 375mg\n doxorubicin_dose_per_m2: Quantity = 50mg\n vincristine_dose_per_m2: Quantity = 1.4mg\n cyclophosphamide_dose_per_m2: Quantity = 750mg\n cycle_period: Duration = 3w\n cycle_repeats: Integer = 6\n\ninput -- \n\n staging: Terminology_term «ann_arbor_staging»\n currency = 30 days\n\n has_metastases: Boolean\n currency = 30 days\n\ninput\n\n neutrophils: Quantity\n currency = 3d\n ranges = {\n [normal]: |>1 x 10^9/L|,\n [low]: |0.5 - 1 x 10^9/L|,\n [very_low]: |<0.5 x 10^9/L|\n }\n\n platelets: Quantity\n currency = 12h\n ranges = {\n [normal]: |>75 x 10^9/L|,\n [low]: |50 - 74 x 10^9/L|,\n [very_low]: |<50 x 10^9/L|\n }\n\n bilirubin: Quantity\n currency = 12h\n ranges = {\n [normal]: |<20 mmol/L|,\n [high]: |20 - 51 mmol/L|,\n [very_high]: |51 - 85 mmol/L|,\n [crit_high]: |>85 mmol/L|\n }\n\n gfr: Quantity\n currency = 24h\n ranges = {\n [normal]: |>20 mL/min|,\n [low]: |10 - 20 mL/min|,\n [very_low]: |<10 mL/min|\n }\n\n ldh: Quantity\n currency = 24h\n ranges = {\n [normal]: |>20 mL/min|,\n [low]: |10 - 20 mL/min|,\n [very_low]: |<10 mL/min|\n }\n\nconditions\n high_ipi:\n Result <- ipi_risk ∈ {[ipi_high_risk], [ipi_intermediate_high_risk]}\n\n |\n | patient fit to undertake regime\n |\n patient_fit:\n Result <- not\n (platelets.in_range (very_low) or\n neutrophils.in_range (very_low))\n \nrules\n prednisolone_dose: Quantity\n Result <- prednisolone_dose_per_m2 * BSA.bsa_m2\n\n rituximab_dose: Quantity\n Result <- rituximab_dose_per_m2 * BSA.bsa_m2\n\n doxorubicin_dose: Quantity\n Result <- doxorubicin_dose_per_m2 * BSA.bsa_m2 *\n map bilirubin.range {\n [high]: 0.5,\n [very_high]: 0.25,\n [crit_high]: 0.0\n }\n\n prednisolone_dose: Quantity\n Result <- prednisolone_dose_per_m2 * BSA.bsa_m2\n\n |\n | TODO: hepatic impairment dose modification\n |\n vincristine_dose: Quantity\n Result <- vincristine_dose_per_m2 * BSA.bsa_m2\n\n |\n | CHECK: is low platelets and GFR dose modification\n | cumulative?\n |\n cyclophosphamide_dose: Quantity\n Result <- cyclophosphamide_dose_per_m2 * BSA.bsa_m2\n * map platelets.range {\n [normal]: 1,\n [low]: 0.75\n }\n * map gfr.range {\n [normal]: 1,\n [low]: 0.75,\n [very_low]: 0.5\n }\n \n |\n | International Prognostic Index\n | ref: https:|en.wikipedia.org/wiki/International_Prognostic_Index\n |\n | One point is assigned for each of the following risk factors:\n | Age greater than 60 years\n | Stage III or IV disease\n | Elevated serum LDH\n | ECOG/Zubrod performance status of 2, 3, or 4\n | More than 1 extranodal site\n |\n | The sum of the points allotted correlates with the following risk groups:\n | Low risk (0-1 points) - 5-year survival of 73%\n | Low-intermediate risk (2 points) - 5-year survival of 51%\n | High-intermediate risk (3 points) - 5-year survival of 43%\n | High risk (4-5 points) - 5-year survival of 26%\n |\n ipi_raw_score: Integer\n if age > 60\n Result <- Result + 1\n\n if staging ∈ {|stage III|, |stage IV|}\n Result <- Result + 1\n \n if ldh.in_range (normal)\n Result <- Result + 1\n\n if ecog > 1\n Result <- Result + 1\n \n if extranodal_sites > 1\n Result <- Result + 1\n \n ipi_risk: Terminology_code\n Result <-\n map ipi_raw_score {\n |0..1| : [ipi_low_risk],\n |2| : [ipi_intermediate_low_risk],\n |3| : [ipi_intermediate_high_risk],\n |4..5| : [ipi_high_risk]\n }\n \nterminology\n term_definitions = <\n [\"en\"] = <\n [\"paracetamol_dose\"] = <\n text = <\"paracetamol dose\">\n description = <\"paracetamol base dose level per sq. m of BSA\">\n >\n [\"chlorphenamine_dose\"] = <\n text = <\"chlorphenamine dose\">\n description = <\"chlorphenamine base dose level per sq. m of BSA\">\n >\n ...\n [\"staging\"] = <\n text = <\"Cancer staging\">\n description = <\"Cancer staging (Ann Arbor system)\">\n >\n [\"has_metastases\"] = <\n text = <\"Metastatic status\">\n description = <\"Status of metastasis of cancer\">\n >\n ...\n [\"neutrophils\"] = <\n text = <\"neutrophils\">\n description = <\"neutrophils level\">\n >\n [\"platelets\"] = <\n text = <\"platelets\">\n description = <\"platelets level\">\n >\n ...\n [\"ipi_low_risk\"] = <\n text = <\"low risk: 5y survival - 73%\">\n description = <\"..\">\n >\n [\"ipi_intermediate_low_risk\"] = <\n text = <\"intermediate-low risk: 5y survival - 51%\">\n description = <\"..\">\n >\n [\"ipi_intermediate_high_risk\"] = <\n text = <\"intermediate-high risk: 5y survival - 43%\">\n description = <\"...\">\n >\n [\"ipi_high_risk\"] = <\n text = <\"high risk: 5y survival - 26%\">\n description = <\"...\">\n >\n >\n >","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Questions","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"DLM - DLM relationships","type":"text"}]},{"type":"paragraph","content":[{"text":"It could make sense to allow DLMs to both ‘inherit’ (extend keyword) and ‘use’, i.e. be composed. Inheriting a re-usable DLM like BSA (body surface area) would allow ","type":"text"},{"text":"height","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"weight","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"bsa_m2","type":"text","marks":[{"type":"code"}]},{"text":" to be referenced directly in the CHOPS guideline. Whereas if the CHOPS guideline wanted to reference rules in some other DLM based on a published (say) Lymphona diagnostic guideline, it would still use an ","type":"text"},{"text":"use","type":"text","marks":[{"type":"code"}]},{"text":" declaration.","type":"text"}]},{"type":"paragraph"}],"version":1}