Add readme & enviroments requirements.txt

README.md

@@ -0,0 +1,91 @@
+# EdgeNeXt × Optuna × Naruto Sign — код HPO-эксперимента
+
+Учебно-исследовательский код к методичке [`../PROTOCOL_HPO_EdgeNeXt_NarutoSign.md`](../PROTOCOL_HPO_EdgeNeXt_NarutoSign.md)
+(научный руководитель — мнс Павленко Б.В.). Задача: подбор гиперпараметров дообучения
+компактного энкодера **EdgeNeXt** на наборе **Naruto Sign** (классификация ручных печатей).
+
+## Установка
+
+```bash
+# Python 3.10–3.12 (PyTorch ещё не собран под 3.14)
+python -m venv .venv && . .venv/Scripts/activate   # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+## Данные
+
+```python
+import kagglehub
+path = kagglehub.dataset_download("vikranthkanumuru/naruto-hand-sign-dataset")
+print(path)   # внутри — папки-классы (ImageFolder)
+```
+
+Сразу посчитать реальную статистику (заполнить таблицу в STATS.md):
+
+```bash
+python -m src.dataset_stats --data-root <PATH> --out results/dataset_stats.json
+```
+
+## Запуск экспериментов
+
+```bash
+# B0 — baseline (один честный прогон, test + confusion matrix)
+python -m src.run_baseline --data-root <PATH> --regime partial --n-unfrozen 1 --epochs 30
+
+# E1 — ablation режимов (повторить для full / partial(0..4) / mona)
+python -m src.run_baseline --data-root <PATH> --regime full   --epochs 30 --out results/e1_full
+python -m src.run_baseline --data-root <PATH> --regime partial --n-unfrozen 0 --out results/e1_lp
+python -m src.run_baseline --data-root <PATH> --regime mona   --epochs 30 --out results/e1_mona
+
+# E2 — Optuna single-objective (TPE + median pruning), persist to sqlite
+python -m src.optuna_search --data-root <PATH> --sampler tpe --pruner median \
+    --n-trials 60 --epochs 25 --study-name nss_v1 --storage
+
+# E3 — Optuna multi-objective (macro-F1 ↑ vs trainable params ↓)
+python -m src.optuna_search --data-root <PATH> --multi-objective --sampler nsga \
+    --n-trials 80 --study-name nss_mo
+
+# E4 — UMAP анализ признаков (до дообучения и с чекпойнтом — после)
+python -m src.umap_analysis --data-root <PATH> --split val --out results/umap_pretrained
+python -m src.umap_analysis --data-root <PATH> --checkpoint <best.pt> --out results/umap_finetuned
+
+# E5 (опц.) — контроль метода: random vs TPE при равном бюджете
+python -m src.optuna_search --data-root <PATH> --sampler random --n-trials 60 --study-name nss_random
+```
+
+Все скрипты — модули пакета `src`, запускать из папки `code/` через `python -m src.<name>`.
+
+## Визуализация Optuna
+
+```python
+import optuna
+from optuna.visualization import (plot_optimization_history,
+                                  plot_param_importances, plot_pareto_front)
+study = optuna.load_study(study_name="nss_v1", storage="sqlite:///nss_v1.db")
+plot_optimization_history(study).show()
+plot_param_importances(study).show()          # fANOVA — какие гиперпараметры важны
+```
+
+## Структура
+
+| Модуль | Назначение |
+|:--|:--|
+| `src/data.py` | ImageFolder, стратиф. split, transforms (hflip OFF), sampler, class weights |
+| `src/model.py` | EdgeNeXt (timm), режимы full/partial/mona, freeze, param-groups, фичи для UMAP |
+| `src/mona.py` | Conv-MONA адаптер (по `Leiyi-Hu/mona`), вставка hook'ом |
+| `src/losses.py` | CE / label-smoothing / weighted / Focal / effective-number weights |
+| `src/metrics.py` | macro-F1, balanced acc, top-k, MCC, κ, confusion (sklearn) |
+| `src/train.py` | train/eval, mixup, early-stop, Optuna pruning, VRAM-hygiene |
+| `src/optuna_search.py` | пространство поиска, single/multi-objective, sampler+pruner |
+| `src/umap_analysis.py` | эмбеддинги → UMAP 2D + кластеризация + ARI/NMI |
+| `src/run_baseline.py` | одиночный прогон + test + confusion-heatmap |
+| `src/dataset_stats.py` | статистика датасета |
+
+## Заметки по воспроизводимости
+
+- seed=42 по умолчанию (`src/train.py::set_seed`); финальные сравнения — 3 seed (42/123/456).
+- test трогать **один раз** в конце; HPO — только по val (macro-F1).
+- `lr`/`weight_decay` ищутся в **log**-шкале.
+- `RandomHorizontalFlip` **отключён** (печати чувствительны к лево/право).
+- Не включать `weighted_ce/focal` одновременно с `--weighted-sampler` на полную силу (двойная компенсация).
+- Главный риск Naruto Sign — **утечка кадров из одного видео** в train и test: если в именах файлов есть id видео, использовать `StratifiedGroupKFold` (см. методичку §3). Базовый `data.py` делает per-frame split — отметить риск в REPORT.md.