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/reproducibility_guide.md — подробная инструкция по воспроизводимому запуску foundation, H1-H5 и полного прогона.

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

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

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

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

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

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

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

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

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

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

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.

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

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

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

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

make all
make test

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

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

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

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

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

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

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
• run_h1_interpretable_features.py
• run_h2_mask_effect.py
• run_h3_noise_regimes.py
• run_h4_aggregation.py
• run_h5_deep_vs_handcrafted.py
• run_all_hypotheses.py

Какие скрипты считаются публичными точками входа, а какие внутренними служебными шагами, отдельно описано в 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 вынесены:

• все содержимое 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.