Stream: terminology
Topic: Displays in expansions
Joshua Bell (Jan 12 2018 at 09:13):
Am I mistaken to believe that Displays in a ValueSet are supposed to show in the expansion as first priority over the CodeSystem display? In two different implementations I've tested ValueSet expansion I have not observed the behavior I was expecting. If you go here: http://clinfhir.com/valuesetCreator.html and search for mfOverride and expand the valueset it shows Male and Female when it should show Girl and Boy. (This terminology server is Ontoserver). When the server expands it is using the CodeSystem display and not the ValueSet display.
I've also observed the same behavior in hapi fhir server (although inconsistent, this only happens with uploaded codesystems, not manually created ones - which do exhibit the behavior I expect). So it seems like I am misunderstanding, or it is really just implemented incorrectly in multiple projects.
I was under the impression ValueSet display overrides the CodeSystem display based on the docs. I did find however, at the bottom of https://www.hl7.org/fhir/valueset.html#compositions, that it says the display should be in an alternate location like text. But I don't seem to see anyone implementing the alternate display in text or any other field within the expansion array. Please advise me on proper usage and where to expect overriden displays. Am I intended in a front end application to call expand and then further have to parse and search the composed concepts for proper displays? Or should the expanded set have their displays be the expected UI display?
Rob Hausam (Jan 12 2018 at 13:34):
Thanks, @Joshua Bell, for continuing to push on this. As you've been observing, this behavior has been pretty inconsistentlyy implemented and we haven't really paid a whole lot of attention to it before. I think we need to do some testing for it in the Connectathon Terminology Services track, and I'll see about adding something for that. @Richard Ettema and @Peter Jordan and I have been discussing the updates for testing. If you have something that you would like to contribute for it (I'll look back through this and the "synonyms" topics for a start), that would be great.
Peter Jordan (Jan 12 2018 at 20:30):
It's worth considering the differing displays returned in SNOMED-based implicit ValueSets generated from text filters by using Ontoserver's comparison tool http://ontoserver.csiro.au/vstool/. Select the OntoServer, Health Intersections and Terminz servers and search for 'Heart attack'. Then, maybe, search for that term in the SNOMED International Browser. Of course, text/type ahead type searching via UIs is a distinct use case - but it's an important one that needs to satisfy the requirements of end users as well as those of terminologists.
Joshua Bell (Jan 12 2018 at 21:37):
I suppose the best contribution to this from me right now would to be outlining what I am expecting to be able to do with it in my use case. In our UI we want users to be able to search for a term that they see in some medical document. Let's go with some drug ingredient, in this case, "mercaptopurine" which is also known as "6-MP". It is possible for the document the user is reading to show either of those names, so we've prepared a valueset of ingredients that contain two of the same concept but each with the different display name. In order for the UI to work the expanded set the UI is supposed to call needs to contain the concept more than once, one for each display name. (See the properly representing synonyms chat where Graham has implemented this on his test server). Furthermore, we have a filtered dropdown so the filter param should be able to search and filter on both displays as well (it does not need to show both when one is present, just clarifying that it shouldn't skip any). The user clicks their choice and the UI simply saves the concept (we don't actually care which display they click in our use case).
Later on we may display this information later, and so we would like a way to flag one of the concepts as the preferred way to display it in said valueset. We don't want to use the CodeSystem endpoint as our final display is also usually different than the one in the CodeSystem as well (like we want "Male" instead of "Male (finding)"). So we want to validate the code on the valueset to retrieve the display of some concept, but if there are two concepts in there one needs to be flagged as the primary one to return when given just the code/system. So if 6-MP is the primary, a user selects mercaptopurine and then later we display it by validating the system/code pair which would return the concept with a display 6-MP.
- Display synonyms
- Primary display flag
- Expansion and validation on these by system/code pairing
Robert McClure (Jan 15 2018 at 16:46):
@Joshua Bell and @Grahame Grieve What I'd like to see us do is expect that an expansion profile (not sure how...) would be why an expansion generates multiple display values like you demonstrated for administrative gender (https://chat.fhir.org/#narrow/stream/terminology/subject/How.20to.20properly.20represent.20Synonyms/near/118029). I didn't follow Graham how you are suggesting the expansion include the additional synonymous descriptions but I'd rather see that based on an expansion profile when the additional descriptions are in the code system already. If they are not, then I'd prefer that they be added via code system supplement this is referenced in an expansion profile to bring in the supplement to provide the additional descriptions.
I suspect you may think that pedantic, but the supplement would then be shareable, reusable, and maintainable. What Joshua wants will not be unique so it would be better if it was not done inside a value set. That said, I'm open to learning how we do this simply inside a value set too for situations that are very unique.
Joshua Bell (Jan 15 2018 at 17:31):
@Robert McClure So what you are suggesting is that all display synonyms should be in the CodeSystem and the expansion profile elects to show them or not?
I think this could present problems, because the display synonym may have nothing to do with the CodeSystem but rather on an application level. I could be making a space game powered by FHIR and am using Male/Female but want it to show up as some weird alien synonym like Malla/Felle but still be using a snomed codesystem underneath. Because my app wants the display "Malla" for male doesn't mean that malla should be added to the base CodeSystem as a synonym, and probably shouldn't be added at that level. CodeSystem should be the "purest" form and only have what is officially put into it by its maintainers correct? If that's so then the Malla/Felle would need to live on the ValueSet how we've already proposed in the synonyms chat. -> and now sort of off topic for here, but rather synonyms discussion. It leads to the question of concept synonyms, defined synonyms in a system, and then now the added layer of application specific synonyms. How are these all to be handled?
Robert McClure (Jan 15 2018 at 19:43):
@Joshua Bell No, that is not what I am saying. I suspect you don't know what I mean by "code system supplement." This would be an artifact that you can create, and then directly reference, that supplements the code system information with additional information for concepts identified in the code system. So your game -focused supplement would provide your own synonyms to the concepts. Of course, you must respect the intent of the code system. Yes, we agree about not putting your synonyms into the "base" code system, but no, your synonyms do not need to live in the value set, and IMO should not be there. BTW, synonyms seem to be what you mean by "displays in expansions" so synonyms are not off topic, they _are_ the topic.
Michael Lawley (Jan 15 2018 at 21:23):
@Joshua Bell This behaviour with displays in ValueSets is on our roadmap for Ontoserver, but requires quite significant internal changes to the implementation mechanisms. Because of this we've been waiting for our customers to provide feedback indicating they need/want this capability. To date we've only had one, and it was an inquiry about whether the capability existed rather than a request for it.
Michael Lawley (Jan 15 2018 at 21:34):
I note that @Joshua Bell 's use case of Malla/Felle is exactly what the ValueSet-provided display text would be used for. CodeSystem.supplement would be a terrible way to do this because it would affect every ValueSet using the code system, not just those for the game.
However, most cases we've seen have been more like the "mercaptopurine" which is also known as "6-MP", in which case the CodeSystem itself is really missing a synonym. Using CodeSystem.supplement is one way around this, but actually updating the source CodeSystem itself is better and helps everyone. (Having an NRC that does monthly SNOMED updates also helps :-)
Lloyd McKenzie (Jan 15 2018 at 22:45):
It might be possible to do it as a "contained" Code System Supplement - though FHIR hasn't really talked about containing things that are referenced by cannonical URLs...
Robert McClure (Jan 16 2018 at 00:14):
@Michael Lawley I am not aware that a code system supplement is something every use of the code system must use. That makes no sense to me at all. I have always considered a supplement an artifact that adds content to the code system for "local" use. It can be shared and reused more broadly, but would not affect every value set using the code system - it is a supplement. If you all have something different in mind I'd like to see the use case and am at this point very opposed to such a restriction for supplements. There are good existing usecases for what I have described. What you are describing is a request to modify the code system itself.
Lloyd McKenzie (Jan 16 2018 at 00:52):
Supplements are used when updating the code system isn't possible/practical. I agree that incorporating all needed information in the code system is the preferred approach when it's workable. However, if you're looking to define Japanese translations of X12 codes, you're not likely to find a lot of energy in X12 to get those in and maintain them :)
Michael Lawley (Jan 16 2018 at 13:01):
@Lloyd McKenzie but translations can be done with ValueSets (as described in this thread https://chat.fhir.org/#narrow/stream/terminology/subject/Code.20System.20Supplements
Michael Lawley (Jan 16 2018 at 13:04):
@Robert McClure If my terminology server has a code system supplement loaded, how do I know which ValueSets should be affected by it?
Robert McClure (Jan 16 2018 at 17:10):
@Michael Lawley I've always assumed that code system supplement use had to be evoked specifically. It can be included in the value set CLD as a determinant for member inclusion in an expansion (i.e.: drugs with a cost above $50 as identified in a drug cost supplement), and it can be used in an expansion profile (i.e.: to add in additional descriptions as in Joshua's example). In all these cases it would be explicitly identified, either in the CLD, or in a profile used for the expansion. I don't know of a use case where it would be needed when it was not specifically identified.
Lloyd McKenzie (Jan 16 2018 at 19:46):
The same issue applies for defining properties (e.g. what LOINC codes are considered to be 'orderable' in Canada isn't something we'd expect Regenstrief to take on the maintenance of - and isn't really something we'd want them to)
Rob Hausam (Jan 16 2018 at 23:41):
I agree with Rob M. that the way to do this is to specify the code system supplement in the value set definition or in an explansion profile - but it should be explicit.
Grahame Grieve (Jan 19 2018 at 10:40):
I don't agree. With language code supplements, at least, the use case for automatically using them everywhere is obvious - I provide the terminology server with a spanish language supplement, I very much expect that it will be used for any expansion/validation where the language is specified as spanish
Grahame Grieve (Jan 19 2018 at 10:41):
I think it would be stupid to say that the supplement must be referenced explicitly.
Lloyd McKenzie (Jan 19 2018 at 15:50):
I see two use-cases. 1. If the value set definition is dependent on properties from the supplement, then the supplement must be declared in the value set. 2. If the expansion is going to make use of display names from a supplement then the supplement must be declared in either the value set or the expansion definition
Robert McClure (Jan 19 2018 at 18:30):
@Grahame Grieve Stupid huh? Well, us three stupid people don't agree with forcing every terminology service to incorporate every supplement created. If you think Spanish should be included with every expansion of some code system, put it into the code system.
Lloyd McKenzie (Jan 19 2018 at 18:42):
Putting it into the code system typically isn't possible.
Robert McClure (Jan 19 2018 at 19:03):
Then perhaps we can add this to the terminology server capability statement so that it would be clear that a particular server is always including a supplement when operating on a code system? Then any use of the supplement would not need to be explicitly included for use, but could (and I think should) be for interop value.
Lloyd McKenzie (Jan 19 2018 at 21:36):
Is there a reason why including it in the value set definition or the expansion profile would be inappropriate?
Rob Hausam (Jan 19 2018 at 22:18):
I don't think it would be inappropriate. I think Grahame is suggesting using displayLanguage as a surrogate in lieu of having to specify the supplement itself explicitly. I can see why you would think of doing that, but if you have to specify the language then it's probably not much of a further step to also specify the supplement that should be used. I think it should be specified explicitly somewhere. I don't think it would be common, but since code system supplements aren't controlled (or maybe even know about) by the code system publisher, it seems conceiveble to me that there could be more than one supplement available on a server for a given use (e.g. for a particular language) - and then you would need to specify which one should be used in a particular instance. But if we made a default declaration globally that was reflected in the terminology capability statement, then that would work and would avoid the need to make the explicit reference each time. You would only need to do it if you wanted to override the default.
Grahame Grieve (Jan 20 2018 at 05:13):
"but if you have to specify the language then it's probably not much of a further step to also specify the supplement that should be used" - I think it's a big difference. language specifies an outcome but delegates the implenentation to the server. Choosing a supplement means you get involved in the process
Rob Hausam (Jan 20 2018 at 05:42):
Yes, that is a good point. But I think I was reflecting something at least close to that in the latter part of what I said. Is there a reason that the server can't or shouldn't declare what it will do in this regard in its terminology capability statement (assuming that we provide a means for that and that server providers have time and opportunity to implement it)? We don't demand that servers document and declare everything that they do, but declaring the behavior and source(s) of additional content being provided beyond the specified code system when a value set is expanded under specific conditions seems like it would be good to support and encourage (even if we don't mandate it)?
Grahame Grieve (Jan 20 2018 at 05:43):
well, let's start with agreeing that it should be possible to determine server behaviour in this respect by asking it.
Grahame Grieve (Jan 20 2018 at 05:45):
I'm not sure that terminology capabilities are the only/correct answer here. A server doesn't list all the code systems it supports in the terminology capabilities - not if you can search for them on the CodeSystem end-point. So shouldn't the same consideration apply?
Rob Hausam (Jan 22 2018 at 13:15):
Yes, we can start with agreeing that it should be possible to determine the server behavior in regard to code system supplements by asking the server. And I agree with you that using TerminologyCapabilities isn't necessarily required for that. Searching the CodeSystem endpoint is a way (and probably the most straightforward way) to do it.
Michael Lawley (Jan 29 2018 at 23:10):
It seems to be there are just a few dimensions of variability here that we need to look at:
1. The ability to explicitly control, on a per operation basis, which supplements (if any) are usable
2. What is the default behaviour in the case that an explicit indication is not provided.
For 1. I see that there are 3 main cases:
a. don't use any supplements
b. only use an explicitly specified set/list of supplements (not sure if there's order-dependent semantics here)
c. use all available supplements
There's a fourth case: use all available supplements except those in an explicitly specified set/list, but I'm not sure we need to go there
For 2. I would argue for (a) don't use any, as this is backward-compatible behaviour.
The TerminologyCapaility statement can specify which of a, b, and c are supported (and I'd like to suggest a MUST always be supported)
Joel Schneider (Jan 30 2018 at 15:47):
In cases where a code system has multiple supplements, there may also be a question regarding which supplement takes precedence, possibly depending on other factors.
Robert McClure (Jan 31 2018 at 20:26):
@Joel Schneider and @Michael Lawley I think you two are describing uses of supplements that we don't allow. First, take a look at https://gforge.hl7.org/gf/project/fhir/tracker/?action=TrackerItemEdit&tracker_item_id=14645&start=0. The expectation is that use of a supplement is specified in a very specific place and only one can be specified. If a terminology service decides to pre-apply a supplement to every use of the code system, they get to decide how to address any "dependencies" or precedence. They should make this clear in the TS capability statement somehow.
Joel Schneider (Jan 31 2018 at 20:30):
So then, for example, a terminology server could not host more than one language-specific supplement per code system? (e.g. English, French, German)
Grahame Grieve (Jan 31 2018 at 20:39):
@Joel Schneider - a terminology server can host more than one language pack. There's nothing stopping that
Robert McClure (Jan 31 2018 at 21:06):
Yes, as many as you need. If you want to include multiple supplements in your default use of a code system, you would have to decide precedence.
Michael Lawley (Jan 31 2018 at 23:37):
@Robert McClure Thanks, but that is where I started and what triggered all my questions. The behaviour described there is very incomplete and seems to be written with an implied use-case / context-of-use.
Specifically, if supplements is populated, then what other fields in CodeSystem can / can not be populated?
If the intent is only to allow designations and properties to be added, then here's some open (for me) questions:
1. does this mean only brand new properties, or new values for existing properties?
2. if it allows defining new properties, then can they also be made available for filters?
3. is it valid to populate concept.code.display? perhaps only valid if it is the same as the value for the supplemented CodeSystem?
4. how do supplements interact with CodeSystem versions? If my terminology server contains 20+ versions of the SNOMED code system (it does), can I supplement each one separately?
Grahame Grieve (Feb 01 2018 at 11:32):
1. both brand new properties, and new (additional) values for existing properties)
2. yes
3. yes
4. very good question. Version in supplement using | (see canonical URLs)
Michael Lawley (Feb 02 2018 at 00:37):
1. so they will always be additional, and not replacing (I hope so)
3. what if it changes from version to version? Is best-practice to leave empty?
5. must all other CodeSystem fields be empty / same as the supplemented version? If the latter, then what about changes between versions? Is best-practice to leave empty?
Last updated: Apr 12 2022 at 19:14 UTC
