ConceptMap tutorial
ConceptMap is a FHIR resource that allows you to establish a one-way map between codes. We'll use latter as an example in this tutorial to demonstrate how two concepts can be related (mapped) to each other and how their equivalence (or lack of) can be specified.
Урок по ConceptMap
ConceptMap - это ресурс FHIR, который позволяет установить одностороннее сопоставление между кодами. Мы будем использовать его в качестве примера в этом уроке, чтобы продемонстрировать, как два понятия могут быть связаны (сопоставлены) друг с другом и как может быть указана их эквивалентность (или её отсутствие).
Contents Содержание
Step 1: About ConceptMap Шаг 1: О ConceptMap Step 2: Sample data mapping Шаг 2: Пример сопоставления данных Step 3: Sample resources Шаг 3: Примеры ресурсов Step 4: Advanced features Шаг 4: Расширенные возможности Step 5: $translate operation Шаг 5: Операция $translateStep 1: About ConceptMap Шаг 1: О ConceptMap
The ConceptMap resource in general has four parts to it:
- Metadata about the resource
- The source of the data
- The target the data is mapped to, and
- The groups of mappings themselves
Metadata describes general information about the mapping - who made it, what version it is, copyright...etc.
Source is a reference to the ValueSet that you are mapping from. Remember that ConceptMap is a one-way mapping so there's always a clear source and a target.
Target is similar to source - it is a reference to the ValueSet you are mapping to.
Mappings are the translations themselves, organised in groups. Each mapping (called an 'element' in the data) can have one or more target elements, which specify a connection between a code from one ValueSet to code(s) in another ValueSet. The type/strength of connection is described by the equivalence property. In FHIR R4, the equivalence codes include: relatedto (concepts are related but exact relationship unknown), equivalent (identical meaning), equal (exactly the same), wider (target is broader), subsumes (target encompasses source), narrower (target is more restrictive), specializes (target refines source), inexact (overlap but imprecise boundaries), unmatched (no corresponding concept), and disjoint (explicitly no mapping exists). The full list with detailed definitions is available in the ConceptMap Equivalence ValueSet.
Ресурс ConceptMap в по сути имеет четыре части:
- Метаданные о ресурсе
- Источник данных
- Цель, к которой сопоставляются данные, и
- Группы самих сопоставлений
Метаданные описывают общую информацию о сопоставлении - кто его создал, какая версия, авторские права и т.д.
Источник - это ссылка на ValueSet, из которого вы выполняете сопоставление. Помните, что ConceptMap - это одностороннее сопоставление, поэтому всегда есть четкий источник и цель.
Цель похожа на источник - это ссылка на ValueSet, к которому вы выполняете сопоставление.
Сопоставления - это сами переводы, организованные в группы. Каждое сопоставление (называемое 'элементом' в данных) может иметь один или несколько целевых элементов, которые определяют связь между кодом из одного ValueSet с кодом(ами) в другом ValueSet. Тип/сила связи описывается свойством эквивалентности. В FHIR R4 коды эквивалентности включают: relatedto (понятия связаны, но точное отношение неизвестно), equivalent (идентичное значение), equal (точно такое же), wider (цель шире), subsumes (цель охватывает источник), narrower (цель более ограничена), specializes (цель уточняет источник), inexact (перекрытие, но неточные границы), unmatched (нет соответствующего понятия), и disjoint (явно нет сопоставления). Полный список с подробными определениями доступен в ValueSet эквивалентности ConceptMap.
Step 2: Sample data mapping Шаг 2: Пример сопоставления данных
As an example, let's say you have a (very poorly designed) ValueSet based on a CodeSystem representing employee presence at work with just three codes: present, not-present, and sick which is in use by your system. You start importing data from a new system which has finer granularity:
В качестве примера, предположим, у вас есть (очень плохо спроектированный) ValueSet, основанный на CodeSystem, представляющем присутствие сотрудников на работе всего с тремя кодами: present, not-present и sick, который используется вашей системой. Вы начинаете импортировать данные из новой системы, которая имеет более детальную градацию:
| Current valueset Текущий valueset | New system's valueset Valueset новой системы |
|---|---|
| present | in-office |
| not-present | away-travelling |
| sick | working-from-home |
| annual-leave | |
| personal-leave | |
| jury-duty |
Your task is to create a FHIR ConceptMap translating the codes your receive to codes you already have, making use of the available equivalence values. You come up with this sample mapping that maps in the direction from the new system to your system's ValueSet:
Ваша задача - создать FHIR ConceptMap, переводящий коды, которые вы получаете, в коды, которые у вас уже есть, используя доступные значения эквивалентности. Вы создаете этот пример сопоставления, который сопоставляет в направлении от новой системы к ValueSet вашей системы:
| New system's valueset Valueset новой системы | Current valueset Текущий valueset | Equivalence code Код эквивалентности |
|---|---|---|
| in-office | present | equal |
| away-travelling | not-present | wider |
| working-from-home | not-present | wider |
| annual-leave | not-present | wider |
| personal-leave | sick | equal |
| jury-duty | not-present | wider |
| away-travelling | present | disjoint |
Step 3: Sample resources Шаг 3: Примеры ресурсов
A sample ConceptMap resource containing these mappings is available. The supporting CodeSystem, old ValueSet and new ValueSet are available as well.
Press the button below to upload these resources to the FHIR server!
Доступен пример ресурса ConceptMap, содержащий эти сопоставления. Также доступны поддерживающие CodeSystem, старый ValueSet и новый ValueSet.
Нажмите кнопку ниже, чтобы загрузить эти ресурсы на FHIR сервер!
The ConceptMap resource will be available at this URL:
Ресурс ConceptMap будет доступен по этому URL:
Once uploaded, it'll look something like this when you GET the ConceptMap via Postman.
После загрузки он будет выглядеть примерно вот так, когда вы получите ConceptMap через Postman.
Step 4: Advanced features Шаг 4: Расширенные возможности
ConceptMap is actually pretty powerful, and besides the basic code-to-code mapping described above, it also supports the following usecases:
ConceptMap на самом деле довольно мощный, и помимо базового сопоставления код-к-коду, описанного выше, он также поддерживает следующие случаи использования:
- Сопоставление одного кода с несколькими кодами одновременно при одинаковом свойстве эквивалентности (путем использования нескольких свойств target в рамках одного свойства element)
- Наличие зависимости для сопоставления, сопоставление может быть применимо только если выбранный элемент существует в данных и имеет указанное значение (см. dependsOn)
Step 5: $translate operation Шаг 5: Операция $translate
The $translate operation allows you to utilise a FHIR terminology server to get an equivalent code as specified by a ConceptMap mapping. To use it, you need to provide the ConceptMap you'd like to use, the input code and its CodeSystem, and the target valueset you'd like to translate to.
Try the $translate operation on the ConceptMap you uploaded above via Postman. For example, to translate the code "in-office" from the new system to your current system's valueset, use:
This will return the mapping showing that "in-office" translates to "present" with an equivalence of "equal".
That's it! You're done for now.
Операция $translate позволяет использовать терминологический сервер FHIR для получения эквивалентного кода, как указано в сопоставлении ConceptMap. Для её использования вам нужно предоставить ConceptMap, который вы хотите использовать, входной код и его CodeSystem, а также целевой valueset, в который вы хотите перевести.
Попробуйте операцию $translate на ConceptMap, который вы загрузили выше, через Postman. Например, чтобы перевести код "in-office" из новой системы в valueset вашей текущей системы, используйте:
Это вернет сопоставление, показывающее, что "in-office" переводится в "present" с эквивалентностью "equal".
Вот и всё! На данный момент вы закончили.