# Аудит данных для E01

Документ фиксирует фактическое состояние данных, доступных на 9 апреля 2026 года, и определяет, какие постановки уже можно реализовывать программно без привлечения новых наборов данных.

## 1. Источники данных

- `data` — исходные изображения и object detection-разметка.
- `data_masks` — те же данные с дополнительными масками объектов в `images_results/masks_sam`.

## 2. Структура одного пациентского каталога

Для большинства пациентов в `data` используется одинаковая структура:

- `images/` — исходные изображения;
- `images_labels/` — текстовые файлы разметки объектов;
- `predefined_classes.txt` — словарь классов.

В `data_masks` для тех же пациентов дополнительно присутствует каталог:

- `images_results/masks_sam/` — маски отдельных объектов в формате `stem_class_<class_id>_obj_<index>.png`.

Отдельно нужно зафиксировать специальный случай:

- в корне обоих наборов присутствует каталог `part-1`, который не соответствует формату пациентского идентификатора;
- в нем находится `33` изображения, `33` label-файла и `477` размеченных объектов;
- в `data_masks` для него есть `475` масок;
- до уточнения происхождения этого каталога его не следует включать в основной patient-level протокол.

## 3. Проверенные количественные характеристики

### 3.1. Общий объем

Для воспроизводимости нужно различать:

- полный сырой объем каталога;
- основной patient-level корпус, который используется в эксперименте.

Полный сырой объем:

- число каталогов верхнего уровня в `data`: `123`;
- число каталогов верхнего уровня в `data_masks`: `123`;
- среди них `122` пациент-идентифицированных каталогов и один специальный каталог `part-1`;
- число изображений: `12 521`;
- число файлов разметки: `12 489`;
- число объектов по detection-разметке: `86 873`.

Основной patient-level корпус, рекомендуемый для первой фазы эксперимента:

- число пациентских каталогов: `122`;
- число изображений: `12 488`;
- число файлов разметки: `12 456`;
- число объектов по detection-разметке: `86 396`.

### 3.2. Наблюдения по разметке

- пустых файлов разметки: `26`;
- изображений без `.txt`-разметки: `32`;
- такие изображения встречаются только у пациентов `P190315.002` и `P190408.001`;
- файлов разметки без соответствующего изображения не обнаружено;
- в `4 991` строках файлов разметки идентификатор класса записан в формате с плавающей точкой, например `7.0`; при загрузке нужно использовать нормализацию `int(float(class_id))`.

### 3.3. Наблюдения по маскам

- всего масок объектов в основном patient-level корпусе: `86 360`;
- изображений, для которых есть хотя бы одна маска: `12 428`;
- изображений без масок: `60`;
- пациентов, у которых есть изображения без масок: `15`.

Из этих `60` изображений:

- `32` совпадают с изображениями без detection-разметки;
- остальные `28` изображений имеют разметку, но не имеют полного покрытия масками.

### 3.4. Проверка соответствия labels и masks

Для изображений, у которых число строк в `images_labels/*.txt` совпадает с числом файлов `*_obj_XXXX.png`, было проверено соответствие классов и порядка объектов.

Результат:

- проверено изображений: `12 395`;
- изображений с полным совпадением порядка объектов: `12 395`;
- изображений с нарушением последовательности `obj_0000, obj_0001, ...`: `0`;
- изображений с несовпадением классов между строкой label-файла и именем маски: `0`.

Это позволяет принять следующий контракт данных: индекс `obj_XXXX` соответствует порядку строки в detection-разметке.

## 4. Словарь классов

Основной словарь классов совпадает у `122` пациентов:

| id | Класс |
|---:|---|
| 0 | Lymphocyte |
| 1 | Metamyelocyte |
| 2 | Monocyte |
| 3 | Myelocyte |
| 4 | Normoblasts |
| 5 | Rod neutrophil |
| 6 | Segmentonuclear neutrophil |
| 7 | blast |
| 8 | Promyelocyte |
| 9 | Eosinophil |
| 10 | Basophil |
| 11 | Magakariocyte |
| 12 | Bad cells |
| 13 | plasma cells |
| 14 | artifacts |
| 15 | gumpricht shadows |
| 16 | methoses |
| 17 | normoblasts: oxyfilny |
| 18 | macrophages |
| 19 | normoblasts: erythroblasts |
| 20 | normoblasts: basophilic |
| 21 | normoblasts: polychromatophilic |

У пациента `240612.007` в `predefined_classes.txt` есть дополнительный класс `22 mast cells`, однако фактических объектов этого класса в текущем корпусе не обнаружено.

