E01_textural_features_blast_pipeline/README.md

<!-- # E01 Textural Features Blast Pipeline -->

<p align="center">
  <h2>E01 Textural Features Blast Pipeline</h2>
  <img src="docs/F0000002.jpg" alt="Banner" width="75%">
</p>

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

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

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

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


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

- [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` (использовался оригинальный рабор https://cloud.mail.ru/public/rb2S/BEfYpp1bq);
- `masks_root` — копия структуры набора с масками в
  `images_results/masks_sam` (использовался оригинальный набор https://cloud.mail.ru/public/2Tb7/8kMa411XX, это тот же набор, что и первый, только дополненный масками).

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

```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
```

Прогресс можно отслеживать в папке outputs/ — там будут появляться результаты прогона экспериента.
Наблюдать за прогрессом можно из второго терминала:
```bash
find outputs/crops/mask -type f | wc -l
find outputs/crops/mask_tight -type f | wc -l
du -sh outputs
```
Ожидаемые конечные количества: 86 250 mask-кропов и 86 166 tight-mask-кропов.

Для непрерывного контроля можно повторять проверку каждые 10 секунд (происходит подсчёт кол-ва файлов в директории outputs/ и подвсёт объёма директории outputs/):
```bash
while true; do
  clear
  date
  PID=$(pgrep -f '[r]un_all_hypotheses.py' | head -1)

  if [[ -n "$PID" ]]; then
    ps -p "$PID" -o pid,etime,%cpu,%mem,state,command
  else
    echo "Процесс run_all_hypotheses.py не найден"
  fi

  du -sh outputs
  find outputs -type f | wc -l
  find outputs -type f -mmin -2 | tail -10
  sleep 10
done
```

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

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

### Результаты запуска
Результаты запуска дополнительно положил в папку на [диске](https://disk.yandex.ru/d/AQoRU5WQVMBtxQ), чтобы можно было свериться.

Основной результат полного запуска —
`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;
- Основной сопоставитель объектов: порядок строк в `images_labels/*.txt` и индекс `obj_XXXX` в имени маски.
- Научная ценность текущего экспериента: воспроизводимая проверка полезности текстурных признаков, влияния масок и реалистичных условий data quality.