Stream: implementers
Topic: valueQuantity for pure fractions
Bob Milius (Jul 12 2021 at 17:58):
I'm creating examples of Observations for values in a valueset in our IG.
The valueset contains (among other things) LOINC codes that have the pattern of "Pure [something] fraction". For example 71831-2 has a name of "Hematocrit [Pure volume fraction] of Capillary blood". The description of all of these kinds of codes is
Because of the confusion that occurs in countries that report results as both decimal fraction and percent, this property was created to represent decimal fractions that are reported without units.
I'm thinking that these might be represented in an observation as valueQuantity.value but without valueQuantity.code or valueQuantity.system since they are unitless. Or I can use the the ucum code {ratio}, but without valueQuantity.unit. Is there a best practice?
"valueQuantity": {
"value": 0.01
},
vs
"valueQuantity": {
"value": 0.01,
"system": "http://unitsofmeasure.org",
"code": "{ratio}"
}
Codes in our valueset following this pattern:
71865-0
71864-3
71863-5
71833-8
71831-2
71829-6
71668-8
71667-0
71666-2
Colin E. (Jul 14 2021 at 13:25):
These values aren't actually "unitless". They have a unit of "1" (the unity), but because units in quantities are multiplicative, and multiplying by 1 means "no change" it is convention that the unit of 1 can be omitted. A unit of "1" is implied by the absence of a unit expression, at least when the value is displayed. That's the situation in maths and the SI unit system, I don't know if the FHIR community has embraced the same convention.
Given that, an alternative form for your example would be-
"valueQuantity": {
"value": 0.01,
"unit": "",
"system": "http://unitsofmeasure.org",
"code": "1"
}
This would mean the unit is explicit in the message, but also defined as blank (the empty string) for display. However i'm no FHIR expert so there may be rules about transmitting null values or empty strings that this would fall foul of, so I can't claim it as "best practice" without comments from other more knowledgable contributors.
It's a weakness of unit-based systems that so many distinct concepts end up overlayed onto that value of one, which is a sort of singularity (no pun intended) where the maths rather gives up. UCUM makes this worse by allowing arbitrary comments (annotations) in curly braces, and giving any such element the value of "1" as well. I suspect it would be much more useful to have "real", defined expression atoms in UCUM (or a sucessor) for different "flavours" of the value 1, for example to distingish quantities that are always Integers [1] from those that are representing real numbers [1.0], but at the moment an unlimited number of unit expressions in UCUM resolve down to the same indistinguishable value of "1".
Richard Townley-O'Neill (Jul 15 2021 at 04:06):
Values cannot be null. The Regex for all of the primitive elements requite at least some content: http://hl7.org/fhir/R4/datatypes.html#primitive
Bob Milius (Jul 15 2021 at 17:02):
Since unit cannot be null, but it is optional, would this be an acceptable and perhaps preferred way of representing it?
"valueQuantity": {
"value": 0.01,
"system": "http://unitsofmeasure.org",
"code": "1"
}
Lloyd McKenzie (Jul 15 2021 at 17:09):
That's fine. But that means there's nothing for the user so see in terms of unit
Josh Mandel (Jul 15 2021 at 17:09):
https://ucum.org/ucum.html addresses this -- indeed you can write "1" or noting:
An annotation without a leading symbol implies the default unit 1
Annotations in UCUM are strings within curly braces, so you can equivalently write something like:
{
"value": 0.01,
"system": "http://unitsofmeasure.org",
"code": "{volume fraction}"
}
Lloyd McKenzie (Jul 15 2021 at 17:11):
You can, though we strongly discourage the use of curly-brackets in UCUM codes in FHIR - because they tend to break interoperability. Many implementations will treat codes with different curly-brace values as being different rather than equivalent. With FHIR, we have "unit" to put the human-readable piece.
Eric Whitley (Jul 15 2021 at 17:41):
I had no idea the annotation on code was possible. Is that a common thing? I would never have expected that.
Eric Haas (Jul 15 2021 at 18:01):
it is a UCUM thing and not a FHIR code thing
Lloyd McKenzie (Jul 15 2021 at 18:03):
And UCUM injected it specifically to accommodate those who wanted to differentiate "units" which, from a mathematical perspective aren't units. So if you want to say 5 "{oranges}" and 3 "{apples}" you can, even though internally UCUM treats both of those as having a unit of "1".
Eric Haas (Jul 15 2021 at 18:04):
we strongly discourage the use of curly-brackets in UCUM codes in FHIR
"we" don't mention it here: http://build.fhir.org/ucum.html
Eric Haas (Jul 15 2021 at 18:08):
I always thought it was because the curly braces had to be escaped a lot and that was a nuisance. I personally enver understood the opposition to using them - they seemed handy to have.
Eric Whitley (Jul 15 2021 at 19:14):
OK, so that makes me feel better. I didn't know if that would be a common thing where someone would send an annotation in place of the coded form. Thank you @Lloyd McKenzie , @Eric Haas , @Josh Mandel for the info and education. :)
Bob Milius (Jul 15 2021 at 20:42):
Eric Haas said:
we strongly discourage the use of curly-brackets in UCUM codes in FHIR
"we" don't mention it here: http://build.fhir.org/ucum.html
and curly-brackets are found in common ucum codes in the FHIR ucum-units valueset
Lloyd McKenzie (Jul 16 2021 at 15:01):
And even though they're allowed for UCUM, they're strongly discouraged in FHIR given that FHIR provides a better alternative.
Jean Duteau (Jul 16 2021 at 15:27):
you keep saying that they're strongly discouraged but, like Eric, I don't see where we say that anywhere in the specification. I looked at the ucum code system and at the Quantity datatype and we say nothing about the curly-brackets.
Lloyd McKenzie (Jul 16 2021 at 16:31):
You're right. FHIR#33063 submitted to address.
Colin E. (Jul 26 2021 at 18:11):
and curly-brackets are found in common ucum codes in the FHIR ucum-units valueset
That's true, annotated units are very common in a lot of published lists, the ucum-units valueset (from memory) comprises 40-50% codes that are differentiated from other codes only by what is in the annotations, but that doesn't mean that's a good thing.
UCUM is a mini programming language (a DSL) for units, and annotations are effectively comments in the code. They have no functional value. If someone told you they had written over 1300 programs, but it turned out 600-ish of them were identical in function AND TEXT to other programs, just with different comments, would you still believe they'd written 1300 programs?
As @Lloyd McKenzie has pointed out, some systems may accept UCUM code strings but not implement "deep knowledge" of the UCUM semantics. They will just compare units as strings, so the only way they can "canonify" a UoM code is to strip out the annotations first, to have the best chance of finding a match in their own UoM list, or when the code is sent to another system.
The value in having a system like UCUM in place is to allow machine-readable semantics of units to be exchanged between systems. Annotations are, by definition, non-semantic elements. As far as any computation with those units is concerned, they don't exist, which makes one wonder why so much time and effort has been spent crafting (say) over 20 differnt annotated versions of the unit "%", when the machine will just (in a computation) say "== 1/100" if required and move on.
The authors of UCUM knew the inclusion of annotations was controversial (this is documented) but felt they had to do it to appease the body of users who see the units field as the place to have a conversation with the recipient, vs. a place to do maths. It's not my place to tell those users they are wrong (what do I know, i'm an engineer...) but I can say that in FHIR the unit code is there for the machine to interpret, and that's not great a place for confusing narrative.
Lloyd McKenzie (Jul 26 2021 at 19:58):
The purpose of FHIR#33063 is to give guidance to implementers that - in FHIR - there are alternative places to put that user-facing text that don't interfere with the computability and that therefore, those alternative mechanisms are preferred.
Last updated: Apr 12 2022 at 19:14 UTC
