E01_textural_features_blast_pipeline/README.md

# E01 Textural Features Blast Pipeline

## Постановка задачи

Проверить, насколько интерпретируемые морфометрические, цветовые и текстурные признаки действительно полезны для автоматизированного обнаружения бластных клеток на микроскопических изображениях препаратов крови, если оценка проводится на реальных данных с разметкой объектов, масками и разделением по пациентам.

## Предмет проекта

- объектно-уровневая постановка `blast / non-blast`;
- сравнение признаковых и более сложных моделей на одинаковых данных;
- оценка роли сегментационных масок при извлечении признаков;
- переход от классификации отдельного объекта к анализаторно-ориентированной оценке изображения;
- фиксация ограничений текущих данных и выделение задач, требующих нового корпуса.

## Текущий фокус

На первом этапе приоритет отдается только тем частям исследования, которые можно выполнить на локальных данных.

- object detection-разметка по пациентам;
- автоматически построенные маски объектов;
- patient-level разбиение;
- морфо-текстурные признаки на уровне отдельных клеток;
- image-level агрегирование как приближение к задаче автоматического анализатора.

Постановки, требующие явного разделения лимфобластов и миелобластов, внешней межлабораторной валидации и case-level клинических меток, вынесены во вторую часть плана.

## Навигация по проекту

- [docs/data_audit.md](docs/data_audit.md) — зафиксированный аудит структуры и качества доступных данных.
- [docs/reproducibility_guide.md](docs/reproducibility_guide.md) — подробная инструкция по воспроизводимому запуску `foundation`, `H1-H5` и полного прогона.

## Воспроизводимый запуск

Эксперимент организован в виде:

- одного базового блока `foundation`;
- отдельных блоков `H1-H5` по гипотезам;
- общего блока `all` для полного последовательного прогона.

Точки входа работают в resumable-режиме:

- если нужные артефакты уже существуют, они валидируются и переиспользуются;
- если какого-то этапа не хватает, пересчитывается только недостающая часть;
- итоговые короткие summary по каждому блоку сохраняются в [outputs/reports/hypotheses](outputs/reports/hypotheses).

## Установка и запуск

Код проверен на CPython 3.12. Для полного прогона требуется около 7 ГБ под
выходные артефакты; лучше иметь не менее 10 ГБ свободного места. Исходные
изображения и маски в репозиторий не входят.

Из корня проекта создайте окружение и установите зафиксированные зависимости.
Вариант с `uv`:

```bash
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python -r requirements.txt
```

То же самое через стандартный `venv` и `pip`:

```bash
python3.12 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install -r requirements.txt
```

Подготовьте два каталога:

- `data_root` — исходные изображения, object detection-разметка и
  `predefined_classes.txt`;
- `masks_root` — копия структуры набора с масками в
  `images_results/masks_sam`.

Скопируйте шаблон конфигурации и укажите абсолютные пути к этим каталогам:

```bash
cp configs/datasets/local_paths.template.json configs/datasets/local_paths.json
```

```json
{
  "data_root": "/absolute/path/to/data",
  "masks_root": "/absolute/path/to/data_masks"
}
```

После этого полный эксперимент и тесты запускаются так:

```bash
make all
make test
```

Команда `make repro-check` последовательно выполняет оба шага. На чистом
рабочем дереве `make all` строит `foundation`, затем H1–H5. При повторном
вызове готовые артефакты проверяются и переиспользуются. Для принудительного
пересчёта всех этапов используйте `make all FORCE=1`.

Конфигурационный файл не обязателен. Пути можно передать непосредственно:

```bash
make all DATA_ROOT=/absolute/path/to/data MASKS_ROOT=/absolute/path/to/data_masks
```

Или через переменные среды:

```bash
export E01_DATA_ROOT=/absolute/path/to/data
export E01_MASKS_ROOT=/absolute/path/to/data_masks
make all
```

Отдельные блоки запускаются командами:

```bash
make foundation
make h1
make h2
make h3
make h4
make h5
```

Основной результат полного запуска —
`outputs/reports/hypotheses/run_all_hypotheses_summary.md`. Численные таблицы
находятся в `outputs/tables`, предсказания — в `outputs/predictions`, графики —
в `outputs/figures`. Для сравнения нового прогона с опубликованным результатом
следует в первую очередь проверить размеры выборок и таблицы
`baseline_model_leaderboard.csv`, `ablation_mask_usage.csv`,
`ablation_dataset_regimes.csv`, `image_level_metrics.csv`,
`patient_level_ranking_metrics.csv` и `deep_vs_handcrafted.csv`.

Прямые entrypoint-скрипты:

- [run_foundation.py](scripts/run_foundation.py)
- [run_h1_interpretable_features.py](scripts/run_h1_interpretable_features.py)
- [run_h2_mask_effect.py](scripts/run_h2_mask_effect.py)
- [run_h3_noise_regimes.py](scripts/run_h3_noise_regimes.py)
- [run_h4_aggregation.py](scripts/run_h4_aggregation.py)
- [run_h5_deep_vs_handcrafted.py](scripts/run_h5_deep_vs_handcrafted.py)
- [run_all_hypotheses.py](scripts/run_all_hypotheses.py)

Какие скрипты считаются публичными точками входа, а какие внутренними служебными шагами, отдельно описано в [scripts/README.md](scripts/README.md).

## Каталоги проекта

- `configs/` — конфигурации запуска; локальные пути к данным задаются через `configs/datasets/local_paths.json` и не коммитятся.
- `data_access/` — пояснения по доступу к данным без хранения самих данных в репозитории.
- `docs/` — аналитические материалы и аудит данных.
- `notebooks/` — исследовательские ноутбуки.
- `outputs/dataset_index/` — манифесты пациентов, изображений и объектов.
- `outputs/splits/` — зафиксированные patient-level разбиения.
- `outputs/crops/` — извлеченные объектные кропы.
- `outputs/features/` — таблицы признаков.
- `outputs/checkpoints/` — обученные модели.
- `outputs/predictions/` — предсказания на object-level и image-level.
- `outputs/figures/` и `outputs/tables/` — артефакты для статьи и диссертации.
- `outputs/reports/` и `reports/` — промежуточные отчеты и итоговые summary-файлы.
- `src/` — основной код проекта.
- `tests/` — проверки корректности пайплайна.

## Что не попадает в GitHub

В [\.gitignore](.gitignore) вынесены:

- все содержимое `outputs/`;
- локальное окружение `.venv/` и кэш `.uv-cache/`;
- локальный файл путей `configs/datasets/local_paths.json`;
- служебные и бинарные директории вроде `vendor/`;
- генерируемые экспортные версии отчетов `reports/*.pdf`, `reports/*.docx`, `reports/*.html`.

## Ключевые рабочие решения

- Основная постановка для текущих данных: `blast vs non-blast`, а не `lymphoblast vs myeloblast`.
- Главная единица недопущения утечки: пациент.
- В базовый patient-level протокол входят только `122` каталогов с patient id; специальный каталог `part-1` пока рассматривается отдельно до уточнения его происхождения.
- Основной сопоставитель объектов: порядок строк в `images_labels/*.txt` и индекс `obj_XXXX` в имени маски.
- Первичная научная ценность текущего корпуса: воспроизводимая проверка полезности текстурных признаков, влияния масок и реалистичных условий data quality.