Initial commit
This commit is contained in:
@@ -0,0 +1,179 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user