# Як нормалізувати медичні дані

> Посібник: перетворіть медичні дані з багатьох джерел в одну порівнянну форму — пошук за LOINC, одиниці UCUM, дати ISO, діапазони посилань, відсутність дублікатів при повторних спробах та валідація за європейським лабораторним профілем.

Source: https://developers.anpheros.com/uk/guides/normalize-medical-data

**Нормалізація медичних даних означає перетворення значень, які надходять у різних формах, в одну порівнянну форму: однаковий код для одного й того ж тесту, однакова система одиниць вимірювання, дати в одному форматі, кожне значення з його діапазоном посилань та його джерелом, і без дублікатів.** Цей посібник показує, як це зробити перед тим, як дані потраплять до запису HL7 FHIR R4: пошук кодів LOINC та ATC, використання одиниць UCUM, відхилення неоднозначних дат, збереження діапазонів, уникнення дублікатів при повторних спробах та перевірка результату за європейським лабораторним профілем. Кожна показана відповідь надходить з Anpheros API.

## Чому це важливо

Той самий результат HbA1c може надійти до вас як "HbA1c 6,4 %", "Гемоглобін глікований: 6.4", "Glycated haemoglobin 46 mmol/mol" або лише лабораторний код, який розуміє одна лабораторія. Доки вони не стануть одним кодом з однією одиницею вимірювання:

- діаграма показників HbA1c пацієнта з часом показуватиме три непов'язані лінії;
- сповіщення про "HbA1c вище 6,5 %" пропустить два зі значень;
- модель ШІ побачить чотири факти замість однієї тенденції;
- інша система, що отримує запис, не зможе його інтерпретувати.

Нормалізація повинна відбуватися в момент надходження даних до запису, один раз, а не в кожному додатку, який згодом їх читає.

## Що містить нормалізоване значення

| Частина | Нормалізована форма | Приклад |
|---|---|---|
| Що вимірювалося | код зі стандартної системи | LOINC `4548-4` (HbA1c), RxNorm `6809` (метформін), ICD-10 `E11` (цукровий діабет 2 типу) |
| Значення | число або текст, тільки якщо результат не є числовим | `6.4` |
| Одиниця вимірювання | UCUM | `%`, `mg/dL`, `mm[Hg]`, `kg` |
| Коли | дата-час за стандартом ISO 8601, із зазначенням часового поясу, якщо час має значення | `2026-10-01T07:30:00Z` |
| Нормальний діапазон | нижнє та верхнє значення в тій самій одиниці вимірювання | `4.0`–`5.6` |
| Джерело | хто його створив і з якої системи | `import` з `labx` |
| Ідентифікатор | щось, що робить повторний запис впізнаваним | ключ ідемпотентності або ідентифікатор джерела |

