# 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.