Initial commit
This commit is contained in:
@@ -0,0 +1,398 @@
|
||||
# E01 Reproducibility Guide
|
||||
|
||||
## 1. Зачем нужна эта структура
|
||||
|
||||
Эксперимент разбит на:
|
||||
|
||||
- один общий блок `foundation`, который готовит данные, split, ROI и признаки;
|
||||
- пять отдельных блоков `H1-H5`, каждый из которых проверяет одну научную гипотезу;
|
||||
- один общий блок `all`, который запускает все последовательно.
|
||||
|
||||
Это сделано для того, чтобы человек мог:
|
||||
|
||||
- пересобрать весь эксперимент целиком;
|
||||
- отдельно запустить только одну гипотезу;
|
||||
- быстро понять, какие артефакты относятся к какой гипотезе.
|
||||
|
||||
Дополнительно все новые entrypoint-скрипты работают в resumable-режиме:
|
||||
|
||||
- если артефакты уже есть, они не пересчитываются без необходимости;
|
||||
- если чего-то не хватает, достраивается только отсутствующий этап;
|
||||
- в summary каждого блока фиксируется, что именно было пересчитано в текущем запуске.
|
||||
|
||||
## 2. Основные команды
|
||||
|
||||
Все команды ниже выполняются из корня клонированного репозитория E01:
|
||||
|
||||
```bash
|
||||
cd E01_textural_features_blast_pipeline
|
||||
```
|
||||
|
||||
Перед запуском нужно подготовить окружение и указать пути к данным.
|
||||
|
||||
### 2.1. Установка зависимостей
|
||||
|
||||
Проект не хранит `.venv` в репозитории. Код проверен на CPython 3.12. После клонирования создайте окружение и установите зависимости:
|
||||
|
||||
```bash
|
||||
python3.12 -m venv .venv
|
||||
./.venv/bin/python -m pip install --upgrade pip
|
||||
./.venv/bin/python -m pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### 2.2. Где должны лежать тяжелые данные
|
||||
|
||||
В репозиторий не включаются:
|
||||
|
||||
- исходный датасет `data`;
|
||||
- датасет масок `data_masks`;
|
||||
- все артефакты из `outputs/`.
|
||||
|
||||
Ожидается, что у вас уже есть две директории:
|
||||
|
||||
- `data_root` — каталог с исходными изображениями и label-файлами;
|
||||
- `masks_root` — каталог с масками объектов.
|
||||
|
||||
Проект не требует, чтобы эти каталоги лежали внутри репозитория. Они могут находиться в любом месте файловой системы.
|
||||
|
||||
### 2.3. Как указать пути к данным
|
||||
|
||||
Рекомендуемый способ:
|
||||
|
||||
1. Скопируйте [local_paths.template.json](../configs/datasets/local_paths.template.json) в `configs/datasets/local_paths.json`.
|
||||
2. Впишите абсолютные пути:
|
||||
|
||||
```json
|
||||
{
|
||||
"data_root": "/absolute/path/to/Data/data",
|
||||
"masks_root": "/absolute/path/to/Data/data_masks"
|
||||
}
|
||||
```
|
||||
|
||||
Этот файл специально не коммитится.
|
||||
|
||||
Альтернативы:
|
||||
|
||||
- переменные среды:
|
||||
|
||||
```bash
|
||||
export E01_DATA_ROOT="/absolute/path/to/Data/data"
|
||||
export E01_MASKS_ROOT="/absolute/path/to/Data/data_masks"
|
||||
```
|
||||
|
||||
- аргументы командной строки:
|
||||
|
||||
```bash
|
||||
./.venv/bin/python scripts/run_all_hypotheses.py --data-root /absolute/path/to/Data/data --masks-root /absolute/path/to/Data/data_masks
|
||||
```
|
||||
|
||||
- передача путей прямо через `make`:
|
||||
|
||||
```bash
|
||||
make all DATA_ROOT=/absolute/path/to/Data/data MASKS_ROOT=/absolute/path/to/Data/data_masks
|
||||
```
|
||||
|
||||
После этого можно использовать либо `make`, либо прямой вызов Python.
|
||||
|
||||
### Вариант A. Самый удобный: через `make`
|
||||
|
||||
```bash
|
||||
make foundation
|
||||
make h1
|
||||
make h2
|
||||
make h3
|
||||
make h4
|
||||
make h5
|
||||
make all
|
||||
make test
|
||||
make repro-check
|
||||
```
|
||||
|
||||
Если вы не хотите создавать `configs/datasets/local_paths.json`, можно сразу передать пути:
|
||||
|
||||
```bash
|
||||
make foundation DATA_ROOT=/absolute/path/to/Data/data MASKS_ROOT=/absolute/path/to/Data/data_masks
|
||||
make all DATA_ROOT=/absolute/path/to/Data/data MASKS_ROOT=/absolute/path/to/Data/data_masks
|
||||
```
|
||||
|
||||
### Вариант B. Прямой запуск Python
|
||||
|
||||
```bash
|
||||
./.venv/bin/python scripts/run_foundation.py
|
||||
./.venv/bin/python scripts/run_h1_interpretable_features.py
|
||||
./.venv/bin/python scripts/run_h2_mask_effect.py
|
||||
./.venv/bin/python scripts/run_h3_noise_regimes.py
|
||||
./.venv/bin/python scripts/run_h4_aggregation.py
|
||||
./.venv/bin/python scripts/run_h5_deep_vs_handcrafted.py
|
||||
./.venv/bin/python scripts/run_all_hypotheses.py
|
||||
./.venv/bin/python -m unittest discover -s tests -v
|
||||
```
|
||||
|
||||
Какие скрипты предназначены для прямого запуска человеком, а какие являются внутренними реализациями этапов, указано в [scripts/README.md](../scripts/README.md).
|
||||
|
||||
## 3. Что запускает каждый блок
|
||||
|
||||
### `foundation`
|
||||
|
||||
Файл:
|
||||
|
||||
- [run_foundation.py](../scripts/run_foundation.py)
|
||||
|
||||
Что делает:
|
||||
|
||||
- `A0`: аудит данных и индексы;
|
||||
- `A1`: подмножества корпуса;
|
||||
- `A2`: patient-level split;
|
||||
- `A4`: постановки бинарных задач;
|
||||
- `A3`: ROI по bbox и маскам;
|
||||
- `A5`: извлечение признаков.
|
||||
|
||||
Главный смысл:
|
||||
|
||||
- один раз подготовить все базовые артефакты для всех следующих гипотез.
|
||||
|
||||
Что ожидается на выходе:
|
||||
|
||||
- `outputs/dataset_index/` — индексы пациентов, изображений и объектов;
|
||||
- `outputs/splits/` — patient-level split;
|
||||
- `outputs/crops/` — bbox и mask ROI;
|
||||
- `outputs/features/` — таблицы признаков;
|
||||
- `outputs/reports/` — QC-отчеты этапов `A0-A5`.
|
||||
|
||||
Ключевой summary:
|
||||
|
||||
- [foundation_summary.md](../outputs/reports/hypotheses/foundation_summary.md)
|
||||
|
||||
### `h1`
|
||||
|
||||
Файл:
|
||||
|
||||
- [run_h1_interpretable_features.py](../scripts/run_h1_interpretable_features.py)
|
||||
|
||||
Что делает:
|
||||
|
||||
- `A6`: baseline-модели на признаках;
|
||||
- `A7`: устойчивость и интерпретация признаков.
|
||||
|
||||
Проверяемая гипотеза:
|
||||
|
||||
- интерпретируемые признаки действительно помогают отличать бласты.
|
||||
|
||||
Что ожидается на выходе:
|
||||
|
||||
- `outputs/tables/object_level_metrics_baselines.csv`;
|
||||
- `outputs/tables/baseline_model_leaderboard.csv`;
|
||||
- `outputs/predictions/object_level_baseline_predictions.parquet`;
|
||||
- `outputs/tables/top_features_stability.csv`;
|
||||
- `outputs/figures/pr_curves_baselines.png`;
|
||||
- `outputs/figures/roc_curves_baselines.png`;
|
||||
- `outputs/reports/feature_interpretation_notes.md`.
|
||||
|
||||
Summary:
|
||||
|
||||
- [h1_interpretable_features_summary.md](../outputs/reports/hypotheses/h1_interpretable_features_summary.md)
|
||||
|
||||
### `h2`
|
||||
|
||||
Файл:
|
||||
|
||||
- [run_h2_mask_effect.py](../scripts/run_h2_mask_effect.py)
|
||||
|
||||
Что делает:
|
||||
|
||||
- масочная часть `A8`.
|
||||
|
||||
Проверяемая гипотеза:
|
||||
|
||||
- маска клетки улучшает признаки и/или качество классификации.
|
||||
|
||||
Что ожидается на выходе:
|
||||
|
||||
- `outputs/tables/ablation_mask_usage.csv`.
|
||||
|
||||
Summary:
|
||||
|
||||
- [h2_mask_effect_summary.md](../outputs/reports/hypotheses/h2_mask_effect_summary.md)
|
||||
|
||||
### `h3`
|
||||
|
||||
Файл:
|
||||
|
||||
- [run_h3_noise_regimes.py](../scripts/run_h3_noise_regimes.py)
|
||||
|
||||
Что делает:
|
||||
|
||||
- режимы корпуса и шумовая часть `A8`.
|
||||
|
||||
Проверяемая гипотеза:
|
||||
|
||||
- шумовые классы и более реалистичный режим корпуса усложняют задачу.
|
||||
|
||||
Что ожидается на выходе:
|
||||
|
||||
- `outputs/tables/ablation_dataset_regimes.csv`;
|
||||
- `outputs/figures/ablation_summary.png` при совместном запуске с `H2` или через `all`.
|
||||
|
||||
Summary:
|
||||
|
||||
- [h3_noise_regimes_summary.md](../outputs/reports/hypotheses/h3_noise_regimes_summary.md)
|
||||
|
||||
### `h4`
|
||||
|
||||
Файл:
|
||||
|
||||
- [run_h4_aggregation.py](../scripts/run_h4_aggregation.py)
|
||||
|
||||
Что делает:
|
||||
|
||||
- `A10-A11`: image-level и patient-level агрегирование, итоговые фигуры и таблицы.
|
||||
|
||||
Проверяемая гипотеза:
|
||||
|
||||
- object-level score можно превратить в practically useful оценку изображения и пациента.
|
||||
|
||||
Что ожидается на выходе:
|
||||
|
||||
- `outputs/tables/image_level_metrics.csv`;
|
||||
- `outputs/tables/patient_level_ranking_metrics.csv`;
|
||||
- `outputs/predictions/image_level_scores.parquet`;
|
||||
- `outputs/predictions/patient_level_scores.parquet`;
|
||||
- `outputs/tables/figure_manifest.csv`;
|
||||
- `outputs/tables/table_manifest.csv`.
|
||||
|
||||
Summary:
|
||||
|
||||
- [h4_aggregation_summary.md](../outputs/reports/hypotheses/h4_aggregation_summary.md)
|
||||
|
||||
### `h5`
|
||||
|
||||
Файл:
|
||||
|
||||
- [run_h5_deep_vs_handcrafted.py](../scripts/run_h5_deep_vs_handcrafted.py)
|
||||
|
||||
Что делает:
|
||||
|
||||
- подготовка `modeling_workset`;
|
||||
- `A9`: ограниченные deep-baseline.
|
||||
|
||||
Проверяемая гипотеза:
|
||||
|
||||
- lightweight deep-модели можно честно сравнить с handcrafted baseline на тех же данных.
|
||||
|
||||
Что ожидается на выходе:
|
||||
|
||||
- `outputs/dataset_index/task_a43_full_realistic_modeling_workset.parquet`;
|
||||
- `outputs/crops/roi_manifest_modeling_workset.parquet`;
|
||||
- `outputs/tables/deep_vs_handcrafted.csv`;
|
||||
- `outputs/predictions/object_level_deep_predictions.parquet`;
|
||||
- `outputs/figures/deep_training_curves.png`;
|
||||
- `outputs/reports/a9_deep_qc.md`.
|
||||
|
||||
Summary:
|
||||
|
||||
- [h5_deep_vs_handcrafted_summary.md](../outputs/reports/hypotheses/h5_deep_vs_handcrafted_summary.md)
|
||||
|
||||
### `all`
|
||||
|
||||
Файл:
|
||||
|
||||
- [run_all_hypotheses.py](../scripts/run_all_hypotheses.py)
|
||||
|
||||
Что делает:
|
||||
|
||||
- последовательно запускает `foundation`, `H1`, `H2`, `H3`, `H4`, `H5`.
|
||||
|
||||
Summary:
|
||||
|
||||
- [run_all_hypotheses_summary.md](../outputs/reports/hypotheses/run_all_hypotheses_summary.md)
|
||||
|
||||
## 4. Порядок запуска по зависимостям
|
||||
|
||||
Если вы хотите выполнять эксперимент по частям, используйте такой порядок:
|
||||
|
||||
1. `foundation`
|
||||
2. `h1`
|
||||
3. `h2`
|
||||
4. `h3`
|
||||
5. `h4`
|
||||
6. `h5`
|
||||
|
||||
Почему именно так:
|
||||
|
||||
- `H1-H5` зависят от базовых артефактов `foundation`;
|
||||
- `H2`, `H3`, `H4`, `H5` используют результаты `H1`;
|
||||
- `H5` дополнительно строит `modeling_workset`.
|
||||
|
||||
Если нужна полная пересборка без ручного контроля, используйте:
|
||||
|
||||
```bash
|
||||
make all
|
||||
```
|
||||
|
||||
или
|
||||
|
||||
```bash
|
||||
./.venv/bin/python scripts/run_all_hypotheses.py
|
||||
```
|
||||
|
||||
Если артефакты уже собраны, эта команда отработает быстро и просто переиспользует проверенные результаты.
|
||||
|
||||
## 5. Где смотреть результаты
|
||||
|
||||
Основные директории:
|
||||
|
||||
- [outputs/reports/hypotheses](../outputs/reports/hypotheses) — короткие summary по каждому блоку;
|
||||
- [outputs/tables](../outputs/tables) — численные таблицы метрик;
|
||||
- [outputs/figures](../outputs/figures) — итоговые графики;
|
||||
- [outputs/predictions](../outputs/predictions) — предсказания моделей;
|
||||
- [outputs/checkpoints](../outputs/checkpoints) — сохраненные модели.
|
||||
|
||||
Практически это означает:
|
||||
|
||||
- если нужен “сырой” численный результат — смотрите `outputs/tables/`;
|
||||
- если нужны предсказания моделей — смотрите `outputs/predictions/`;
|
||||
- если нужны изображения и графики для статьи или диссертации — смотрите `outputs/figures/`;
|
||||
- если нужна проверка корректности этапов — смотрите `outputs/reports/` и `outputs/reports/hypotheses/`.
|
||||
|
||||
Подробный человекочитаемый отчет:
|
||||
|
||||
- [E01_detailed_report.md](../reports/E01_detailed_report.md)
|
||||
|
||||
## 6. Как проверять, что все прошло корректно
|
||||
|
||||
Минимальная проверка:
|
||||
|
||||
```bash
|
||||
make repro-check
|
||||
```
|
||||
|
||||
Что это означает:
|
||||
|
||||
- выполнен полный воспроизводимый запуск с пересчётом отсутствующих этапов;
|
||||
- после этого выполнены локальные тесты.
|
||||
|
||||
Проверенный сценарий публикационного репозитория:
|
||||
|
||||
1. Установить зависимости из `requirements.txt`.
|
||||
2. Создать `configs/datasets/local_paths.json`.
|
||||
3. Выполнить `make all`.
|
||||
4. Выполнить `make test`.
|
||||
5. Открыть `outputs/reports/hypotheses/run_all_hypotheses_summary.md`.
|
||||
|
||||
Также полезно открыть:
|
||||
|
||||
- [run_all_hypotheses_summary.md](../outputs/reports/hypotheses/run_all_hypotheses_summary.md)
|
||||
|
||||
## 7. Важное ограничение среды
|
||||
|
||||
`xgboost` не входит в обязательные зависимости. Соответствующие конфигурации
|
||||
автоматически используют `HistGradientBoostingClassifier` из scikit-learn.
|
||||
|
||||
Практическое следствие:
|
||||
|
||||
- конфигурации, которые в таблицах помечены как `xgboost`, фактически выполняются через `HistGradientBoosting` fallback.
|
||||
|
||||
Это ограничение уже отражено в:
|
||||
|
||||
- [a6_baseline_qc.md](../outputs/reports/a6_baseline_qc.md)
|
||||
- [a9_deep_qc.md](../outputs/reports/a9_deep_qc.md)
|
||||
Reference in New Issue
Block a user