Яка кодова система відповідає якому типу ресурсу, перелічено в розділі [Кодові системи FHIR](https://developers.anpheros.com/uk/guides/fhir-code-systems).

## Крок 1: знайдіть код

Шукайте термінологію платформи за англійською або румунською назвою, або за скороченням:

```bash
curl "https://platform.anpheros.com/v1/terminology/loinc?q=hba1c" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/terminology/loinc?q=hemoglobina%20glicozilata" -H "Authorization: Bearer $KEY"
```

Обидва повертають однакове поняття:

```json
{"data": [{"system": "http://loinc.org", "code": "4548-4", "display": "Hemoglobin A1c/Hemoglobin.total in Blood",
           "display_ro": "Hemoglobină glicozilată (HbA1c)", "category": "laboratory", "unit": "%"}], "total": 1}
```

Для ліків, [Anpheros Search](https://developers.anpheros.com/uk/guides/anpheros-search) знаходить речовину за назвою або брендом і надає її RxNorm ingredient code та EMA product numbers:

```bash
curl "https://platform.anpheros.com/v1/search?q=metformin&type=treatment" -H "Authorization: Bearer $KEY"
```

Поле `unit` — це одиниця, яку LOINC очікує для цього тесту. Використовуйте його, щоб перевірити, що ви отримали. Створіть зіставлення від власних назв кожного джерела до кодів один раз, для кожного джерела, і зберігайте його у своїй інтеграції. Не вгадуйте під час запису: коли назва неоднозначна, і ніщо у джерелі не вирішує її, залиште її незіставленою та запитайте джерело. [Як імпортувати лабораторні результати до запису FHIR](https://developers.anpheros.com/uk/guides/import-lab-results-fhir) показує, як зберігаються та повідомляються незіставлені лабораторні маркери.

## Крок 2: запис із кодами, одиницями вимірювання та діапазонами

```bash
curl -X POST "https://platform.anpheros.com/v1/patients/$PID/observations" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/json" -H "Idempotency-Key: lab-77-hba1c" -d '{
  "code": "4548-4", "category": "laboratory",
  "value": 6.4, "unit": "%", "effective_at": "2026-10-01T07:30:00Z",
  "reference_range": {"low": 4.0, "high": 5.6},
  "author_type": "import"
}'
```

```json
{"id": "3296315c-…", "code": "4548-4", "system": "http://loinc.org", "display": "Hemoglobin A1c/Hemoglobin.total in Blood",
 "category": "laboratory", "effective_at": "2026-10-01T07:30:00Z", "value": 6.4, "unit": "%",
 "reference_range": {"low": 4.0, "high": 5.6}, "status": "final", "fhir": "Observation/3296315c-…"}
```

Коли ви надсилаєте лише код, платформа заповнює стандартну назву LOINC, як у REST API, так і в FHIR API (`/fhir/R4`), тому кожна програма читає одне й те саме `display`. `display`, який ви надсилаєте самостійно, зберігається як є.

Зберігайте також оригінальне формулювання. Для лабораторного звіту `code.text` у FHIR Observation містить назву лабораторії ("Hemoglobina glicozilata (HbA1c)") поруч із кодуванням LOINC. Пацієнт все ще впізнає свій паперовий звіт, і нічого не втрачається, якщо зіставлення колись буде поставлено під сумнів.

## Крок 3: одиниці вимірювання

Використовуйте коди UCUM: `mg/dL`, `mmol/L`, `%`, `mm[Hg]`, `kg`, `cm`, `/min`, `Cel`. Два правила запобігають більшості помилок:

- **Не конвертуйте мовчки.** Якщо лабораторія повідомляє рівень глюкози в `mmol/L`, а ваш додаток відображає `mg/dL`, зберігайте те, що виміряла лабораторія, і конвертуйте під час відображення. Збережене значення залишається простежуваним до звіту.
- **Перевіряйте одиницю вимірювання проти коду.** Коди LOINC є специфічними: HbA1c в `%` — це `4548-4`, тоді як HbA1c в `mmol/mol` має інший код LOINC. Значення, одиниця вимірювання якого не відповідає очікуваній одиниці коду, є помилкою зіставлення, а не проблемою конвертації.

Anpheros не конвертує одиниці вимірювання для вас; він зберігає одиницю, яку ви надсилаєте.

## Крок 4: дати

Перетворіть дати до формату ISO 8601 перед записом, використовуючи відомий формат джерела. `01.10.2026` — це 1 жовтня в Румунії та багатьох європейських країнах, але `10/01/2026` — це 1 жовтня лише в Сполучених Штатах. API відхиляє все, що не є ISO, замість того, щоб вгадувати:

```json
{"error": {"type": "invalid", "message": "Input should be a valid datetime or date, invalid character in year (at effective_at)", "field": "effective_at"}}
```

Виняток становить лабораторний конектор: він приймає `DD.MM.YYYY` та `DD/MM/YYYY`, оскільки знає, що читає європейський звіт.

Для вимірювань, де важливий час доби (артеріальний тиск, глюкоза, дози ліків), надсилайте час із його часовим поясом. Показання о 23:30 в Бухаресті припадають на попередній день за UTC, і пацієнт очікує їх у день, коли вони були зроблені.

## Крок 5: відсутність дублікатів

Дублікати виникають через повторні спроби, надсилання одного й того ж звіту двічі та надходження одного й того ж значення двома шляхами.

- **Повторні спроби:** надсилайте `Idempotency-Key`, який ідентифікує значення у джерелі, наприклад, ідентифікатор звіту та тест. Повторне надсилання того ж запиту з тим самим ключем повертає першу відповідь і не зберігає нічого нового. SDK додають одиницю до кожного створення.
- **Один і той же звіт двічі:** лабораторний конектор створює стабільний ідентифікатор для кожного рядка зі звіту, коду, дати та значення, і пропускає рядки, які вже були імпортовані.
- **Два шляхи:** зберігайте власний ідентифікатор системи-джерела з `X-Anpheros-Origin-Id` (або в `identifier` у ресурсах FHIR) і шукайте його перед записом значень, які можуть повернутися іншим шляхом.

## Крок 6: перевірка за профілем

Для лабораторних результатів запитайте платформу, наскільки ресурс відповідає профілю HL7 Europe для лабораторних звітів, перш ніж покладатися на нього:

```bash
curl -X POST "https://platform.anpheros.com/fhir/R4/Observation/\$validate?profile=eu-lab" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: application/fhir+json" -d '{
  "resourceType": "Observation", "status": "final",
  "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "laboratory"}]}],
  "code": {"text": "HbA1c"}, "subject": {"reference": "Patient/'$PID'"},
  "valueQuantity": {"value": 6.4, "unit": "%"}
}'
```

Цей ненормалізований результат отримує точний список:

```json
{"resourceType": "OperationOutcome", "issue": [
  {"severity": "error", "code": "invalid", "diagnostics": "Observation.code must carry a LOINC coding.", "expression": ["Observation.code"]},
  {"severity": "error", "code": "required", "diagnostics": "Observation.effective[x] is required.", "expression": ["Observation.effective"]},
  {"severity": "warning", "code": "business-rule", "diagnostics": "valueQuantity should carry a UCUM system and code.", "expression": ["Observation.valueQuantity"]},
  {"severity": "warning", "code": "informational", "diagnostics": "No referenceRange: interpretation will need the laboratory's ranges.", "expression": ["Observation.referenceRange"]},
  {"severity": "information", "code": "informational", "diagnostics": "No performer (laboratory) recorded.", "expression": ["Observation.performer"]},
  {"severity": "information", "code": "informational", "diagnostics": "No issued time (when the laboratory released the result).", "expression": ["Observation.issued"]}]}
```

Кожна проблема відповідає одному з наведених вище кроків. Запустіть `$validate` у своїх інтеграційних тестах з реальними зразками з кожного джерела.

## Крок 7: збереження джерела

Нормалізація змінює спосіб запису значення, але ніколи не його походження. Надсилайте `author_type` (`device`, `import`, `practitioner`, `patient`) та `X-Anpheros-Source-System` з кожним записом. Це дозволяє лікарю, аудитору або моделі ШІ відрізнити лабораторний результат від значення, введеного вдома. Див. [Пояснення походження медичних даних](https://developers.anpheros.com/uk/guides/medical-data-provenance).

## Чеклист

- [ ] Кожне джерело має відображення своїх назв на LOINC / ATC / ICD-10, збережене у вашій інтеграції
- [ ] Неоднозначні назви залишаються невідображеними та повідомляються, ніколи не вгадуються
- [ ] Одиниці UCUM, що відповідають коду; без прихованого перетворення
- [ ] Дати у форматі ISO 8601, із часовими поясами, де час має значення
- [ ] Діапазони посилань зберігаються разом із лабораторними значеннями
- [ ] Оригінальне формулювання збережено (`code.text`)
- [ ] Ключі ідемпотентності або ідентифікатори джерела при кожному записі
- [ ] `author_type` та система джерела при кожному записі
- [ ] `$validate` у тестах для лабораторних результатів

## Часті запитання

### Що таке нормалізація медичних даних?
Перетворення медичних даних з різних джерел в одну стандартну форму: спільні коди (LOINC для тестів та вимірювань, ICD-10 для діагнозів, ATC для медикаментів), одиниці UCUM, дати ISO, референтні діапазони та записане джерело, щоб значення з різних систем можна було порівнювати, комбінувати та обмінювати.

### Чи слід перетворювати всі значення в одну одиницю?
Зберігайте одиницю, в якій вимірювало джерело, доки вона є дійсною одиницею UCUM, що відповідає коду, і перетворюйте під час відображення або аналізу. Це дозволяє відстежувати кожне збережене значення до його початкового звіту.

### Чи може нормалізація бути повністю автоматичною?
Здебільшого. Коди у джерелі, відомі назви та добре сформовані одиниці можуть бути відображені автоматично. Неоднозначні назви та невідомі локальні коди потребують одноразового рішення людини для кожного джерела, після чого відображення стає автоматичним.

## Пов'язане

- [Системи кодів FHIR](https://developers.anpheros.com/uk/guides/fhir-code-systems)
- [Як імпортувати лабораторні результати до запису FHIR](https://developers.anpheros.com/uk/guides/import-lab-results-fhir)
- [Пояснення походження медичних даних](https://developers.anpheros.com/uk/guides/medical-data-provenance)
- [Сумісність медичних даних](https://developers.anpheros.com/uk/guides/interoperability)
- [API медичних даних](https://developers.anpheros.com/uk/guides/medical-data-api)