# Adding to the DV_QUANTITY units options
**Category:** [Archetype Designer](https://discourse.openehr.org/c/archetype-designer/30)
**Created:** 2021-10-21 01:03 UTC
**Views:** 2063
**Replies:** 67
**URL:** https://discourse.openehr.org/t/adding-to-the-dv-quantity-units-options/1964
---
## Post #1 by @heather.leslie
@borut.fabjan et al,
Is there a recommended way that we can add to the DV_QUANTITY units list so that it can be included in updates. Personally, I've hacked the ADL on multiple occasions but this is clearly not ideal and it isn't there next time I or others need it...
Triggered by @JonJones question... https://discourse.openehr.org/t/medication-amounts-and-units/1935/4
The Gray is an SI unit, defined as the absorption of one joule of radiation energy per kilogram of matter. In the Archetype Designer settings (top R corner of the logged in AD screen) can be set to UCUM or to an openEHR list that includes SI units. In the UCUM list 'J/kg' is present, and if you switch to the openEHR list, then 'Gy' is present.
Similarly, Volt (V) is another SI unit, defined as Joules per Coulomb. While Volt appears in the openEHR list, 'J/C' appears not to be available.
While Gy and V are presented as SI units in this UCUM document with definition units - https://ucum.org/ucum.html#para-30 - centiGray and kiloVolt are not. I've found references to 100 cGy = 1 Gy and descriptions of a centiGray as a 'derived metric (SI) measurement unit'. Similarly 1 kV = 1000V.
The Ocean tool used to have a local file that could be edited. Is there an equivalent one for the AD tool?
---
## Post #2 by @siljelb
There is a local file for Archetype Designer in the same way as in Archetype Editor. In fact it's the same file. I've added cGy, mGy and kV to this file, as well as made some other minor adjustments and corrections. Could you update AD with this when convenient, @borut.fabjan ?
[PropertyUnitData.xml|attachment](upload://5QvIbX3CGQC0z3Fp0ugc2X00snf.xml) (56.4 KB)
Although for the future, it's likely we'll want to be able to construct UCUM units conbining the atom units with appropriate prefixes on the fly. In this case, the unit files would only contain a list of properties (length, mass, energy dose, etc), a list of atom units (m, kg, Gy, etc), and a list of prefixes (m, M, c, etc). This would be much more flexible, and wouldn't require us to add new stuff to the units file anywhere near as often.
---
## Post #3 by @JonJones
I like this future option, and thanks for the information on the property units. To work around this for now I've just removed the units constraint so any unit value is now allowed- lets the user specify cgy or gy but weakens the model slightly. It has limited exposure at the moment but pressing timescales. Would be interested to know where that file lives in AD directories- not seen that before!
---
## Post #4 by @siljelb
To follow up on your requirement @JonJones, kV and cGy can now be used as units in Archetype Designer.
---
## Post #5 by @JonJones
Super- thanks for seeing this through!
---
## Post #6 by @Dileep_V_S
g/dL - (gram per deciliter) option is still missing from archetype designer. Can this also be added?
---
## Post #7 by @siljelb
Did you try selecting "Concentration", then "MASS/VOLUME"?
---
## Post #8 by @Dileep_V_S
@siljelb Yes that works. I never knew this approach. Thanks for pointing it out
regards
---
## Post #9 by @heather.leslie
@siljelb, any suggestions on how to represent {copies} and {*copies* }/*mL* as units for HIV viral load?
Also {copies}/ug, {Log_copies}/mL, 10*3{copies}/mL - as per https://ucum.nlm.nih.gov/example-UCUM-Codes-v1.4.pdf
I can't see these able to be represented in the PropertyUnitDate.xml?
Thanks
---
## Post #10 by @siljelb
Since a UCUM annotation (anything between curly braces) is dropped by a parser, almost all of these could be represented as a "qualified real/volume" concentration:
The exception is {copies}/ug which is a "qualified real/mass" concentration. We don't have a unit setup for this in the currently used PropertyUnitData.xml, but I see no reason why we couldn't add it.
If we need the units persisted with the {copies} etc annotations, we could add those also to the PropertyUnitData.xml.
---
## Post #11 by @heather.leslie
Sure. In that case, I'd like to see {copies}, 1 {Log_copies} and 10*3{copies} added to the .XML file and we now have a use case for {Qualified Real/Mass}.
As the apparent custodial of the file, can you update it, please?
Thanks
Heather
---
## Post #12 by @siljelb
I can update the copy I have, but as far as I know there isn't any centralised governance of this file. Is this something we can get going, @thomas.beale ?
For now though, could you add this new file to Archetype Designer, @borut.fabjan ? [PropertyUnitData.xml|attachment](upload://sCjHU7NOMmaV6pwlyuS0ZRO2XJr.xml) (58.2 KB)
I've added the following:
```
```
The reason why I've done it this way and not added '{copies}' and '{log_copies}' is that those are functionally the same as '1'.
---
## Post #13 by @thomas.beale
[quote="siljelb, post:12, topic:1964"]
I can update the copy I have, but as far as I know there isn’t any centralised governance of this file. Is this something we can get going
[/quote]
Yes indeed - is the link you made below of a definitive copy, or do you want to make changes?
EDIT: also, I would have expected you want to retain the `{copies}` in those additions - the idea is for the parser to get rid of those, otherwise the remaining units text won't be computable / comparable.
---
## Post #14 by @siljelb
[quote="thomas.beale, post:13, topic:1964"]
is the link you made below of a definitive copy, or do you want to make changes?
[/quote]
I've already made the changes I outlined, but I don't know whether this is the definite file, because we don't have a centralised governance of the file :sweat_smile:
[quote="thomas.beale, post:13, topic:1964"]
EDIT: also, I would have expected you want to retain the `{copies}` in those additions - the idea is for the parser to get rid of those, otherwise the remaining units text won’t be computable / comparable.
[/quote]
I'm not sure what you mean here. These units are functionally equivalent to `1/ml`, `1/ug`, `1/ml` and `10*3/ml`, respectively. Any interpretation would need to be done by a human. This should be okay for most of them, but I'm struggling a bit with the `{log_copies}/ml`. Ideally we should have a machine readable symbol for a decimal logarithmic (and natural logarithmic) scale in UCUM, but I can't find one.
---
## Post #15 by @thomas.beale
[quote="thomas.beale, post:13, topic:1964"]
also, I would have expected you want to retain the `{copies}` in those additions -
[/quote]
Sorry my fault, didn't real the XML properly - was reading the 'Text' field, not the UCUM field.
---
## Post #16 by @sebastian.iancu
[quote="siljelb, post:14, topic:1964"]
I’ve already made the changes I outlined, but I don’t know whether this is the definite file, because we don’t have a centralised governance of the file :sweat_smile:
[/quote]
The latest version of **PropertyUnitData.xml** was added to [specification-TERM](https://github.com/openEHR/specifications-TERM/blob/master/computable/XML/PropertyUnitData.xml). Future changes can be submitted via JIRA and we can then apply SEC workflow on maintaining that file.
See details on https://discourse.openehr.org/t/invalid-ucum-units-in-archetype-designer/1261/14.
---
## Post #17 by @heather.leslie
[quote="sebastian.iancu, post:16, topic:1964"]
Future changes can be submitted via JIRA
[/quote]
How can this decision be made more accessible to the community?
---
## Post #18 by @thomas.beale
Problem reports (PRs) can always be raised on any specifications-related artefact, including this file.
So this file is in the 'TERM' component and you can get to the PRs via the 'PR' link highlighted below.
Otherwise you can get there via the [Jira PRs project](https://openehr.atlassian.net/jira/software/c/projects/SPECPR/issues). Use 'View all filters' on the bottom left menu to get to a filter 'TERM-PRs', otherwise you will see everything.
For this particular issue, you could comment in the issue ([SPECPR-408](https://openehr.atlassian.net/browse/SPECPR-408)).
---
## Post #19 by @sebastian.iancu
[quote="heather.leslie, post:17, topic:1964, full:true"]
[quote="sebastian.iancu, post:16, topic:1964"]
Future changes can be submitted via JIRA
[/quote]
How can this decision be made more accessible to the community?
[/quote]
Heather, I guess you see some (technological) obstacles in managing future evolution this PropertyUnit.xml file. We actually apply same principles as for all other openEHR specifications artefacts, so it is nothing special for this file.
---
## Post #20 by @thomas.beale
We might have to think about going back to having a Jira service desk project to collect terminology change requests from the general community...
---
## Post #21 by @vanessap
That would be the best way. Until now my experience was pinging @siljelb to update the file and later pinging @borut.fabjan to update adl designer (thanks!). Putting the file on github now made it more visible for others, what exists there, how is it made, etc
But how many would know that they need to come to the jira service desk and request?
I believe that to some the interaction are directly with the modelling tool, so maybe first some kind of info button should be available on the tools (like "can't find a unit? click here") and redirect to this service desk? (where it could also have a link to discourse)
And I am now wondering, this file I uploaded before came from ADL designer. Does other modelling tools also use it? What about conformance? (*edit: i saw now this is a post on ADL designer, but i left it here for future thinking*)
---
## Post #22 by @sebastian.iancu
That board was unfortunately never used during a few years existed. Instead, changes were communicated mostly personally, or were just discovered accidentally in the (new subsequent version of the) tooling files. My take, since I adopted this specification component few months ago, was to apply standardized governance and publishing cycles that we have in openEHR (SEC + PRs/CRs) - if that seems unworkable then I would like to get feedback on why, etc.
In case of this PropertyUnitData.xml, even we (SEC) would maintain it and store it on GitHub, it still has to be "imported" into Archetype Designer - so @borut.fabjan help is still needed. :pray:
---
## Post #23 by @thomas.beale
[quote="sebastian.iancu, post:22, topic:1964"]
My take, since I adopted this specification component few months ago, was to apply standardized governance and publishing cycles that we have in openEHR (SEC + PRs/CRs) - if that seems unworkable then I would like to get feedback on why, etc.
[/quote]
I think that is exactly what we should be doing - but there is an additional question: how does a clinical modeller or anyone (someone using the file in some R&D project, say) ask for NewWeirdRadiologyUnit to be added to the units? If we had a service desk project, and the URL of that project was embedded in the right place in tools, and maybe we have a button as well on the specs page, then people can just put their request into the tracker, and we process the requests, and re-release the file. So those requests are really just a special kind of PR that says: I think this code xyz is missing.
---
## Post #24 by @heather.leslie
No, just a communication issue. It's one thing for the people involved in specs to know this is the way it is done but inevitably people start a new thread on Discourse asking for help in how to model units. I'm suggesting there needs to be some prominent FAQ or similar public notification (not a tech tool) to try to circumvent this 'groundhog day' question from newbies, non-techs and everyone else who doesn't know your strategy.
---
## Post #25 by @sebastian.iancu
Thank you Heather, it is now getting clear to me what you meant by previous post. You are right, better communication will help; I will try to address this.
---
## Post #26 by @ian.mcnicoll
@heather.leslie - I like the idea of a specific Units topic on Discourse with perhaps a fixed post and link to the JIRA.
But often the questions are a bit more nuanced like - "I can't find Squiggles per m2" which may require an expert to figure out if this is indeed missing or is perhaps out of scope.
Heather is correct that most newbies/clinical folks are likely to be a bit intimidated by JIRA. So perhaps more realistic for some 'units' experts to watch that topic and facilitate/ filter requests and make the CRs when appropriate.
---
## Post #27 by @thomas.beale
[quote="ian.mcnicoll, post:26, topic:1964"]
Heather is correct that most newbies/clinical folks are likely to be a bit intimidated by JIRA. So perhaps more realistic for some ‘units’ experts to watch that topic and facilitate/ filter requests and make the CRs when appropriate
[/quote]
That's what Jira service desk is for - it is designed to be outward (customer) facing.
---
## Post #28 by @ian.mcnicoll
[quote="thomas.beale, post:27, topic:1964"]
That’s what Jira service desk is for - it is designed to be outward (customer) facing.
[/quote]
Still think this kind of activity is better mediated through a bit of community advice / curation. i.e likely to be insiders who interact with the service desk rather than newbies
---
## Post #29 by @siljelb
I agree. In some cases it even takes a bit of community thinking to decide what the required units actually are. For example, it took us a while to come up with the "Medication dose rate" property, with units such as "{MASS/MASS/TIME}" or "{VOLUME/AREA/TIME}".
---
## Post #30 by @ian.mcnicoll
It almost just needs a pinned post here "So you cannot find a particular unit..." which could explain some of the common challenges with UCUM units, e.g how to find compound units, issues with weirdly name units -, what the heck Qualified real is all about, and then those curly bracket things etc. Finally if you still can't find what you need , then feel free to ask for advice (and here's the link to the Service request in JIRA, if you are happy to go ahead yourself).
---
## Post #31 by @heather.leslie
Just one of a series of FAQs explaining the process would be enough. This will be a frequent flyer.
---
## Post #32 by @heather.leslie
[quote="thomas.beale, post:27, topic:1964"]
outward (customer) facing.
[/quote]
Nope. It may be for a specific population, but not for all. And it is likely that this question is commonest for those of us who don't usually/ever hang out on JIRA. We need to use the right tool for the job.
---
## Post #33 by @thomas.beale
I'm still not being very clear I realise ;)
Jira service desk (for which we have a licence) is a tool for building a website with forms that are designed in the tool to look however we want. We can build a test one pretty quickly and demo it.
The 'jira' that you are thinking of is only an internal view of the above, seen by those who service the requests.
There are other tools that do the same job, and they all work pretty much the same way.
---
## Post #34 by @ian.mcnicoll
That's ok - build it and we can hook up to it. No-noes objecting but we see it being used primarily by openEHR insiders such as @siljelb, and that a Discourse topic plus FAQs is a better place to have folks ask the original question, which normally involves some discussion.
---
## Post #35 by @thomas.beale
[quote="ian.mcnicoll, post:34, topic:1964"]
No-noes objecting but we see it being used primarily by openEHR insiders such as @siljelb, and that a Discourse topic plus FAQs is a better place to have folks ask the original question, which normally involves some discussion.
[/quote]
Discourse FAQs are fine, we should have that as well.
But to ask for new terms in the Units file, or in any terminology, a request system of some sort is needed that queues requests for attention from the 'insiders'. The requesters need a place to lodge those requests. Service desk is a good option. With about 15 mins configuration (more to do), I set up a Jira Service Desk project dedicated to collecting requests for new and changed terms/codes in the Property / Units file and also openEHR terminology.
Here's what the 'new unit request' looks like (with no form-building at all). It is available at a portal within the openEHR jira space, i.e. it's a pure form. It can be made prettier, simpler or whatever. Since it is hosted in a dedicated place, that URL can be used anywhere we want, and anyone who clicks it will land on this (or a similar) form.
---
## Post #36 by @heather.leslie
I did understand. :wink:
I wasn't disagreeing with your proposed technical process but rather suggesting that we needed to develop some frequent flier FAQs to explain the process and to link to the process, not to replace the process. :wink: :wink:
---
## Post #37 by @ian.mcnicoll
This might be of interest in the general UCUM / lab units space.
https://www.linkedin.com/pulse/uk-pathology-units-list-what-why-how-termlex/?trackingId=vTSboBSodEcMyTfkXusJYw%3D%3D
---
## Post #38 by @Brice
Hi, does anyone know how to find microvolt units (μV) in Archetype Designer?
I suspect they are not included, is there a procedure to request it?
---
## Post #39 by @siljelb
Hi Hugo! The most recent [PropertyUnitData.xml](https://github.com/openEHR/specifications-TERM/blob/master/computable/XML/PropertyUnitData.xml) does contain `µV`, but I suspect AD hasn't updated it during the last three months.
@borut.fabjan, I'd recommend to wait until [this PR](https://github.com/openEHR/specifications-TERM/pull/12) has been merged, as it corrects an error on the `kV` unit.
---
## Post #40 by @Brice
Great, thank you very much!
---
## Post #41 by @sebastian.iancu
Sorry for delay, PR is now merged, the change is not in 'latest' and will be part of upcoming Release 3.1.0.
---
## Post #42 by @linforest
```
```
My current translation (zh) of the rubric "Qualified real" is "带有量词限定的实数" (which means a real number with a qualifier for counting)? Is this understanding correct?
BTW, I forked the [openEHR specifications-TERM repo](https://github.com/openEHR/specifications-TERM) for translating the [XML file](https://github.com/openEHR/specifications-TERM/blob/master/computable/XML/en/openehr_terminology.xml).
---
## Post #43 by @linforest
```
```
This rubric is a bit ambiguous. "Electric resistance"?
```
```
An ambiguous rubric. It means "the value that appears most frequently in a series of numbers"?
If **example units** available, it would be easier to clarify the meaning.
---
## Post #44 by @linforest
```
```
I can't find exactly the same term above but the following one:
```
"Power spectral density" = "功率谱密度"
```
Should these issues be proposed to the github repo?
---
## Post #45 by @siljelb
[quote="linforest, post:42, topic:1964"]
“Qualified real” [...] (which means a real number with a qualifier for counting)? Is this understanding correct?
[/quote]
It's a good question. I've always understood 'Qualified real' to be a "trick" to be able to fit a unitless number into the DV_QUANTITY data type, but others who've been around for longer probably have more info about this. @thomas.beale ?
[quote="linforest, post:43, topic:1964"]
```
```
This rubric is a bit ambiguous. “Electric resistance”?
[/quote]
Agree, "Electrical resistance" is better!
[quote="linforest, post:43, topic:1964"]
```
```
An ambiguous rubric. It means “the value that appears most frequently in a series of numbers”?
[/quote]
This is from ``:
```
```
In the context of the other related values, my assumption is that this is the statistical mode:
> The mode refers to the most frequently occurring number found in a group of numbers.
( [Mode - StatPearls - NCBI Bookshelf (nih.gov)](https://www.ncbi.nlm.nih.gov/books/NBK540990/))
[quote="linforest, post:43, topic:1964"]
If **example units** available, it would be easier to clarify the meaning.
[/quote]
Yes, the units for all the different unit properties are in [PropertyUnitData.xml](https://github.com/openEHR/specifications-TERM/blob/master/computable/XML/PropertyUnitData.xml).
[quote="linforest, post:44, topic:1964"]
```
```
I can’t find exactly the same term above but the following one:
```
"Power spectral density" = "功率谱密度"
```
[/quote]
You're right, it should be "Power spectral density".
[quote="linforest, post:44, topic:1964"]
Should these issues be proposed to the github repo?
[/quote]
That would be great! :smile:
---
## Post #46 by @ian.mcnicoll
[quote="siljelb, post:45, topic:1964"]
I’ve always understood ‘Qualified real’ to be a “trick” to be able to fit a unitless number into the DV_QUANTITY data type,
[/quote]
That is my understanding, it signifies a unitless number, but I had thought that "1" was a valid UCUM unit, not an openEHR thing. Having said that I can't find any notes on this this in UCUM documentation.
---
## Post #47 by @siljelb
[quote="ian.mcnicoll, post:46, topic:1964"]
I had thought that “1” was a valid UCUM unit, not an openEHR thing
[/quote]
'1' is a valid UCUM unit. Meaningless, but valid :laughing:
---
## Post #48 by @linforest
It's called "unity", if i remember correctly.
---
## Post #49 by @linforest
Thanks, Selje and Ian. Your clarifications are very useful.
[Chinese translation (zh) of the openehr_terminology.xml (Release-3.0.0) is completed.](://github.com/openEHR/specifications-TERM/pull/17)
---
## Post #50 by @linforest
[quote="siljelb, post:45, topic:1964"]
Yes, the units for all the different unit properties are in [PropertyUnitData.xml](https://github.com/openEHR/specifications-TERM/blob/master/computable/XML/PropertyUnitData.xml).
[/quote]
```
```
How to translate this file, including the property name and especially the Unit name? I mean the official way.
---
## Post #51 by @klarapersson
As part of an ongoing project at Region Östergötland ( https://discourse.openehr.org/t/cardiology-templates-and-archetypes/6327/14 ) we are creating a new archetype for echocardiography including measurements set by clinicians. These include some values divided by body surface area (BSA) which are given the unit mm/(m^2), but this unit does not exist in Archetype Designer right now. Is it possible to get some help with adding this unit, or perhaps an option for {LENGTH/AREA}?
---
## Post #52 by @siljelb
The easiest way to get a new unit added is to make the change and create a pull request for this file: [specifications-TERM/computable/XML/PropertyUnitData.xml at master · openEHR/specifications-TERM](https://github.com/openEHR/specifications-TERM/blob/master/computable/XML/PropertyUnitData.xml)
For your specific unit, UCUM `mm/m2` and a new property "Length per area" would probably work, and it may be a good idea to also add the more generic {LENGTH/AREA} as you suggested.
---
## Post #53 by @HHeiser
Quickly dropping in to share a use case around adding non-standard units to `DV_QUANTITY`.
I’m working on medication templates where many dosage units are proprietary and non-SI, e.g. *tube*, *sachet*, *tablet*, or even *piece*. These are the units patients actually understand: “Apply one tube of cream X each morning” or “Dissolve one tablet in water before meals”
Obviously, these units are highly variable and non-standard (the size of a “tube” can differ wildly between products) but they still carry much more meaning for patients than something like *500 mg*, and thus the main administration and prescription units.
At the moment, I handle this in Archetype Designer by manually adding units to each relevant `DV_QUANTITY` element in the `t.json` file, e.g.:
```json
...
}, {
"@type" : "C_PRIMITIVE_TUPLE",
"members" : [ {
"@type" : "C_STRING",
"rmTypeName" : "STRING",
"constraint" : [ "Tube" ]
}, {
"@type" : "C_REAL",
"rmTypeName" : "REAL",
"constraint" : [ {
"lowerIncluded" : false,
"upperIncluded" : false,
"upperUnbounded" : true,
"lowerUnbounded" : true
} ]
}, {
"@type" : "C_STRING",
"rmTypeName" : "STRING",
"constraint" : [ "KISIM" ]
}, {
"@type" : "C_STRING",
"rmTypeName" : "STRING",
"constraint" : [ "Tube" ]
} ]
}, {
...
```
When the file is imported back into AD, these extra units are preserved and not overwritten, which is good.
It works, but is cumbersome and error-prone, especially with multiple dosage fields per template that should have the same units. Maintaining consistency quickly becomes difficult.
I don’t think asking for these units to be added to `PropertyUnitData.xml` really makes sense, given how context-specific they are, but I wanted to share the approach anyway. Maybe it’s useful for others dealing with similar topics, or as a starting point for a more elegant solution.
---
## Post #54 by @siljelb
[quote="HHeiser, post:53, topic:1964"]
many dosage units are proprietary and non-SI, e.g. *tube*, *sachet*, *tablet*, or even *piece*. These are the units patients actually understand: “Apply one tube of cream X each morning” or “Dissolve one tablet in water before meals”
[/quote]
I would question the need to structure this kind of dosing to this level. If you need to represent the patient instruction including dosage, maybe "Dose description" would be sufficient? Otherwise, the "Alternate dose" is intended to be used for dosage representations like number of tablets, but then we're back to your solution of hacking the template file.
---
## Post #55 by @ian.mcnicoll
Quick reply for now The quantity datatype does support non ucum terminology exactly for this purpose. In uk we would use snomed for these kinds of ‘unit'.
---
## Post #56 by @thomas.beale
We want to be pretty careful here. The concept of Quantity is a ‘hard’ physics one, and is intended to make data computable.
Things like ‘sachet’ etc are pre-manufactured doses, and are proxies for real amounts. E.g. you could put ‘1 sachet’ of ‘Lemsip’ (a non-hospital flu product available in the UK, just using it for fun…), but you’ll never know that the patient who receives a sachet is consuming 1000mg of paracetomol. Now apply this to drugs of more serious interest like chemo / immunotherapy…
Doing this kind of data properly should be done via something like the following representation
* drug admin (CLUSTER)
* form = powder
* delivery unit = adult single sachet manufacturer/type xyz
* medication =
* paracetomol
* amount: DV_QUANTITY = 1000mg (ideally derived from some knowledge base that knows what this particular sachet xyz actually has in it)
* diphenhydramine
* amount: …
* etc
*
That phrase ‘delivery unit’ (or it could be ‘product unit’) is not the same kind of ‘unit’ as a scientific unit of measure, at all. It should be in a different field.
I’m skipping over various details, but you know them all. The key however is to think very carefully before making a lot of data just uncomputable…
BTW the real way to do all this properly is with a ref to a drug / preparation database, and a thumbnail copy of the information found there (guaranteeing that the 1000mg / sachet / other details are in the EHR for all time, even if the knowledge base goes away).
---
## Post #57 by @HHeiser
*Disclaimer: The following discussion veers away from the original topic of Archetype Designer and goes deep into clinical modelling…*
Hi Thomas,
thanks for your input. Your concern is reasonable, and we have been grappling with how to properly represent these differences between medication products, their delivered units, and amounts of individual compounds.
TL;DR: Separating delivery dosage units from actual compound amounts in dedicated elements seems reasonable, but even those are currently always`DV_QUANTITY`, which - in current practice - does not seem to be strictly limited to computable SI units.
Your proposed representation sounds good, but from my understanding does not align with the currently published archetypes for this field. Thus, we have found no better option for now than our current approach of storing the ordered and/or administered amount in “*Dose*” of [`CLUSTER.dosage.v2`](https://ckm.openehr.org/ckm/archetypes/1013.1.5948) nested within the “*Structured dose and timing directions*” `SLOT` of [`INSTRUCTION.medication_order.v3`](https://ckm.openehr.org/ckm/archetypes/1013.1.5946), or “*Amount*” `SLOT` of [`ACTION.medication.v1`](https://ckm.openehr.org/ckm/archetypes/1013.1.123).
Although not ideal, we feel that we are within the proposed usage of [`CLUSTER.dosage.v2`](https://ckm.openehr.org/ckm/archetypes/1013.1.5948). In its concept description, the comment specifically mentions delivery units as accepted: “*Comment: For example: '2 tablets at 6pm' or '20 mg three times per day'.*” The description of the “*Dose*” element only mentions SI units, with “*Alternate dose*” being more appropriate: “*For example, can be used to represent a unit-dose based value such as 'tabs', when the Dose amount is expressed as an SI unit such as 'mg',*“. I could be convinced to use “*Dose*” in `CLUSTER.dosage.v2`**solely** for computable SI-unit doses. This highlights a slightly different problem we encountered, how to store the information of which active ingredient within the ordered product the “*Dose*” refers to, especially for compound products (Co-Amoxicillin) or complex mixtures (Smofkabiven) - which we currently persist in “*Dose description*“. Furthermore, “*Alternate dose*” is also a `DV_QUANTITY`, so even using “*Alternate dose*” for “sachet” and “*Dose*” for “1000 mg" would require manually injecting the delivery units into the `t.json`.
Similar story with a different cluster [`CLUSTER.medication_supply_amount.v0`](https://ckm.openehr.org/ckm/archetypes/1013.1.2453), whose “*Amount*” and “*Pack size*” are `DV_QUANTITY` and explicitly refer to delivery units: “*For example: '30' as magnitude and 'tablets' as unit; or '100' as magnitude and 'ml' as unit.*”
We do in fact include, as you suggest, a reference to an external database via [`CLUSTER.knowledge_base_reference.v1`](https://ckm.openehr.org/ckm/archetypes/1013.1.3748) where medication compounds and amounts for the ordered product are stored, just without a copy of this information within the openEHR composition (yet). We are still considering adding this, potentially under the “*Medication details*” SLOT via [`CLUSTER.medication.v2`](https://ckm.openehr.org/ckm/archetypes/1013.1.5947). However, its description explicitly forbids (from my understanding) using this archetype for storing delivery units: “***Misuse**: Not to be used to record the intended or administered dose of a medication. Use either the INSTRUCTION.medication_order or the CLUSTER.dosage archetypes for this purpose.*”.
Furthermore, we store a reference to an external unit conversion database that knows how much compound is in a product and can (to some degree) convert a “500 mg” order by a doctor into an administrable “tablet” for the nurse. However, due to the problems listed above, this conversion happens outside of openEHR at the moment.
---
## Post #58 by @Brice
One way to model these types of drug units, which are not a physical quantity, is with ‘qualified real’. Provided the pharmaceutical form of the drug has been specified in the prescription, I believe the model can be consistent.
---
## Post #59 by @thomas.beale
[quote="HHeiser, post:57, topic:1964"]
Your proposed representation sounds good, but from my understanding does not align with the currently published archetypes for this field. Thus, we have found no better option for now than our current approach of storing the ordered and/or administered amount in “*Dose*” of [`CLUSTER.dosage.v2`](https://ckm.openehr.org/ckm/archetypes/1013.1.5948) nested within the “*Structured dose and timing directions*” `SLOT` of [`INSTRUCTION.medication_order.v3`](https://ckm.openehr.org/ckm/archetypes/1013.1.5946), or “*Amount*” `SLOT` of [`ACTION.medication.v1`](https://ckm.openehr.org/ckm/archetypes/1013.1.123).
[/quote]
Appreciate all the difficulties here. I would just say the the wider modelling plus tech community really does need to think about whether we want to be able to run reliable machine queries that will find out if e.g. a patient is getting too much paracetomol or whatever, due to admin of admixture drugs, or even if the doses of their medications are correct. If we are going to put ‘sachet/drop/ whatever’ in the central quantity representing the dose of each substance (or worse, just at the level of premixed drugs), then doing such queries is much more complicated - they rely on being able to convert 1 sachet of product xyz to N mg of ingredient A, M mg of B and so on. Assuming a knowledge base / master drug data repo is even available, doing this every time on query is bad, because subtle changes in the knowledge base will bring back wrong answers and no-one will ever know. Any such conversion should be performed on initial commit.
The alternative is to give up on being able to compute reliably on dosing of a lot of medications. Indeed, if quantity units can be things like ‘sachet’ etc, one can’t even know for which drugs such queries can be trusted. One might expect that queries for doses of chemo drugs should actually return correct answers, but how would anyone know if some pseudo amount is being used in some chemo related application?
Many possibilities even for secondary data use (research etc) are compromised badly by the use of pseudo units in quantities.
---
## Post #60 by @siljelb
[quote="HHeiser, post:57, topic:1964"]
how to store the information of which active ingredient within the ordered product the “*Dose*” refers to, especially for compound products (Co-Amoxicillin) or complex mixtures (Smofkabiven) - which we currently persist in “*Dose description*“
[/quote]
IIRC, the intent here was that compound products or mixtures should be dosed by the relevant unit of the ordered product or mixture. For example, co-codamol (paracetamol/codeine) is dosed in tablets (AKA UCUM `1`), and kabiven usually in ml of the finished mixture based on a number of `g/kg/d` (nitrogen/bodyweight/day).
Incidentally, lots of other medications need to be dosed using units such as "puffs" etc, but the intent was that these should be put in the "Alternate dose" element, with the "Dose" reserved for UCUM (not necessarily SI) units.
[quote="HHeiser, post:57, topic:1964"]
We are still considering adding this, potentially under the “*Medication details*” SLOT via [`CLUSTER.medication.v2`](https://ckm.openehr.org/ckm/archetypes/1013.1.5947). However, its description explicitly forbids (from my understanding) using this archetype for storing delivery units
[/quote]
Correct. The two "amount" elements in "Medication details" are only intended for recording ad-hoc mixtures of known quantities of different components. The complete mixture would then be dosed using an appropriate unit using the "Dosage" archetype.
[quote="HHeiser, post:57, topic:1964"]
Furthermore, “*Alternate dose*” is also a `DV_QUANTITY`, so even using “*Alternate dose*” for “sachet” and “*Dose*” for “1000 mg" would require manually injecting the delivery units into the `t.json`.
[/quote]
I see this is a problem, although maybe more a problem of tooling rather than of modelling? If you leave the unit of "Alternate dose" unconstrained in your template, shouldn't you be able to inject whichever unit string you want at runtime from your conversion db?
---
## Post #61 by @ian.mcnicoll
Sorry @Thomas - I’m going to have to disagree again!! (Not like me I know).
’Product-based’ prescribing is a very well-established approach in many different countries, including the UK, particularly in community settings. The purpose is to give clear instructions to the person adminstering or taking the medication in an unsupervised setting like primary care
So an order like “Flucloxacillin capsules 250mg 2 cap four times daily” is completely normal, and is explicitly supported by the openEHR models. Clearly it does introduce some complexity in moving between this approach and the ‘Dose-based prescribing’ equivalent like “Flucloxacillin 500mg 4 times daily” as would be more typical in UK hospital systems but there has been a lot of work done to make this possible. THe NHS Meds team have some very nice documentation based on FHIR but the same principles apply- a snippet here - https://simplifier.net/guide/ukcoreimplementationguideformedicines/Use-Case-Medications-on-Admission?version=current
In the UK, and I suspect elsewhere, there are regular attempts to unify and go with mode or the other but in reality this collides with a whole lot of massive barriers - - staff retraining, primary legislation changes, wholesale system changes, which means we are almost certainly stuck with having to support for some time if not forever.
One critical aspect is to be able ot capture the ‘dose unit’ as a coded item. not just as text.
DV_QUANTITY was adjusted some time ago now to allow non-UCUM codesystems, explicitly to support ‘dose units’ like ‘tablet’, ‘capsule’ e,g a SNOMED terms.
Prior to that, there were separate quantity (as q qualified real’ and unit elements but this was very messy to explain and implement.
FWIW this is now aligned with FHIR Quantity
https://specifications.openehr.org/releases/RM/Release-1.1.0/data_types.html#_dv_quantity_class
So my suggestion is to use this to represent the ‘recorded’ prescribed quantity i.e. if the prescriber is using product-based then use 'dose units’ if dose-based’ then use SI units, though this is not always possible for mixed preparations.
Alternate dose can then be used to carry the dose-based equivalent if this is helpful.
To calculate that alternate ‘SI dose’, as others have said you either have to capture the form and strength of the ‘dose unit’ in the CLUSTER.medication archetype, or , as @Thomas suggested make use of knowledge within the drug terminology. We have this in the UK with the dm+d terminology which essentially captures the key information about the medication product to be able to make that conversion, and the UK Meds team did have that working as a demonstrator. We feel confident enough about version management of dm+d such that we do not feel the need to explicitly duplicate the product strength/ form details in the patient record (in Cluster. Medication) but we know that folks in other jurisdictions do not have the same confidence.
So right now, after an explicit request to add ‘dose unit’ support to DV_QUANTITY, with changes to the dosage archetype made in response, we do have a standard approach, which happens to line up with FHIR.
---
## Post #62 by @thomas.beale
[quote="ian.mcnicoll, post:61, topic:1964"]
’Product-based’ prescribing is a very well-established approach in many different countries, including the UK, particularly in community settings. The purpose is to give clear instructions to the person adminstering or taking the medication in an unsupervised setting like primary care
[/quote]
Yep, I know this of course, and it has to be supported (clearly), and obviously the models must reflect this reality, or data won’t even be captured properly in the first place. So, no argument from me.
Now to details:
```
Flucloxacillin capsules 250mg 2 cap four times daily
```
This is an Instruction, i.e. an order, in a form that can be directly acted upon.
However, when each admin Action is recorded (assuming that they are…), you ideally want two things to be stated:
* A) that the two caps were taken by the patient, i.e. that the prescribed admin act was carried out - I would not necessarily even use DV_QUANTITYs here
* B) the actual real dose - computed once (not many times later) of each ingredient in the formula - these need to be DV_QUANTITYs
A) tells later users of the record that one administration was completed at time T by HCF X etc, and B) provides a computable form of what actual amounts of what substances were put into the patient’s body.
[quote="ian.mcnicoll, post:61, topic:1964"]
We feel confident enough about version management of dm+d such that we do not feel the need to explicitly duplicate the product strength/ form details in the patient record (in Cluster. Medication) but we know that folks in other jurisdictions do not have the same confidence
[/quote]
Theoretically I would trust DM+D as well, but that’s not really the point; at some point it will turn into something else (maybe due to privatisation, along with the rest of the NHS…) and patient lifelong health records containing refs into DM+D suddenly can’t be computed with. If the relevant meta-data exists in DM+D, it should be used to compute the true admin dose values once for each INstruction, as a kind of ‘template’ sub-Cluster whose meaning is ‘effective dose description’, containing the computed effective doses of each ingredient (to cover mixtures). Each subsequent Action would record a copy of this Cluster, with any modification needed, e.g. if only one cap were given on the 4th dose (not going to happen with anti-biotics, but common with steroids or similar).
The other reason you can’t ‘trust DM+D’ is that the data will one day turn up in the EHR system of a Japanese cruise ship for a sick UK traveller and they just won’t have DM+D available to resolve anything; same in reverse for say a Korean patient visiting Spain, and so on.
If we want lifelong health records that are properly computable over decades, and don’t rely on temporary / local knowledge resources, I don’t see a way out of doing something like the above.
---
## Post #63 by @ian.mcnicoll
I had thought the discussion above was about Instructions not Actions but I take the point about the challenge of knowing exactly the substance amount administered.
---
## Post #64 by @siljelb
The actual administered dose (as well as form, route, etc) needs to be recorded as part of the ACTION, as it can change for any number of reasons when theory (order) hits reality (administration).
But if a specific product is recorded as administered (even if the order is for a generic substance, the dose actually administered will usually be a specific product), it should be possible to calculate the amount of active substance either at the time of recording or at a later date given enough information about the product.
---
## Post #65 by @thomas.beale
[quote="siljelb, post:64, topic:1964"]
it should be possible to calculate the amount of active substance either at the time of recording or at a later date given enough information about the product
[/quote]
Yes… ‘should’…! If it can be done at the time of creation of Instruction or at worst, the Actions, it should. Leaving it till later means it will never be done. But committing non-computable info in the first place just means the EHR is non-computable, at least for this purpose (meds dosing).
---
## Post #66 by @ian.mcnicoll
@HHeiser
[quote="siljelb, post:60, topic:1964"]
IIRC, the intent here was that compound products or mixtures should be dosed by the relevant unit of the ordered product or mixture. For example, co-codamol (paracetamol/codeine) is dosed in tablets (AKA UCUM `1`), and kabiven usually in ml of the finished mixture based on a number of `g/kg/d` (nitrogen/bodyweight/day).
[/quote]
I might have said something a little different for co-codamol, though I appreciate this is not the current guidance in the archetype. I’d still prefer for the ‘dosage’ to represent the original instruction given, so ‘1-2 tablets’, where the ‘tablet’ would be carried in the extended Quantity structure and use alternateDose for the derived dose
---
## Post #67 by @klarapersson
Thank you! How long does it usually take before the change is implemented in Archetype Designer?
---
## Post #68 by @siljelb
It's probably a good idea to notify Better about the change once the pull request has been merged.
---
**Canonical:** https://discourse.openehr.org/t/adding-to-the-dv-quantity-units-options/1964
**Original content:** https://discourse.openehr.org/t/adding-to-the-dv-quantity-units-options/1964