E01_textural_features_blast_pipeline

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

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

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

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

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

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

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

Прогресс можно отслеживать в папке outputs/ — там будут появляться результаты прогона экспериента. Наблюдать за прогрессом можно из второго терминала:

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/):

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

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

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-скрипты:

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

README.md Unescape Escape