обновил документы

README.md

@@ -1,4 +1,9 @@
-# E01 Textural Features Blast Pipeline
+<!-- # 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>
 
 ## Постановка задачи
 
@@ -57,9 +62,9 @@ python3.12 -m venv .venv
 Подготовьте два каталога:
 
 - `data_root` — исходные изображения, object detection-разметка и
-  `predefined_classes.txt`;
+  `predefined_classes.txt` (использовался оригинальный рабор https://cloud.mail.ru/public/rb2S/BEfYpp1bq);
 - `masks_root` — копия структуры набора с масками в
-  `images_results/masks_sam`.
+  `images_results/masks_sam` (использовался оригинальный набор https://cloud.mail.ru/public/2Tb7/8kMa411XX, это тот же набор, что и первый, только дополненный масками).
 
 Скопируйте шаблон конфигурации и укажите абсолютные пути к этим каталогам:
 
@@ -100,6 +105,35 @@ 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
@@ -111,6 +145,9 @@ make h4
 make h5
 ```
 
+### Результаты запуска
+Результаты запуска дополнительно положил в папку на [диске](https://disk.yandex.ru/d/AQoRU5WQVMBtxQ), чтобы можно было свериться.
+
 Основной результат полного запуска —
 `outputs/reports/hypotheses/run_all_hypotheses_summary.md`. Численные таблицы
 находятся в `outputs/tables`, предсказания — в `outputs/predictions`, графики —

data_access/README.md

@@ -1,22 +0,0 @@
-# Data Access
-
-Heavyweight datasets are not stored in this repository.
-
-To run the experiment:
-
-1. Prepare the original dataset directory `data`.
-2. Prepare the masks dataset directory `data_masks`.
-3. Copy `configs/datasets/local_paths.template.json` to `configs/datasets/local_paths.json`.
-4. Put absolute paths to these two directories into `local_paths.json`.
-
-After that, run:
-
-```bash
-make all
-```
-
-or:
-
-```bash
-./.venv/bin/python scripts/run_all_hypotheses.py
-```

docs/data_audit.md

@@ -1,6 +1,6 @@
 # Аудит данных для E01
 
-Документ фиксирует фактическое состояние данных, доступных на 9 апреля 2026 года, и определяет, какие постановки уже можно реализовывать программно без привлечения новых наборов данных.
+Документ фиксирует фактическое состояние доступных для экспериемнта данных.
 
 ## 1. Источники данных
 

docs/reproducibility_guide.md

@@ -8,7 +8,7 @@
 - пять отдельных блоков `H1-H5`, каждый из которых проверяет одну научную гипотезу;
 - один общий блок `all`, который запускает все последовательно.
 
-Это сделано для того, чтобы человек мог:
+Это сделано для того, чтобы:
 
 - пересобрать весь эксперимент целиком;
 - отдельно запустить только одну гипотезу;
@@ -128,7 +128,7 @@ make all DATA_ROOT=/absolute/path/to/Data/data MASKS_ROOT=/absolute/path/to/Data
 ./.venv/bin/python -m unittest discover -s tests -v
 ```
 
-Какие скрипты предназначены для прямого запуска человеком, а какие являются внутренними реализациями этапов, указано в [scripts/README.md](../scripts/README.md).
+Какие скрипты предназначены для прямого запуска , а какие являются внутренними реализациями этапов, указано в [scripts/README.md](../scripts/README.md).
 
 ## 3. Что запускает каждый блок
 
@@ -354,7 +354,7 @@ make all
 - если нужны изображения и графики для статьи или диссертации — смотрите `outputs/figures/`;
 - если нужна проверка корректности этапов — смотрите `outputs/reports/` и `outputs/reports/hypotheses/`.
 
-Подробный человекочитаемый отчет:
+Подробный  отчет:
 
 - [E01_detailed_report.md](../reports/E01_detailed_report.md)
 

plan/current/experiment_plan_detailed.md

@@ -787,16 +787,4 @@
 5. Обучить Logistic Regression и Random Forest на `clean_cell_set`.
 6. Построить первые object-level и image-level метрики.
 
-Именно после этого спринта в проекте уже появится рабочая база, на которую можно последовательно наращивать остальной код.
 
-## 10. Что этот эксперимент даст для статьи и диссертации
-
-Если этап A будет выполнен качественно, то он уже сам по себе даст:
-
-- воспроизводимую оценку роли текстурных признаков;
-- сравнение признаковых режимов `bbox`, `mask`, `bbox+mask`;
-- практический аргумент в пользу patient-level протокола;
-- прикладную картину влияния шумовых классов и качества разметки;
-- bridge-результат между object-level классификацией и задачей автоматического анализатора.
-
-Именно это и должно стать центральным результатом первого экспериментального цикла.

plan/source_article_plan/README.md

@@ -1,15 +0,0 @@
-# Source Article Plan
-
-Этот каталог содержит архивную копию исходного плана экспериментов, вынесенного из обзорной статьи о текстурных признаках.
-
-Основной файл:
-
-- [experiment_plan.md](../../plan/source_article_plan/experiment_plan.md)
-
-Назначение каталога:
-
-- сохранить исходную формулировку экспериментов, непосредственно следующую из обзорной статьи;
-- использовать ее как traceability-слой при переходе к более прикладному и дата-ориентированному плану;
-- не редактировать этот файл как основной рабочий документ.
-
-Актуальный переработанный рабочий план находится в [plan/current/experiment_plan_detailed.md](../../plan/current/experiment_plan_detailed.md).

plan/source_article_plan/experiment_plan.md

@@ -1,378 +0,0 @@
-# План экспериментов по теме резидуальных лимфо- и миелобластов
-
-## 1. Назначение документа
-
-Этот документ является вынесенным из основной обзорной статьи планом экспериментов. Его задача — перевести выводы обзора литературы в конкретные, проверяемые и пригодные к реализации экспериментальные шаги. Основная статья отвечает на вопрос, что известно из литературы. Этот файл отвечает на вопрос, что именно следует проверять дальше в рамках диссертационной работы.
-
-## 2. Логика перехода от обзора к экспериментам
-
-Из обзора вытекают четыре устойчивых наблюдения.
-
-1. Классические текстурные признаки по-прежнему полезны, если данных мало, если нужна интерпретируемость и если требуется понять, какие именно свойства клетки дают вклад в решение.
-2. Нейросетевые модели обычно дают более высокий потолок качества, но сильнее зависят от объема и однородности данных.
-3. Интерпретируемость нейросетей сама по себе является отдельной исследовательской задачей, потому что в медицине важно не только качество, но и понимание class-specific признаков лимфобластов и миелобластов.
-4. Большинство работ заканчивается на уровне одиночной клетки, тогда как для автоматического анализатора нужно решать задачу на уровне всего препарата.
-
-Поэтому план экспериментов разделен на четыре направления:
-
-1. интерпретируемый morpho-texture baseline;
-2. гибридная модель для ограниченного объема данных и доменного сдвига;
-3. интерпретируемые нейросетевые и transformer-подобные модели для поиска новых признаков;
-4. анализаторно-ориентированная slide-level схема поиска и подтверждения бластов.
-
-## 3. Эксперимент 1. Интерпретируемый morpho-texture baseline
-
-### 3.1. Исследовательский пробел
-
-Во многих работах текстурные признаки показывают хорошие результаты, но сравнение с современными нейросетями часто проводится на разных наборах данных или в разных условиях валидации. Из-за этого трудно понять, насколько классические признаки действительно сильны сами по себе.
-
-### 3.2. Гипотеза
-
-Компактный набор морфологических, цветовых и текстурных признаков способен обеспечить конкурентоспособное и интерпретируемое различение классов `бласт / не бласт` на изображениях препаратов крови в монослое, если оценка ведется честно: с patient-level разделением и на одинаковых данных для всех baseline-моделей.
-
-Дополнительная частная гипотеза состоит в том, что разные подсемейства признаков будут по-разному работать для лимфобластов и миелобластов: для лимфобластов больший вклад внесут признаки ядерно-цитоплазматического отношения и внутрядерной однородности, а для миелобластов --- признаки нуклеол, цитоплазматической неоднородности и локальной гранулярности.
-
-### 3.3. Данные
-
-- Основной целевой корпус: изображения клеток из препаратов крови в монослое после экспертной разметки.
-- Вспомогательные публичные данные: совместимые single-cell blood-smear datasets для предварительной отладки пайплайна и выбора признаков.
-- Желательно заранее выделить три подмножества:
-  - лимфобласты;
-  - миелобласты;
-  - небластные клетки и морфологически близкие distractor-классы.
-
-### 3.4. Независимые переменные
-
-- Набор зон анализа:
-  - вся клетка;
-  - только ядро;
-  - ядро и цитоплазма по отдельности;
-  - клетка с явным выделением контура.
-- Семейство признаков:
-  - морфометрические;
-  - цветовые;
-  - текстурные;
-  - объединенные морфо-цвето-текстурные.
-- Тип текстурных дескрипторов:
-  - GLCM и признаки Харалика;
-  - LBP;
-  - фрактальные признаки;
-  - признаки Фурье;
-  - вейвлет-признаки.
-- Тип классификатора:
-  - SVM;
-  - Random Forest;
-  - XGBoost;
-  - небольшой многослойный персептрон.
-
-### 3.5. Зависимые переменные
-
-- accuracy;
-- balanced accuracy;
-- sensitivity отдельно для лимфобластов и миелобластов;
-- specificity;
-- macro-F1;
-- PR-AUC для редких blast-классов;
-- calibration error;
-- стабильность ranking признаков между повторными разбиениями;
-- согласие между top-признаками модели и экспертной морфологической интерпретацией.
-
-### 3.6. Baseline-источники
-
-- `putzu2014leucocyte`
-- `rawat2017classification`
-- `dincic2021morphological`
-- `tarquino2023inmop`
-- `dasariraju2020detection`
-
-### 3.7. Протокол
-
-1. Построить единый конвейер сегментации клетки, ядра и, если возможно, цитоплазмы.
-2. Извлечь полный набор признаков и затем провести два режима оценки:
-   - без отбора признаков;
-   - с отбором признаков по устойчивым критериям.
-3. Использовать patient-level split, чтобы клетки одного пациента не попадали одновременно в train и test.
-4. Выполнить повторяемую перекрестную проверку на обучающей части.
-5. Один раз финально оценить модель на отложенном тесте.
-6. Для лучших моделей отдельно построить профиль признаков для лимфобластов и миелобластов и проверить, насколько эти профили воспроизводятся у разных пациентов.
-
-### 3.8. Важные абляции
-
-- убрать по одному семейству признаков;
-- сравнить whole-cell и nucleus-only режимы;
-- сравнить цветные и нормализованные по окраске изображения;
-- сравнить исходные признаки и признаки после уменьшения размерности.
-
-### 3.9. Риски
-
-- ошибка сегментации может замаскировать реальную полезность текстурных признаков;
-- число бластов может оказаться слишком малым для устойчивой оценки подтипов;
-- часть пограничных незрелых клеток может иметь неоднозначную разметку.
-
-## 4. Эксперимент 2. Гибридная модель для малого объема данных и доменного сдвига
-
-### 4.1. Исследовательский пробел
-
-Современные нейросети часто показывают лучшие результаты на крупных стандартизованных наборах данных, но литература редко проверяет, помогают ли текстурные признаки удерживать качество при переносе между разными источниками изображений.
-
-### 4.2. Гипотеза
-
-Гибридная модель, объединяющая нейросетевые embeddings и отобранные текстурные признаки, будет устойчивее, чем чисто нейросетевая и чисто классическая модели, в условиях малого объема данных и межлабораторного доменного сдвига.
-
-### 4.3. Данные
-
-- Публичный blood-smear dataset для предобучения или первичного fine-tuning.
-- Внутренний диссертационный набор монослойных препаратов для внешней проверки переноса.
-- При возможности: второй внешний набор из другой лаборатории или другого сканера.
-
-### 4.4. Независимые переменные
-
-- Тип представления:
-  - handcrafted only;
-  - deep only;
-  - hybrid.
-- Тип backbone:
-  - ResNet-подобная сеть;
-  - более легкая CNN;
-  - Vision Transformer или Swin-подобная модель;
-  - замороженный feature extractor против частичного fine-tuning.
-- Способ объединения признаков:
-  - простая конкатенация;
-  - отбор признаков после конкатенации;
-  - отдельные классификаторы с последующим late fusion.
-- Наличие и тип нормализации окраски.
-
-### 4.5. Зависимые переменные
-
-- balanced accuracy на внутреннем и внешнем тесте;
-- macro-F1;
-- sensitivity для blast-классов;
-- expected calibration error;
-- устойчивость к смене домена;
-- стабильность ranking наиболее важных признаков;
-- согласие между объяснениями deep/hybrid-модели и экспертно выделенными областями ядра, нуклеол и цитоплазмы.
-
-### 4.6. Baseline-источники
-
-- `acevedo2019recognition`
-- `matek2019human`
-- `schouten2021tens`
-- `hegde2019comparison`
-- `sulaiman2023resrandsvm`
-- `attallah2024wavelet`
-- `park2024blastdiff`
-- `katar2023xvit`
-- `uzen2024swinconvmixer`
-
-### 4.7. Протокол
-
-1. Обучить базовую CNN на публичных данных.
-2. Сформировать нейросетевые embeddings для каждой клетки.
-3. Параллельно вычислить handcrafted-признаки для тех же клеток.
-4. Построить три варианта классификации:
-   - только handcrafted;
-   - только embeddings;
-   - гибрид.
-5. Проверить модели в трех режимах:
-   - обычный hold-out внутри одного домена;
-   - cross-dataset evaluation;
-   - low-shot adaptation на малом числе целевых примеров.
-6. Для лучших deep и hybrid моделей дополнительно сохранить карты внимания или значимости, чтобы затем оценить их морфологическую правдоподобность.
-
-### 4.8. Абляции
-
-- с текстурными признаками и без них;
-- с цветовой нормализацией и без нее;
-- с ядром и без ядра как отдельной зоны анализа;
-- разное число отобранных признаков;
-- полное и частичное размораживание нейросети;
-- CNN против transformer-backbone при одинаковом объеме данных.
-
-### 4.9. Риски
-
-- гибридная модель может переобучаться быстрее, чем чистая CNN;
-- при неаккуратном feature selection возможно скрытое подтекание информации из test;
-- монослойные препараты могут отличаться от публичных наборов сильнее, чем ожидается;
-- трансформер может проигрывать CNN в low-data режиме даже при более сложной архитектуре.
-
-## 5. Эксперимент 3. Интерпретируемые нейросетевые и transformer-подобные модели для поиска новых признаков
-
-### 5.1. Исследовательский пробел
-
-В литературе уже есть сильные deep-модели, но пока недостаточно ясно, какие именно морфологические признаки они используют при различении лимфобластов, миелобластов и небластных клеток. В результате нейросеть часто остается высокоточной, но слабо объяснимой, а ее потенциальная способность открывать новые class-specific признаки почти не используется систематически.
-
-### 5.2. Гипотеза
-
-Если сравнивать CNN, transformer-подобные модели и интерпретируемое MIL на одинаковых данных и с одинаковыми разбиениями, то можно получить не только конкурентоспособное качество, но и воспроизводимые объяснения, отражающие морфологически осмысленные различия между лимфобластами и миелобластами.
-
-### 5.3. Данные
-
-- Размеченные single-cell изображения с отдельными метками `лимфобласт`, `миелобласт`, `небласт`.
-- При наличии: case-level или slide-level набор с более грубыми метками для MIL.
-- Экспертные контуры или хотя бы точечные пометки для областей интереса:
-  - ядро;
-  - нуклеолы;
-  - гранулы / палочки Ауэра;
-  - подозрительные зоны цитоплазмы.
-
-### 5.4. Независимые переменные
-
-- Тип архитектуры:
-  - CNN;
-  - Vision Transformer / Swin;
-  - MIL.
-- Тип объяснения:
-  - saliency map;
-  - Grad-CAM-подобная тепловая карта;
-  - attention rollout;
-  - ranking клеток в MIL.
-- Тип целевой задачи:
-  - `бласт / не бласт`;
-  - `лимфобласт / миелобласт`;
-  - slide-level `blast-positive / blast-negative`.
-
-### 5.5. Зависимые переменные
-
-- balanced accuracy;
-- macro-F1;
-- sensitivity для лимфобластов и миелобластов;
-- IoU или другая мера перекрытия объяснений с экспертными областями интереса;
-- устойчивость объяснений между повторами обучения;
-- экспертная оценка клинической правдоподобности объяснений;
-- частота выявления новых, ранее не формализованных признаковых гипотез.
-
-### 5.6. Baseline-источники
-
-- `hehr2023scemila`
-- `schouten2021tens`
-- `park2024blastdiff`
-- `katar2023xvit`
-- `iwata2025clinicalreliability`
-- `singi2025caremil`
-- `jammal2025neurobridgex`
-- `jammal2025causalformer`
-- `deltadahl2025cytodiffusion`
-
-### 5.7. Протокол
-
-1. Обучить CNN, transformer-подобную модель и MIL-вариант на одинаковых patient-level разбиениях.
-2. Для каждой модели сгенерировать объяснения одного и того же типа или привести их к сопоставимому виду.
-3. Сравнить объяснения с экспертными областями интереса.
-4. Отдельно провести blinded review: показать эксперту только explanation maps и спросить, соответствуют ли они биологически правдоподобным признакам.
-5. Зафиксировать повторяющиеся class-specific паттерны и проверить, можно ли затем описать их классическими признаками.
-
-### 5.8. Абляции
-
-- без цветовой нормализации и с ней;
-- без nucleus mask и с ней;
-- без специальных explanation loss и с ним, если такой используется;
-- CNN и transformer при одинаковом числе параметров;
-- cell-level обучение против MIL при более грубых метках.
-
-### 5.9. Риски
-
-- explanation maps могут быть визуально убедительными, но нестабильными;
-- экспертная интерпретация объяснений может различаться между наблюдателями;
-- часть найденных паттернов может оказаться лабораторным артефактом, а не реальной морфологией.
-
-## 6. Эксперимент 4. Анализаторно-ориентированное обнаружение бластов на уровне препарата
-
-### 6.1. Исследовательский пробел
-
-Большая часть литературы заканчивается на уровне одиночной клетки. Для автоматического анализатора этого недостаточно: сначала нужно найти подозрительные клетки на препарате, а уже затем классифицировать их.
-
-### 6.2. Гипотеза
-
-Whole-slide или wide-field стратегия поиска кандидатов с последующей blast-focused классификацией обеспечит более высокую чувствительность на уровне препарата, чем фиксированный обзор ограниченного числа клеток, особенно в редких и лейкопеничных случаях.
-
-### 6.3. Данные
-
-- Slide-level набор препаратов с экспертным заключением `blast-positive / blast-negative`.
-- Отдельное подмножество с клеточными разметками для обучения второго этапа.
-- Желательно выделить сложную подгруппу:
-  - лейкопеничные препараты;
-  - препараты с редкими бластами;
-  - препараты с артефактами и плохой окраской.
-
-### 6.4. Независимые переменные
-
-- Режим обзора:
-  - фиксированный обзор ограниченного числа клеток;
-  - region-focused обзор;
-  - whole-slide candidate mining.
-- Способ формирования кандидатов:
-  - эвристическая сегментация;
-  - detector;
-  - ранний analyzer preclassifier.
-- Способ второго этапа:
-  - handcrafted baseline;
-  - hybrid model;
-  - deep classifier.
-- Правило передачи кандидатов человеку:
-  - по blast probability;
-  - по uncertainty;
-  - по комбинированному score.
-
-### 6.5. Зависимые переменные
-
-- case-level sensitivity;
-- false negatives per slide;
-- false positives per slide;
-- число клеток, переданных на экспертную проверку;
-- время анализа одного препарата;
-- доля случаев, в которых анализатор не пропустил ни одного бласта.
-
-### 6.6. Baseline-источники
-
-- `boldu2019automatic`
-- `wang2025advantages`
-- `dealmeida2023cytomorphologies`
-- `manescu2023apl`
-- `singi2025caremil`
-
-### 6.7. Протокол
-
-1. Построить двухэтапный pipeline:
-   - генерация кандидатов на уровне препарата;
-   - blast-focused классификация кандидатов.
-2. Сравнить минимум три режима просмотра:
-   - ограниченное число клеток;
-   - локальный поиск по зонам интереса;
-   - полный скан препарата.
-3. Оценивать результат не только по cell-level качеству, но и по итоговой чувствительности на уровне случая.
-4. Отдельно анализировать подгруппу лейкопеничных препаратов.
-5. Проверять, помогают ли explanation-aware правила ранжирования передавать на верификацию более правдоподобные кандидаты.
-
-### 6.8. Абляции
-
-- ограничить число кандидатов, передаваемых на второй этап;
-- сравнить ranking по уверенности и по вероятности;
-- проверить, помогает ли текстурный score на этапе ранжирования кандидатов;
-- сравнить cell-level classifier и slide-level aggregation rule по отдельности.
-
-### 6.9. Риски
-
-- разметка на уровне препарата дорога и неполна;
-- слабый первый этап может испортить результат даже при сильном втором этапе;
-- на редких бластах итоговые метрики могут сильно колебаться.
-
-## 6. Общие требования к валидности
-
-Для всех трех направлений необходимо контролировать:
-
-1. отсутствие утечки изображений одного пациента между train, validation и test;
-2. явное разделение внутренней настройки модели и финального теста;
-3. учет межлабораторного и межприборного доменного сдвига;
-4. отдельную оценку редких классов, а не только общей accuracy;
-5. хранение версий разметки и фиксацию спорных клеток;
-6. обязательное сравнение как минимум одного классического, одного нейросетевого и одного гибридного baseline.
-
-## 7. Приоритет реализации
-
-Если двигаться поэтапно, то оптимальная очередность такая:
-
-1. сначала завершить Эксперимент 1 и получить интерпретируемый baseline;
-2. затем строить Эксперимент 2 как наиболее содержательное сравнение с нейросетями;
-3. после стабилизации cell-level моделей переходить к Эксперименту 3.
-
-Такая очередность позволяет не терять интерпретируемость на раннем этапе и при этом постепенно приближать работу к задаче полноценного автоматического анализатора препаратов крови в монослое.