## 5. Распределение объектов по классам

Наиболее представленные классы:

| id | Класс | Число объектов |
|---:|---|---:|
| 7 | blast | 61 861 |
| 12 | Bad cells | 7 825 |
| 0 | Lymphocyte | 5 660 |
| 15 | gumpricht shadows | 3 600 |
| 6 | Segmentonuclear neutrophil | 1 715 |
| 3 | Myelocyte | 1 052 |
| 2 | Monocyte | 1 038 |
| 17 | normoblasts: oxyfilny | 1 035 |
| 5 | Rod neutrophil | 545 |
| 21 | normoblasts: polychromatophilic | 416 |
| 1 | Metamyelocyte | 414 |
| 9 | Eosinophil | 333 |

Редкие классы присутствуют, но для самостоятельной устойчивой оценки их объема недостаточно:

- `Promyelocyte`: `5`;
- `Magakariocyte`: `7`;
- `macrophages`: `7`;
- `plasma cells`: `24`;
- `Basophil`: `28`;
- `artifacts`: `54`.

## 6. Распределение по пациентам и изображениям

- пациентов, у которых встречается хотя бы один `blast`: `100`;
- пациентов без `blast`: `22`;
- изображений с хотя бы одним `blast`: `8 618`;
- изображений только с `blast`: `3 508`;
- изображений со смешанным составом `blast + other`: `5 110`;
- изображений без `blast`: `3 812`.

Это означает, что текущий набор подходит не только для object-level классификации, но и для image-level агрегирования, когда нужно оценивать вероятность наличия бластов на изображении по совокупности обнаруженных объектов.

## 7. Недопокрытие масками

Найдено `35` изображений, у которых число строк в detection-разметке не совпадает с числом масок объектов. Всего недостающих масок объектов: `36`.

Недостающие маски по классам:

| id | Класс | Число недостающих масок |
|---:|---|---:|
| 7 | blast | 13 |
| 15 | gumpricht shadows | 9 |
| 12 | Bad cells | 5 |
| 2 | Monocyte | 3 |
| 6 | Segmentonuclear neutrophil | 2 |
| 0 | Lymphocyte | 1 |
| 20 | normoblasts: basophilic | 1 |
| 5 | Rod neutrophil | 1 |
| 3 | Myelocyte | 1 |

Практический вывод: маски покрывают практически весь корпус, поэтому mask-based признаки можно считать основной, а не вспомогательной веткой текущего эксперимента. При этом для воспроизводимости необходимо зафиксировать правило fallback: если маски для объекта нет, данный объект либо исключается из mask-only ветки, либо используется только в bbox-only ветке.

## 8. Что текущие данные позволяют исследовать

Текущий корпус уже позволяет:

- строить основной протокол на `122` пациент-идентифицированных каталогах;
- строить patient-level разбиения;
- извлекать object-level кропы по detection-разметке;
- использовать mask-restricted ROI для признаков;
- сравнивать `bbox-only` и `mask-based` признаки;
- решать бинарную задачу `blast / non-blast`;
- оценивать image-level наличие бластов через агрегирование объектных предсказаний;
- изучать влияние классов качества, артефактов и сложных отрицательных примеров.

## 9. Что текущие данные не позволяют доказательно исследовать

На текущем корпусе нельзя считать полноценно подтвержденными следующие постановки:

- включение каталога `part-1` в основной patient-level корпус без дополнительного уточнения его происхождения;
- различение `lymphoblast / myeloblast`, так как в разметке есть только общий класс `blast`;
- внешнюю межлабораторную валидацию и устойчивость к доменному сдвигу;
- case-level и slide-level клиническую постановку с подтвержденными диагнозами;
- сопоставление результатов модели с экспертной разметкой нуклеол, палочек Ауэра и других специализированных структур.

## 10. Прямое следствие для плана эксперимента

Первый этап эксперимента должен быть построен вокруг следующей последовательности:

1. аудит и нормализация данных;
2. выделение основного patient-level корпуса и исключение `part-1` из базового протокола до уточнения его статуса;
3. формирование индексных таблиц на уровне пациента, изображения и объекта;
4. извлечение кропов и mask-aware областей интереса;
5. object-level `blast / non-blast` baseline;
6. сравнение признаков по режимам `bbox`, `mask`, `bbox+mask`;
7. image-level агрегирование как приближение к задаче автоматического анализатора;
8. только после этого — расширение постановки на новые данные и более сложные модели.