Text, descriptions and comments for value set items - mandatory or optional?

We need a data type that allows:

  • data element names for all
  • descriptions for some, but not all

I checked and I was wrong. the Description attribute on a term is mandatory.

  • ordering for some, but not all and not always sequential or unique

We have that now with DV_ORDINAL and the same will apply to DV_SCALE

So we are left with 2 issues, I think.

  1. Mandatory descriptions- I suspect will not be possible to make descriptions optional for ordinal terms but mandatory for others. Is there an appetite for making Description optional - in a sense we already do that by adding a dummy ‘’ . We could then use tooling to add '’ as it does now to most terms but not in the context of Ordinals/scales. That makes me a little bit uncomfortable but only a little!!

  2. Not having numerics associated with every item in the ordinal/scale. I know there are use cases but they make me really uneasy. If there is no numeric, what is supposed to be used for e.g ‘infinite’, or what is the point of the numeric? I think I would prefer to separate any text/coded_text options as perhaps a choice against the Ordinal. Do you have any examples that we can chew over?

  3. I just found another example of weirdness - numerics without terms https://academic.oup.com/occmed/article/67/5/404/3975235. We can probably work around that

1 Like

Correction - Description is only mandatory in AOM/ADL2 - do we think that should be relaxed? I would probably vote yes and leave it to good practice/tooling to ‘help us’ to add Descriptions in most cases!!

I’m no longer absolutely sure exactly which ‘description’ we are talking about. But agree in principle that they shouldn’t be mandatory and good modelling will result in descriptions where it is appropriate.

I think descriptions for DV_CODED_TEXT and maybe even the main text for DV_ORDINAL/DV_SCALE value set items should be optional, but for data elements they should be mandatory. We often have scores/scales with no descriptions for value set items, and sometimes just a numerical value with no text at all.

Descriptions wherever possible is good modelling policy, in fact the semantics are often very unclear/unsafe without them. However mandation of descriptions implies you can’t save an archetype without a description - not going to happen…


Totally agree

So just to be clear what we are talking about - here is an example from an older version of the Frailty archetype where the description was plit between Descripton and comment.

["at0005"] = <
					text = <"Very Fit">
					description = <"People who are robust, energetic and motivated. These people commonly exercise regularly.">
					comment = <"They are among the fittest for their age.">

The text is carried through into patient data, along with the associated code and value (for an ordinal). It is always mandatory.

description and comment are only carried in the archetype and are useful in tooling and sometimes helpful in UI generation but do not end up in the patient data.

An AOM 1.4 they are optional, in fact are not formally defined, but the ADL1.4 document implies that description is mandatory.

I sense consensus that description and comment should be optional but ‘encouraged’ - other than perhaps in Ordinals? I’m not sure if that can be enforced in the specs but there is no reason why it could not just be implemented in tooling e.g when a dv_ordinal valuuset is created the usual dummy description is left blank.

Do we have some consensus here?

Make description optional?

What about optional numeric values in DV_SCALE ? I would say no
What about optional’ text’ as per the BORG examples above - again I would say no.

I think there are use cases where DV_ORDINAL/DV_SCALE without the text is warranted. See for example the Pain intensity question of PROMIS-29, here: http://www.healthmeasures.net/administrator/components/com_instruments/uploads/15-09-02_02-16-11_PROMIS-29Profilev2.0InvestigatorVersion.pdf

Agree, DV_SCALE or DV_ORDINAL without a numeric value doesn’t make much sense.

I’d say yes, it should be optional.

I agree. We use the descriptionas tooltip in the UI. To let the user read more carefully why to choose the specific item. Description might be overriden by the application/UI to give more specific description in the specific use-case.

We also see use-cases where the users asks for overriding og the text attribute. This kind of makes sense to be more specific about the intention in the use-case. The problem is that this is also stored in the data. This is why we, so far, didn’t implement such a feature.

It would be interesting to see an example of this! :slight_smile:

Just remember, those descriptions are not primarly made for end-users, but to reviewers and implementers. :slight_smile:

I don’t agree. I think the archetype modelling is great since we have this great possibility to put more information to the end-user about the archetype terms. The comment field should be used to contain information for the archetype modellers, but the description should be written in a way that might be read by the end user.

I look forward to some feedback on this! :slight_smile:

Currently on Better we show by default the “description” from the archetype as a tool-tip to the user on the front end and in many cases it’s very useful. It can be overwritten by other text to be shown on frontend, but this does not go to ehr server when creating a composition.
On the comment’s section of the archetype, I only see it on modelling tools and I agree with @bna that this should be considered as an advice content to the modeller and not shown by default to the end user.

1 Like

You provided an example where there were only some values and others left open - https://academic.oup.com/occmed/article/67/5/404/3975235. I’ve seen other examples and we should also be able to cater for these.

I see some items with values but no text, but no items with no values, in that example?

Hmmm- I would model this just as as a DV_COUNT, I think

Maybe, but there’s the issue of the first and last values having labels. :woman_shrugging:

To try and sum up the discussion from my own understanding:

  • All value set items, whether in DV_ORDINAL/DV_SCALE or DV_CODED_TEXT data types, should have the possibility of adding text, description and comment text fields to them.
  • text should be mandatory for DV_CODED_TEXT, but optional (though strongly recommended) for DV_ORDINAL/DV_SCALE. The reason why it should be optional for the latter two is to accommodate scales like Borg Scale, which has some items with a numerical value but no text.
  • description should always be optional. A lot of scales only have a short text label for each item, and no description. The alternative is to leave the description empty, which makes less sense.
  • comment should always be optional, and would probably only be used where the value set items contain examples.
1 Like

This is the only one that makes me uncomfortable., otherwise agree. I think I would prefer to fill the gaps, where it makes sense or model as DV_COUNT where as in one of the scales it is only 0 and 10 that have text labels. I know we want to replicate the scales as they were designed as far as possible but very often they do not take account of transfer to IT systems, or the data being visualised outside the context of the full form.

I can empathise with the unease, but I don’t see how we can reasonably fill the gaps. For example for the Borg CR10 scale, which text would you assign to the numeric value ‘8’? “More severe than ‘very severe’, but less severe than ‘very, very severe (almost maximal)’”?

Modelling things like the pain intensity scale of the PROMIS-29 as a DV_COUNT would IMO lead to loss of even more context.

1 Like

My clinical safety head would be doing something like

8 Very severe
9 Very severe +
10 Very, very severe
11 Very, very severe +

It’s a hack, I accept but just leaving 'random scores blank just feels risky.

PROMIS-29 Pain scale.

For me this is a ‘junk score’ it is a typical VAS that happens to have the normal guidance '0 means no pain vs. 10 = the worst you can imagine. It is not a scale at all in my book and there is nothing in here that is PROMIS-29 specific.