IvanChurilov/E01_textural_features_blast_pipeline
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
IvanChurilov
2026-09-11 08:28:02 +03:00
commit 1f9b2f20bd
64 changed files with 12593 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/data_audit.md
+211
View File
@@ -0,0 +1,211 @@
# Аудит данных для 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. только после этого — расширение постановки на новые данные и более сложные модели.
docs/reproducibility_guide.md
+398
View File
@@ -0,0 +1,398 @@
# E01 Reproducibility Guide
## 1. Зачем нужна эта структура
Эксперимент разбит на:
- один общий блок `foundation`, который готовит данные, split, ROI и признаки;
- пять отдельных блоков `H1-H5`, каждый из которых проверяет одну научную гипотезу;
- один общий блок `all`, который запускает все последовательно.
Это сделано для того, чтобы человек мог:
- пересобрать весь эксперимент целиком;
- отдельно запустить только одну гипотезу;
- быстро понять, какие артефакты относятся к какой гипотезе.
Дополнительно все новые entrypoint-скрипты работают в resumable-режиме:
- если артефакты уже есть, они не пересчитываются без необходимости;
- если чего-то не хватает, достраивается только отсутствующий этап;
- в summary каждого блока фиксируется, что именно было пересчитано в текущем запуске.
## 2. Основные команды
Все команды ниже выполняются из корня клонированного репозитория E01:
```bash
cd E01_textural_features_blast_pipeline
```
Перед запуском нужно подготовить окружение и указать пути к данным.
### 2.1. Установка зависимостей
Проект не хранит `.venv` в репозитории. Код проверен на CPython 3.12. После клонирования создайте окружение и установите зависимости:
```bash
python3.12 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -r requirements.txt
```
### 2.2. Где должны лежать тяжелые данные
В репозиторий не включаются:
- исходный датасет `data`;
- датасет масок `data_masks`;
- все артефакты из `outputs/`.
Ожидается, что у вас уже есть две директории:
- `data_root` — каталог с исходными изображениями и label-файлами;
- `masks_root` — каталог с масками объектов.
Проект не требует, чтобы эти каталоги лежали внутри репозитория. Они могут находиться в любом месте файловой системы.
### 2.3. Как указать пути к данным
Рекомендуемый способ:
1. Скопируйте [local_paths.template.json](../configs/datasets/local_paths.template.json) в `configs/datasets/local_paths.json`.
2. Впишите абсолютные пути:
```json
{
"data_root": "/absolute/path/to/Data/data",
"masks_root": "/absolute/path/to/Data/data_masks"
}
```
Этот файл специально не коммитится.
Альтернативы:
- переменные среды:
```bash
export E01_DATA_ROOT="/absolute/path/to/Data/data"
export E01_MASKS_ROOT="/absolute/path/to/Data/data_masks"
```
- аргументы командной строки:
```bash
./.venv/bin/python scripts/run_all_hypotheses.py --data-root /absolute/path/to/Data/data --masks-root /absolute/path/to/Data/data_masks
```
- передача путей прямо через `make`:
```bash
make all DATA_ROOT=/absolute/path/to/Data/data MASKS_ROOT=/absolute/path/to/Data/data_masks
```
После этого можно использовать либо `make`, либо прямой вызов Python.
### Вариант A. Самый удобный: через `make`
```bash
make foundation
make h1
make h2
make h3
make h4
make h5
make all
make test
make repro-check
```
Если вы не хотите создавать `configs/datasets/local_paths.json`, можно сразу передать пути:
```bash
make foundation DATA_ROOT=/absolute/path/to/Data/data MASKS_ROOT=/absolute/path/to/Data/data_masks
make all DATA_ROOT=/absolute/path/to/Data/data MASKS_ROOT=/absolute/path/to/Data/data_masks
```
### Вариант B. Прямой запуск Python
```bash
./.venv/bin/python scripts/run_foundation.py
./.venv/bin/python scripts/run_h1_interpretable_features.py
./.venv/bin/python scripts/run_h2_mask_effect.py
./.venv/bin/python scripts/run_h3_noise_regimes.py
./.venv/bin/python scripts/run_h4_aggregation.py
./.venv/bin/python scripts/run_h5_deep_vs_handcrafted.py
./.venv/bin/python scripts/run_all_hypotheses.py
./.venv/bin/python -m unittest discover -s tests -v
```
Какие скрипты предназначены для прямого запуска человеком, а какие являются внутренними реализациями этапов, указано в [scripts/README.md](../scripts/README.md).
## 3. Что запускает каждый блок
### `foundation`
Файл:
- [run_foundation.py](../scripts/run_foundation.py)
Что делает:
- `A0`: аудит данных и индексы;
- `A1`: подмножества корпуса;
- `A2`: patient-level split;
- `A4`: постановки бинарных задач;
- `A3`: ROI по bbox и маскам;
- `A5`: извлечение признаков.
Главный смысл:
- один раз подготовить все базовые артефакты для всех следующих гипотез.
Что ожидается на выходе:
- `outputs/dataset_index/` — индексы пациентов, изображений и объектов;
- `outputs/splits/` — patient-level split;
- `outputs/crops/` — bbox и mask ROI;
- `outputs/features/` — таблицы признаков;
- `outputs/reports/` — QC-отчеты этапов `A0-A5`.
Ключевой summary:
- [foundation_summary.md](../outputs/reports/hypotheses/foundation_summary.md)
### `h1`
Файл:
- [run_h1_interpretable_features.py](../scripts/run_h1_interpretable_features.py)
Что делает:
- `A6`: baseline-модели на признаках;
- `A7`: устойчивость и интерпретация признаков.
Проверяемая гипотеза:
- интерпретируемые признаки действительно помогают отличать бласты.
Что ожидается на выходе:
- `outputs/tables/object_level_metrics_baselines.csv`;
- `outputs/tables/baseline_model_leaderboard.csv`;
- `outputs/predictions/object_level_baseline_predictions.parquet`;
- `outputs/tables/top_features_stability.csv`;
- `outputs/figures/pr_curves_baselines.png`;
- `outputs/figures/roc_curves_baselines.png`;
- `outputs/reports/feature_interpretation_notes.md`.
Summary:
- [h1_interpretable_features_summary.md](../outputs/reports/hypotheses/h1_interpretable_features_summary.md)
### `h2`
Файл:
- [run_h2_mask_effect.py](../scripts/run_h2_mask_effect.py)
Что делает:
- масочная часть `A8`.
Проверяемая гипотеза:
- маска клетки улучшает признаки и/или качество классификации.
Что ожидается на выходе:
- `outputs/tables/ablation_mask_usage.csv`.
Summary:
- [h2_mask_effect_summary.md](../outputs/reports/hypotheses/h2_mask_effect_summary.md)
### `h3`
Файл:
- [run_h3_noise_regimes.py](../scripts/run_h3_noise_regimes.py)
Что делает:
- режимы корпуса и шумовая часть `A8`.
Проверяемая гипотеза:
- шумовые классы и более реалистичный режим корпуса усложняют задачу.
Что ожидается на выходе:
- `outputs/tables/ablation_dataset_regimes.csv`;
- `outputs/figures/ablation_summary.png` при совместном запуске с `H2` или через `all`.
Summary:
- [h3_noise_regimes_summary.md](../outputs/reports/hypotheses/h3_noise_regimes_summary.md)
### `h4`
Файл:
- [run_h4_aggregation.py](../scripts/run_h4_aggregation.py)
Что делает:
- `A10-A11`: image-level и patient-level агрегирование, итоговые фигуры и таблицы.
Проверяемая гипотеза:
- object-level score можно превратить в practically useful оценку изображения и пациента.
Что ожидается на выходе:
- `outputs/tables/image_level_metrics.csv`;
- `outputs/tables/patient_level_ranking_metrics.csv`;
- `outputs/predictions/image_level_scores.parquet`;
- `outputs/predictions/patient_level_scores.parquet`;
- `outputs/tables/figure_manifest.csv`;
- `outputs/tables/table_manifest.csv`.
Summary:
- [h4_aggregation_summary.md](../outputs/reports/hypotheses/h4_aggregation_summary.md)
### `h5`
Файл:
- [run_h5_deep_vs_handcrafted.py](../scripts/run_h5_deep_vs_handcrafted.py)
Что делает:
- подготовка `modeling_workset`;
- `A9`: ограниченные deep-baseline.
Проверяемая гипотеза:
- lightweight deep-модели можно честно сравнить с handcrafted baseline на тех же данных.
Что ожидается на выходе:
- `outputs/dataset_index/task_a43_full_realistic_modeling_workset.parquet`;
- `outputs/crops/roi_manifest_modeling_workset.parquet`;
- `outputs/tables/deep_vs_handcrafted.csv`;
- `outputs/predictions/object_level_deep_predictions.parquet`;
- `outputs/figures/deep_training_curves.png`;
- `outputs/reports/a9_deep_qc.md`.
Summary:
- [h5_deep_vs_handcrafted_summary.md](../outputs/reports/hypotheses/h5_deep_vs_handcrafted_summary.md)
### `all`
Файл:
- [run_all_hypotheses.py](../scripts/run_all_hypotheses.py)
Что делает:
- последовательно запускает `foundation`, `H1`, `H2`, `H3`, `H4`, `H5`.
Summary:
- [run_all_hypotheses_summary.md](../outputs/reports/hypotheses/run_all_hypotheses_summary.md)
## 4. Порядок запуска по зависимостям
Если вы хотите выполнять эксперимент по частям, используйте такой порядок:
1. `foundation`
2. `h1`
3. `h2`
4. `h3`
5. `h4`
6. `h5`
Почему именно так:
- `H1-H5` зависят от базовых артефактов `foundation`;
- `H2`, `H3`, `H4`, `H5` используют результаты `H1`;
- `H5` дополнительно строит `modeling_workset`.
Если нужна полная пересборка без ручного контроля, используйте:
```bash
make all
```
или
```bash
./.venv/bin/python scripts/run_all_hypotheses.py
```
Если артефакты уже собраны, эта команда отработает быстро и просто переиспользует проверенные результаты.
## 5. Где смотреть результаты
Основные директории:
- [outputs/reports/hypotheses](../outputs/reports/hypotheses) — короткие summary по каждому блоку;
- [outputs/tables](../outputs/tables) — численные таблицы метрик;
- [outputs/figures](../outputs/figures) — итоговые графики;
- [outputs/predictions](../outputs/predictions) — предсказания моделей;
- [outputs/checkpoints](../outputs/checkpoints) — сохраненные модели.
Практически это означает:
- если нужен “сырой” численный результат — смотрите `outputs/tables/`;
- если нужны предсказания моделей — смотрите `outputs/predictions/`;
- если нужны изображения и графики для статьи или диссертации — смотрите `outputs/figures/`;
- если нужна проверка корректности этапов — смотрите `outputs/reports/` и `outputs/reports/hypotheses/`.
Подробный человекочитаемый отчет:
- [E01_detailed_report.md](../reports/E01_detailed_report.md)
## 6. Как проверять, что все прошло корректно
Минимальная проверка:
```bash
make repro-check
```
Что это означает:
- выполнен полный воспроизводимый запуск с пересчётом отсутствующих этапов;
- после этого выполнены локальные тесты.
Проверенный сценарий публикационного репозитория:
1. Установить зависимости из `requirements.txt`.
2. Создать `configs/datasets/local_paths.json`.
3. Выполнить `make all`.
4. Выполнить `make test`.
5. Открыть `outputs/reports/hypotheses/run_all_hypotheses_summary.md`.
Также полезно открыть:
- [run_all_hypotheses_summary.md](../outputs/reports/hypotheses/run_all_hypotheses_summary.md)
## 7. Важное ограничение среды
`xgboost` не входит в обязательные зависимости. Соответствующие конфигурации
автоматически используют `HistGradientBoostingClassifier` из scikit-learn.
Практическое следствие:
- конфигурации, которые в таблицах помечены как `xgboost`, фактически выполняются через `HistGradientBoosting` fallback.
Это ограничение уже отражено в:
- [a6_baseline_qc.md](../outputs/reports/a6_baseline_qc.md)
- [a9_deep_qc.md](../outputs/reports/a9_deep_qc.md)