Original text in ADL?

ian.mcnicoll · 12 September 2020 12:25

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.

yampeku · 12 September 2020 20:37

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

heather.leslie · 13 September 2020 03:08

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

thomas.beale · 13 September 2020 12:21

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 @heather.leslie 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!

thomas.beale · 13 September 2020 12:22

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

ian.mcnicoll · 13 September 2020 17:29

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.

@heather.leslie - 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.

@heather.leslie -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.

ian.mcnicoll · 14 November 2023 13:31

I’d like to re-open this discussion as we are in the process of reviewing a PROMS archetype which pushes the requirements to accurately represent PROMS UI directives a little further;

Ignore the ‘markdown’ in the Descriptions - that is another contentious issue/experiment Markdown use?.

The changes we have made, since the last posts, are to accept @heather.leslie 's argument that in the majority of cases, it makes sense just to put the original patient-facing long text question into the Description field for formal scales and scores.

There are some other issues though…

Do we need to technically flag up any exceptions to using Description for original patient questions? I think there are such exceptions on CKM. Perhaps it is not important?
Should we handle other ‘UI directives’ which are part of the use of the scale/ score. The open Outcomes developers certainly appreciated adding these to the archetype.

An example is a ‘Page break instruction’ where the score specifies that a piece of text must always appear at the top of any pages/tabs created by the app

“This questionnaire is about your joint, back, neck, bone and muscle symptoms such as aches, pains and/or stiffness.”

This is part of the licensing requirement for any app that deploys this score, so there is an argument that it assists some of those tricky conversations about archetypes and licensing, since we can demonstrate that we make it easier for apps developers to do the right thing.

We handled this ‘pagebreak instruction’ by placing it in a marked-up comment but this was largely due to some problem with current tooling.
e.g,

["at0000"] = <
	text = <"Musculoskeletal Health Questionnaire (MSK-HQ)">
	description = <"The MSK-HQ is a short self-reported questionnaire that allows people with musculoskeletal conditions (such as arthritis or back pain) to report their symptoms and quality of life in a standardised way.">
	comment = <"pagebreakInstruction: 
This questionnaire is about your joint, back, neck, bone and muscle symptoms such as aches, pains and/or stiffness.

Leaving aside whether this is a good thing to do, our preference would actually be to use the keyed items in the archetype ontology section, as these need to be multilingual

["at0000"] = <
	text = <"Musculoskeletal Health Questionnaire (MSK-HQ)">
	description = <"The MSK-HQ is a short self-reported questionnaire that allows people with musculoskeletal conditions (such as arthritis or back pain) to report their symptoms and quality of life in a standardised way.">
  pagebreakInstruction =<" This questionnaire is about your joint, back, neck, bone and muscle symptoms such as aches, pains and/or stiffness.

However, we found some issues with the way that this is represented in Archetype Designer .opt generation, where it treated as a template annotation (and therefore uni-lingual), and by the web template format , which merges mutli-lingual keyed ontology items with template annotations.

I’m sure these are fixable, so our questions are…

Is there a place for these Scale/score UI directions in archetypes, and an agreed way of capturing them.
And if not in archetypes, is there an argument for having a set of agreed directives that can be added at
template level?
Are there other examples e.g. headerInstructions that might apply.
Do custom keyed ontology items make sense for this?
Are there any tech blockers to keeping these keyed items multilingual and carried correctly in .opt and .wt formats?

thomas.beale · 15 November 2023 18:12

A few Qs (upon rereading the thread):

is this mainly about scores or questionnaires, or both? For questionnaires, the text is to represent some original question text faithfully; for scores, I’m not sure, since AFAIK, everyone using a given score knows exactly what the numbers mean - or maybe they don’t? But don’t we always want to publish the standardised text for each Ordinal option (i.e. that the 0,1,2 of Apgar/heart rate mean), since Scores absolutely rely on standardised assignment of the ordinal values to the patient.
for the pagebreak thing, putting this in the archetype term definitions means that it will never be there, except on most/some/all questionnaires, when it will always be there. Any App building software would have to know to look for this ‘page-break’ field while processing certain kinds of archetypes.

I’m not sure I understand yet why this kind of thing wouldn’t be done in a Cluster pattern archetype that would carry things like:

original question text
standardised question meaning
question response
pagebreak indicator
optional other things