ADL1.4→2 Annotations

PROMS archetypes, in particular, are highlighting a need for better handling of ‘annotations’ that can be both unilingual or multi-lingual, and a few disrepancies in tooling are becoming evident.

ADL1.4 annotations

In the ADL1.4 setting two types of annotations are supported in tooling - multi-lingual annotations in archetypes and unilingual annotations in templates.

Archetype-level Multi-lingual annotations associated with archetyped data points , carried in the terminology section. These are really just extra ‘term_definition’ items beyond the text and `description` keywords . comment is not actually defined as a keyword but is treated as such by convention. AOM1.4 does not specifically distinguish ‘text, ‘description’ or ‘comment’ - these are all just ‘items’ in the AOM1.4 spec

["at0028"] = <
text = <"Pain or burning on urination">
description = <"">
epic_item_id = <"29">
subscale2 = <"Irritative/Obstructive">
subscale = <"Urinary bother">
domain = <"Urinary">
original_form_number = <"6b">
short_form_number = <"4b">

Template-level ‘path-based annotations’ supported in both .oet and . AD native json formats.

in Ocean .oet these are uni-lingual, in AD Native (ADN) these are multi-lingual (ADL2). ADN also converts any ontology-based annotations other than ‘description’ or ‘comment’ to multi-lingual path-based annotations (as per ADL2), as well as any annotations defined in the template -a exactly as expected in

AD native json format

       "annotations": {
        "@type": "RESOURCE_ANNOTATIONS","documentation": {
          "en": {
            "/data[at0001]/events[at0313]/data[at0003.1]/items[at0004]": {
              "epic_item_id": "23",
              "subscale2": "Incontinence",
              "subscale": "Urinary function",
              "domain": "Urinary",
              "original_form_number": "1",
              "short_form_number": "1",
              "Templated": "me"
            },

ADL2

ADL2 adds support for multi-lingual path-based annotations in both archetypes and templates but also allows them to be added to RM attributes.

AOM2 formalises the text and description items but not comment and retains other_items

Although not clearly documented, there seems to be presumption that any existing ontology-based annotations, other than text , description and comment should be converted to path-based annotations.

annotations
    documentation = <
        ["en"] = <
            ["/data[at0001]/events[at0313]/data[at0003]/items[at0241]"] = <
                ["epic_item_id"] = <"62">
                ["subscale"] = <"Sexual function">
                ["domain"] = <"Sexual">
                ["original_form_number"] = <"21">
            >

OPT 1.4 generation

AD: When exporting a .opt 1.4 file, AD converts all terminology-based annotations, other than description or comment to unilingual path-based annotations, merging any path-based annotations from the AD native.json template. The major issue here is that opt1.4 only supports unilingual path-based annotations.

CKM: CKM generates opt.14 (based on .oet) , by retaining all ontology-based multi-lingual annotations as-is and adding unilingual template path-based annotations.

Web template generation

Web templates retain ontology-based multi-lingual annotations for ‘description’ but convert ‘comment’ or any other ontology-based annotations to path-based uni-lingual annotations.

Next steps

The assumption that terminology-based annotations should be deprecated in favour of path-based annotations seems sensible. Path-based annotations provide a simple consistent means of supporting annotations on both RM attributes and archetyped nodes at both archetype and template-level and potentially both unilingual and muti-lingual. However there are a few loose-ends to be resolved, especially in transition while opt1.4 still needs to be supported.

Issues arising

Document ADL1.4→ 2 approach

We need to clearly document he expected behaviour when converting to ADL2 and decide if legacy ontology-based annotations should be preserved. The major issue is that Better’s approach to converting terminology-based annotations to path-based annotations drops any multi-lingual capacity in .opt1.4 and web templates.

Proposal

Add comment attribute in ARCHETYPE_TERM as formal attribute
? Deprecate other_items in ARCHETYPE_TERM. Certainly do not support in tooling
Retain terminology-based annotations in .opt1.4 exports, alongside
Add multi-lingual annotation support in web-templates

This should be compatible with .oet generated .opt as in CKM.

Clarify ADL2 approach to uni-lingual annotations

ADL2 specs do not clearly explain how to capture unilingual annotations. THey hint at other approaches but do not give examples. It would be very useful to capture both unilingual (technical ‘coded’ items) and multilingual annotations (PROMS type descriptors)

Options

A. Add a language descriptor or empty string which explicitly means ‘unilingual’

B. Add a new top-level section which is explicitly unilingual (may need AOM spec change

This obviously has an impact on AD/CKM tooling where unilingual vs multi-lingual annotations must be explicitly supported in the UI.