Original text in ADL?

The requirement is to add an ‘original_text’ attribute to term definitions to handle very wordy but ‘official’ questions associated with some scales and scores. THe authors/copyright holders are often anxious that these are faithfully represented.

["at0027"] = <
    text = <"During the past week had difficulty in concentrating">  
    description = <"Has the patient had difficulty in concentrating"> 
    comment = <"Ensure original text is used in any user interface">  
    original_text = <"During the past week: Have you had difficulty in concentrating on things, like reading a newspaper or watching television?">

Explained in more detail here](See 'Original text' for scales and scores/ instruments?)

There seems to general support from modellers and tool vendors I have spoken to.

@thomas.beale @pieterbos @borut.fabjan @yampeku @sebastian.garde - As far as I can tell, it does not require a spec change - we already routinely add comment to the term_definitions even though this is not explicitly defined in the specs.

I’m not sure if these additional reserved terms need to be documented anywhere.

In linkehr it won’t appear in the editor interface, but I think it won’t be deleted

I have some significant reservations. We have been putting the original text in the description quite successfully via a cut and paste in many scores and scales. It has not had it’s own attribute, but I see zero benefit apart from implementers having a clearer understanding of what should be displayed on a UI.

Some initial thoughts on consequences:

  • description becomes empty, filled with a confusing default *, or we need to make something up that isn’t true to the scale or score. Adding “Has the patient had difficulty in concentrating” is certainly problematic to me, as it is an additional modelling overhead, and any paraphrase like this will most often add zero value and may actively cause confusion - the stuff of review Editor nightmares. It also requires further translation overheads and increases complexity of translation reviews.
  • AD is already not displaying some of the existing attributes ideally, apparently because of limited screen real estate, so I’m not at all thrilled with it being compromised further or having more of these items hidden on other tabs. From a governance point of view this has significant implications.

I do like the idea of investigating some of these other markers/annotations.

This request is not a simple win and we need to consider solutions to these other issues as part of the whole package please.

Regards Heather

1 Like

Normally the idea of other attributes attached to a Term definition in an archetype is that it could apply to any term, like ‘comment’ does. But we are here talking about a term definition attribute that only applies to ‘terms’ that encode a question from a scale/score. If I understand correctly, ‘original_text’ would only apply in such cases. That implies that tools would have to know this, and somehow guess or be told that some terms are ‘questions’ - this is not usually a good idea in tooling. Runtime apps would need to make the same inference somehow as well.

I can see a few ways to pontentially do this more cleanly:

  • create a subtype of the class ARCHETYPE_TERM, which is the formal type of those terms within the AOM, e.g. QUESTION_TERM or similar, with the attribute ‘orginal_text’ and any others needed. I don’t really know if this makes sense but it is a technical possibility. Tools and apps can then know for sure just based on the type what kind of term is there.
  • define a ‘question’ CLUSTER archetype with the needed bits and pieces. I know @heatherleslie has stated that this was done and didn’t work, but it might be worth a review of the previous effort with some tech people involved. This path means no changes to the RM, or AOM, and tools would instead need to spot this ‘reference archetype’.

The second way seems preferable to me, if it could be made to work, but the first way might well be a good solution. Terminology experts may have better ideas!

1 Like

Just on this, I think we should see such issues as being fixable temporary problems, not permanent obstructions to modellers doing what they want.

I agree but that clear understanding is exactly what we need to aim at but to be clear this is only for display and licensing reasons. @thomas.beale - although this mostly applies to scales and scores , there other occasions where it would be really helpful to be able to point implementers to ‘official display text’ where is not appropriate to use that directly in the term value. Yes , we can use ‘description’ but it is not clear that this is the recommended/clinically safe/mandated text, rather than some other description. It can apply to terms in valuesets as well as node names.

Having the ‘original text’ clearly defined makes it much easier for downstream UI artefacts to be gnerated and for us to show that formal instruments are being properly represented.

@heatherleslie - I agree that we do not want to add to the editorial burden but I had assumed that it would only be completed if the archetype modeller (might also be in templates) recognised that they had somehow altered the original text. If the ‘original text’ attribute is empty, it can be assumed that the term text is an accurate representation. I think we had already talked about making description optional.

So term text is mandatory, using ‘original text’ only when the term text is in some way altered. Description is also optional and in most cases, for formal instruments, can be left blank, and use 'original text; to capture the full text.

So for a form generator, or indeed manual app builder, they would just check the ‘original text’ and if that is empty, they can assume that the text they should display is that of the term. Whether this is part of a formal scale or score is not relevant. no need for a new class or archetype. There will be examples of this being helpful in other kinds of archetype and in quite a few templates.

@heatherleslie -I agree that AD could do some of this a bit better but I think we should treat that separately (perhaps a group of us come up with a common approach to suggest to Better?). It might even be sensible to keep this off the main screen and e.g on the terminology tab.

1 Like