# ICBHI 2017: Frame-level ASD với BEATs

Phân loại âm phổi ICBHI 2017 (normal / crackle / wheeze / both) bằng **Frame-level Adventitious Sound Detection (Frame ASD)**: backbone BEATs (AS2M) sinh đặc trưng theo token thời gian-tần số, head dự đoán logit crackle và wheeze cho từng token, MIL pooling gộp về mức chu kỳ thở, rồi tìm ngưỡng kép để ánh xạ về 4 lớp.

Mục lục

1. [Bài toán và dữ liệu](#1-bài-toán-và-dữ-liệu)
2. [Cài đặt](#2-cài-đặt)
3. [Kiến trúc model](#3-kiến-trúc-model)
4. [Vòng train và đánh giá](#4-vòng-train-và-đánh-giá)
5. [Ablation ladder F0-F22](#5-ablation-ladder-f0-f22)
6. [Chain chính F12 -> F17 -> F20](#6-chain-chính-f12---f17---f20)
7. [Preprocessing ladder L1-L5](#7-preprocessing-ladder-l1-l5)
8. [Quy trình khôi phục F12](#8-quy-trình-khôi-phục-f12-scriptsf12_restoresh)
9. [Wavescale + fbank ICBHI, F12 -> F20 trực tiếp](#9-wavescale--fbank-icbhi-f12---f20-trực-tiếp-scriptswavescale_f20sh)
10. [Đánh giá và công cụ](#10-đánh-giá-và-công-cụ)
11. [Lưu ý](#11-lưu-ý)

---

## 1. Bài toán và dữ liệu

- Dataset: ICBHI 2017, split **official 60/40** (`--test_fold official`).
- Mỗi bản ghi được cắt thành từng chu kỳ thở theo annotation, resample về **16 kHz**, cắt hoặc pad về **5 s** (`--desired_length 5`, `--pad_types repeat`: pad bằng cách lặp lại tín hiệu).

| Split | File | Chu kỳ | normal | crackle | wheeze | both |
|---|---|---|---|---|---|---|
| train | 539 | 4142 | 2063 (49.8%) | 1215 (29.3%) | 501 (12.1%) | 363 (8.8%) |
| test | 381 | 2756 | 1579 (57.3%) | 649 (23.5%) | 385 (14.0%) | 143 (5.2%) |

Metric (`util/icbhi_util.get_score`):

- **Sp** = recall lớp normal.
- **Se** = tổng số chu kỳ bất thường đoán đúng lớp / tổng số chu kỳ bất thường (crackle + wheeze + both).
- **Score** = (Sp + Se) / 2.

Log còn in recall riêng cho crackle / wheeze / both và `n→whe_fp` (số chu kỳ normal bị đoán là wheeze).

## 2. Cài đặt

```bash
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
```

Cần có:

- `data/icbhi_dataset/audio_test_data/` (wav + txt annotation), `data/icbhi_dataset/official_split.txt`, `patient_list_foldwise.txt`, `metadata.txt`. Cache chu kỳ (`data/training.pt`, `data/test.pt`) được dùng nếu có.
- `pretrained_models/BEATs_iter3_plus_AS2M.pt`.
- Mỗi `best.pth` nặng khoảng **1.08 GB**. Các script đều kiểm tra dung lượng trống (`MIN_FREE_MB`, mặc định 1500).

## 3. Kiến trúc model

```mermaid
flowchart TD
    wave["Waveform 16 kHz, 5 s, B x 80000"] --> scale["Nhân beats_wave_scale (1 hoặc 32768)"]
    scale --> fbank["Kaldi fbank 128 mel, cửa sổ 25 ms, bước 10 ms, chuẩn hoá (x - 15.42) / (2 x 6.56)"]
    fbank --> specaug{"Đang train và use_specaug?"}
    specaug -->|có| sa["SpecAugment (icbhi_ast_sup / structured / sound_aware)"]
    specaug -->|không| patch
    sa --> patch["Patch embedding 16x16 trên mel x thời gian"]
    patch --> enc["BEATs Transformer encoder (768-d)"]
    enc --> tokens["Token B x N x 768 (khoảng 31 bước thời gian x 8 dải tần)"]
    tokens --> head["Frame ASD head: linear hoặc MLP"]
    head --> lc["logit crackle B x N"]
    head --> lw["logit wheeze B x N"]
    lc --> mil["MIL pooling: max hoặc mean top-k (k=3)"]
    lw --> mil
    mil --> prob["sigmoid: p_crackle, p_wheeze"]
    prob --> thr["Ngưỡng kép tau_c, tau_w"]
    thr --> cls["4 lớp: normal / crackle / wheeze / both"]
```

### 3.1 Backbone: [models/beats_encoder.py](models/beats_encoder.py), [BEATs/BEATs.py](BEATs/BEATs.py)

- `BeatsEncoder` load `BEATs_iter3_plus_AS2M.pt` và chỉ dùng `extract_features`, không dùng predictor gốc của BEATs. Kết quả `encode_frames()` là chuỗi token `[B, N, 768]`. "Frame" trong Frame ASD chính là các token patch này.
- `--beats_wave_scale`: waveform đọc từ file nằm trong [-1, 1]. BEATs chính thức nhân 2^15 (thang int16) trước fbank. Repo cũ (tháng 7) dùng **1**, và các checkpoint cũ chỉ đúng ở scale này. **32768** là thang chính thức.
- `--fbank_stats save/fbank_stats_s32768.json --fbank_norm {global,per_bin}`: thay hằng số AudioSet trong `BEATs.preprocess` (`(fbank - 15.41663) / (2 * 6.55582)`) bằng mean/std của fbank ICBHI trên tập train, tính bởi [scripts/fbank_stats.py](scripts/fbank_stats.py). File json ghi kèm `wave_scale` và phải khớp `--beats_wave_scale`. Hai giá trị này là buffer không persistent, nên checkpoint không đổi key. Không truyền `--fbank_stats` thì đặc trưng giống từng bit như trước. Thử nghiệm ở mục 9 cho thấy tuỳ chọn này **không** giúp ích.
- `--freeze_backbone`: đóng băng toàn bộ BEATs, chỉ train head (dùng ở F8, F10, F11, F20, fingerprint).
- SpecAugment chỉ chạy khi `model.training`. Mask được áp lên fbank trước patch embedding.

### 3.2 SpecAugment: [util/specaug.py](util/specaug.py)

| Policy | Mô tả |
|---|---|
| `icbhi_ast_sup` (mặc định, legacy) | 2 x FrequencyMasking(16) + 2 x TimeMasking(35) của torchaudio, fill 0, cùng một mask cho cả batch. Ở đường legacy, tensor có dạng `[B, 1, T, F]` nên mask tần số và thời gian bị **đổi trục**. `--specaug_axis_fix` sửa lỗi này. |
| `structured` | `StructuredSpecAug`: mask riêng cho từng mẫu, fill bằng giá trị trung bình của mẫu, đúng trục `[B, 1, F, T]`. Không tạo ra vạch ngang (giống wheeze) hay vạch dọc (giống crackle). |
| `sound_aware` | `structured` + mask tần số không bao giờ chạm vào dải bảo vệ wheeze (lấy từ `save/pattern_stats.json`), áp dụng cho mọi mẫu, không phụ thuộc nhãn. |
| `sound_aware_labeled` | Mask phụ thuộc nhãn. Pattern mask làm **lộ nhãn**: model học được quy luật "không bị mask = bất thường" nên Sp sụp ở test (L3 leaky: 45.66). Chỉ giữ lại để tái hiện lỗi này. |

### 3.3 Head: [method/frame_asd.py](method/frame_asd.py)

- `linear` (`FrameASDHead`): Dropout(0.1), sau đó hai nhánh `Linear(768, 1)` cho crackle và wheeze.
- `mlp` (`FrameASDMLPHead`, `--head_type mlp --head_hidden_dim 256`): `LayerNorm(768)`, `Linear(768, 256)`, `GELU`, `Dropout(0.1)` dùng chung, sau đó hai nhánh `Linear(256, 1)`.

### 3.4 MIL pooling và loss

- Nhãn 4 lớp được tách thành 2 nhãn nhị phân: `crackle = label in {1, 3}`, `wheeze = label in {2, 3}`.
- `mil_pool_logits`: `max` lấy logit lớn nhất theo token; `topk` lấy trung bình k logit lớn nhất (mặc định k=3 từ F2). `--mil_energy_guided` chỉ giữ các token có năng lượng RMS thuộc top `energy_top_frac`; tuỳ chọn này bị reject ở F3.
- `FrameASDLoss`: `BCEWithLogits(pooled_c, y_c, pos_weight_c) * w_crackle + BCEWithLogits(pooled_w, y_w, pos_weight_w) * w_wheeze`. `pos_weight = số mẫu âm / số mẫu dương` tính trên tập train (`get_frame_pos_weights`).
- Loss phụ (tuỳ chọn): `--wheeze_focal` (focal BCE cho wheeze), `--lambda_both` (BCE của `p_c * p_w` với nhãn both), `--lambda_pcsl` (patient contrastive loss trên trung bình token, [method/pcsl.py](method/pcsl.py)).

### 3.5 Suy luận: ngưỡng kép

- `search_dual_threshold`: duyệt lưới `tau_c, tau_w` trong [0.15, 0.95] (`--threshold_n_points 41`, tức bước 0.02), chọn cặp có Score cao nhất thoả `Se >= min_se` (48) và `Sp >= min_sp` (72). Nếu không cặp nào thoả, lấy cặp có Score cao nhất không ràng buộc (`constraint_fallback=True`).
- Ánh xạ `to_4class`: `p_c >= tau_c` và `p_w >= tau_w` cho ra both; chỉ crackle cho ra crackle; chỉ wheeze cho ra wheeze; còn lại là normal.
- Accuracy in trong log train dùng ngưỡng cố định 0.5, chỉ để tham khảo.

## 4. Vòng train và đánh giá

Entry: [train.py](train.py), helper: [util/frame_asd_train.py](util/frame_asd_train.py).

```mermaid
flowchart LR
    args["parse args, set_seed"] --> data["ICBHIDataset train/test, DataLoader"]
    data --> build["build_model: BEATs + head + FrameASDLoss + Adam"]
    build --> resume{"--resume?"}
    resume -->|có| load["load_checkpoint (backbone, head, optimizer)"]
    resume -->|không| loop
    load --> loop["Mỗi epoch"]
    loop --> lr["cosine LR"]
    lr --> tr["train_one_epoch"]
    tr --> ev["evaluate trên test fold + tìm ngưỡng kép"]
    ev --> ma["MA update (beta 0.5)"]
    ma --> best{"Score > best?"}
    best -->|có| save["lưu best.pth, best_threshold.json, class_metrics.json"]
    best -->|không| stale["stale += 1, early stop khi >= 8"]
    save --> loop
    stale --> loop
```

- Optimizer: Adam, `weight_decay 1e-6`, cosine LR theo `--epochs` (số epoch thay đổi thì đường LR cũng thay đổi).
- `--ma_update --ma_beta 0.5`: sau mỗi epoch, trọng số model được trộn với trọng số của epoch trước (moving average), áp dụng **sau** bước evaluate.
- Early stop sau `--early_stop_patience` (8) epoch không cải thiện.
- Resume:
  - `--resume ckpt`: load backbone + head + optimizer, train tiếp từ epoch đã lưu.
  - `--reset_epoch_on_resume`: bắt đầu lại từ epoch 1 (dùng cho finetune nhiều stage).
  - `--resume_backbone_only`: chỉ load backbone, head khởi tạo lại.
- Output trong `save/icbhi_<model>_<method>_<tag>/`: `train_args.json`, `best.pth`, `best_threshold.json` (tau, Sp, Se, Score), `class_metrics.json` (recall từng lớp, confusion matrix), `train.log` (khi chạy qua script). Kết quả best được thêm vào `save/results.json`.

Ví dụ một lệnh F12 đầy đủ (cấu hình chuẩn của mọi script BEATs):

```bash
python -u train.py --tag frame_asd_F12_xxx --method frame_asd --model beats --dataset icbhi --seed 2 \
  --class_split lungsound --n_cls 4 --batch_size 16 --desired_length 5 \
  --optimizer adam --weight_decay 1e-6 --cosine --test_fold official --pad_types repeat \
  --ma_update --ma_beta 0.5 --print_freq 50 --min_se 48 --min_sp 72 --early_stop_patience 8 \
  --mil_pool topk --mil_topk 3 --use_specaug --specaug_policy icbhi_ast_sup --threshold_n_points 41 \
  --ablation_stage F12 --epochs 15 --learning_rate 7e-5 --beats_wave_scale 1
```

## 5. Ablation ladder F0-F22

Mỗi stage thêm đúng **một** kỹ thuật lên cấu hình tích luỹ. [scripts/ablation_frame_asd_summary.py](scripts/ablation_frame_asd_summary.py) quyết định PROMOTE/REJECT so với stage được promote gần nhất:

- **REJECT** nếu: Score giảm hơn 0.30; hoặc Sp giảm hơn 2 điểm mà recall wheeze không tăng ít nhất 2 điểm; hoặc `n→whe_fp` tăng hơn 25.
- **PROMOTE** nếu: Score tăng ít nhất 0.30; hoặc Score không giảm, recall wheeze không giảm quá 1 điểm và `n→whe_fp` không tăng quá 10.

Cấu hình chung: seed 2, 15 epoch, LR 7e-5, `min_se 48`.

### 5.1 HFTT backbone (F0-F11)

Script: [scripts/ablation_frame_asd.sh](scripts/ablation_frame_asd.sh), [scripts/ablation_frame_asd_f8.sh](scripts/ablation_frame_asd_f8.sh). Model HFTT ([models/hftt.py](models/hftt.py)), batch 32. Checkpoint HFTT không còn trong `save/`. Các điểm bên dưới lấy từ tham chiếu ghi trong summary script.

| Stage | Kỹ thuật | Khởi tạo | Kết quả / quyết định |
|---|---|---|---|
| F0 | Baseline max-MIL (`frame_asd_v1`) | HFTT | 62.57 (Sp 76.38, Se 48.77), tham chiếu |
| F1 | Eval lại F0 với `min_sp 72` (không train) | F0 | dùng `min_sp 72` từ đây |
| F2 | `--mil_pool topk --mil_topk 3` + `min_sp 72` | scratch | promote |
| F3 | + `--mil_energy_guided` | scratch | reject |
| F4 | + `--use_specaug` (`icbhi_ast_sup`) | scratch | **63.53** (Sp 78.47, Se 48.60), promote |
| F5 | + `--wheeze_focal --focal_gamma 2` | scratch | reject |
| F6 | + `--frame_multiscale` | scratch | reject |
| F7 | + `--lambda_pcsl 0.05` | scratch | plateau 63.53, reject |
| F8 | Head MLP 256, backbone đóng băng | backbone F4 | warm-up head |
| F9 | Finetune toàn bộ F8, LR 2e-5, 10 epoch | F8 | |
| F10 | Head MLP + `--w_wheeze 1.3`, backbone đóng băng | backbone F4 | |
| F11 | Head MLP + `--lambda_both 0.5`, backbone đóng băng | backbone F4 | |

Cấu hình tích luỹ sau HFTT: `--min_sp 72 --mil_pool topk --mil_topk 3 --use_specaug`.

### 5.2 BEATs backbone (F12-F22)

| Stage | Kỹ thuật | Khởi tạo | LR / epoch | Script |
|---|---|---|---|---|
| F12 | Thay HFTT bằng BEATs-only, giữ cấu hình F4, head linear, finetune toàn bộ | BEATs AS2M | 7e-5 / 15 | [ablation_beats_only.sh](scripts/ablation_beats_only.sh) |
| F13 | `--w_wheeze 1.3` (đã comment) | F12 | 7e-5 / 15 | [ablation_frame_asd_f13_plus.sh](scripts/ablation_frame_asd_f13_plus.sh) |
| F14 | `--lambda_both 0.3` (đã comment) | F12 | 7e-5 / 15 | như trên |
| F15 | `--raw_augment 1` (đã comment) | F12 | 7e-5 / 15 | như trên |
| F16 | `--lambda_pcsl 0.01` (đã comment) | F12 | 7e-5 / 15 | như trên |
| **F17** | Finetune LR thấp | F12 best | 2e-5 / 10 | như trên |
| F18 | Train dài 25 epoch, patience 10 (đã comment) | scratch | 7e-5 / 25 | như trên |
| F19a | `--lambda_both 0.3` | F17 | 7e-5 / 15 | [ablation_beats_f19_plus.sh](scripts/ablation_beats_f19_plus.sh) |
| F19b | `--raw_augment 1` | F17 | 7e-5 / 15 | như trên |
| F19c | `--lambda_pcsl 0.01` | F17 | 7e-5 / 15 | như trên |
| F19d | Train dài từ đầu | scratch | 7e-5 / 25 | như trên |
| F19e | Finetune lần 2 từ run tốt nhất trong F17, F19a-d | best | 1e-5 / 10 | như trên |
| **F20** | BEATs đóng băng + head MLP 256 khởi tạo lại | backbone F17 | 7e-5 / 20 | [3test.sh](scripts/3test.sh) |
| F22 | MIL-align: `--mil_topk 2` khi train | F17 | 2e-5 / 10 | [ablation_beats_f22_mil_align.sh](scripts/ablation_beats_f22_mil_align.sh) |
| F22b | Finetune lần 2 (chỉ chạy khi F22 > F17) | F22 | 1e-5 / 8 | như trên |

F22 còn chạy `sweep_frame_asd_inference.py` (thử `mil_topk` 2/3, `min_sp` 66-72, `min_se` 46-50). Kết quả local: F22 đạt 63.50.

## 6. Chain chính F12 -> F17 -> F20

Script: [scripts/3test.sh](scripts/3test.sh).

```mermaid
flowchart LR
    as2m["BEATs AS2M"] --> f12["F12: finetune toàn bộ, head linear, 7e-5, 15 ep"]
    f12 --> f17["F17: resume F12, 2e-5, 10 ep, reset epoch"]
    f17 --> pick{"Score F17 >= F12?"}
    f12 --> pick
    pick -->|có| f20a["F20 dùng backbone F17"]
    pick -->|không| f20b["F20 dùng backbone F12"]
    f20a --> f20["F20: freeze BEATs, head MLP 256 mới, 7e-5, 20 ep"]
    f20b --> f20
```

- Một stage chỉ train lại khi chưa có `best.pth` của nó. F12 cũng bị bỏ qua nếu đã có F17.
- F20 ghi backbone nguồn vào `backbone_source.txt`. Script từ chối `F20_TAG=frame_asd_F20_mlp` để không ghi đè checkpoint tháng 7.
- Biến môi trường: `F12_TAG`, `F17_TAG`, `F20_TAG`, `F20_EPOCHS` (20), `BATCH_SIZE` (16), `EXTRA_ARGS` (thêm vào mọi stage, ví dụ `--beats_wave_scale 32768`). Mỗi bộ input khác nhau phải dùng tag riêng để không resume nhầm checkpoint.

```bash
bash scripts/3test.sh                     # f12 f17 f20
F12_TAG=frame_asd_F12_wavescale F17_TAG=frame_asd_F17_wavescale F20_TAG=frame_asd_F20_mlp_wavescale \
  EXTRA_ARGS="--beats_wave_scale 32768" bash scripts/3test.sh f17 f20
```

Kết quả (Score):

| Chain | F12 | F17 | F20 |
|---|---|---|---|
| Gốc tháng 7 (`../ICBHI_2017`) | 65.28 | 66.27 | 66.70 (`train_summary.json`) |
| Legacy local (scale 1) | 63.45 | 63.30 | 62.70 |
| Wavescale (scale 32768) | 64.56 | 64.18 | 64.78 |
| Wavescale + structured, seed 1, F20 trực tiếp (mục 9) | 66.32 | bỏ qua | 66.01 |

Checkpoint F17 tháng 7 không còn, chỉ còn F20 tháng 7 (`../ICBHI_2017/save/icbhi_beats_frame_asd_frame_asd_F20_mlp/best.pth`). Backbone trong F20 chính là backbone F17 vì F20 đóng băng backbone.

## 7. Preprocessing ladder L1-L5

Script: [scripts/f12_preproc_ladder.sh](scripts/f12_preproc_ladder.sh). Gốc là F12 wavescale (64.56, scale 32768). Mỗi bước thêm một nhóm tuỳ chọn lên các nhóm đã được nhận, và chỉ được nhận khi Score vượt best hiện tại. Run thua bị xoá checkpoint. Trạng thái lưu ở `save/f12_ladder_state.json`.

| Bước | Flag | Mô tả | Score |
|---|---|---|---|
| L1 wavecond | `--wave_highpass_hz 80 --wave_rms_norm -25` | High-pass 80 Hz zero-phase + chuẩn hoá RMS -25 dBFS (train + test) | 63.36 |
| L2 sastruct | `--specaug_policy structured` | SpecAug theo từng mẫu, fill mean, đúng trục | **64.96** |
| L3 sasound | `--specaug_policy sound_aware --specaug_stats save/pattern_stats.json` | L2 + bảo vệ dải wheeze cho mọi mẫu | 63.62 |
| L3 leaky | `sound_aware_labeled` | Mask theo nhãn, làm lộ nhãn | 45.66 (Sp 33.6) |
| L4 waveaug | `--wave_aug_p 0.5` | Chỉ khi train: gain ±6 dB, dịch vòng ±0.5 s, trộn nhiễu từ chu kỳ normal (SNR 15-25 dB) | 64.33 |
| L5 ormix | `--or_mix_p 0.3` | Chỉ khi train: trộn chu kỳ chỉ-crackle với chỉ-wheeze thành both | 63.51 |

`save/pattern_stats.json` được sinh bởi [scripts/analyze_patterns.py](scripts/analyze_patterns.py) (dải mel bảo vệ wheeze, độ rộng mask thời gian an toàn cho crackle). [scripts/check_preproc.py](scripts/check_preproc.py) kiểm tra nhanh các bước tiền xử lý trên CPU.

## 8. Quy trình khôi phục F12 ([scripts/f12_restore.sh](scripts/f12_restore.sh))

Mục tiêu: có một F12 đạt `TARGET` (mặc định 65.0) để chạy lại F17 -> F20 và về lại mức tháng 7.

```mermaid
flowchart TD
    p0["Phase 0: kiểm tra data, md5 BEATs (repo này vs repo gốc), disk, GPU"] --> p1["Phase 1: audit preprocessing so với ../ICBHI_2017 (f12_preproc_audit.py)"]
    p1 --> p2["Phase 2: fingerprint, head MLP mới trên backbone F20 tháng 7 đóng băng, FP_EPOCHS=20, scale 1 và 32768"]
    p2 --> dec{"Scale nào cho Score cách 66.70 không quá FP_TOL (0.5)?"}
    dec -->|khớp| p3a["Phase 3a: F12 legacy, icbhi_ast_sup, scale khớp, SEEDS_LEGACY"]
    dec -->|không khớp| stop["Dừng (FORCE=1 để chạy tiếp với scale 1)"]
    p3a --> hit{"Score >= TARGET?"}
    hit -->|có| p4["Phase 4: summary + lệnh F17/F20"]
    hit -->|không| p3b["Phase 3b: wavescale 32768 + structured SpecAug, SEEDS_NEW"]
    p3b --> p4
```

- **Fingerprint (Phase 2)**: script train một head MLP mới trên backbone F20 tháng 7 (đóng băng) ở hai scale input. Scale nào cho điểm gần 66.70 nhất (và nằm trong `FP_TOL`) được coi là scale input của tháng 7. Mặc định `FP_EPOCHS=20`, giống F20 tháng 7. Kết quả lưu ở `save/f12_restore/fp_scale<scale>_e<epochs>.json`, run ở `save/f12_restore/icbhi_beats_frame_asd_fp_head_s<scale>_e<epochs>/`.
- Nếu scale khớp thay đổi trong khi đã có run legacy (của các seed sắp chạy) train ở scale khác, script dừng (`soft_die`) để không dùng lại kết quả sai scale.
- Mỗi run F12 có tag `frame_asd_F12_restore_<legacy|sastruct>_s<seed>`. Run đã xong có file `.done` và được dùng lại. Chỉ run tốt nhất được giữ `best.pth`. Trạng thái lưu ở `save/f12_restore/state.json`, tổng kết ở `save/f12_restore/summary.json`.
- Biến môi trường: `TARGET` (65.0), `SEEDS_LEGACY` (2), `SEEDS_NEW` (2), `FP_EPOCHS` (20), `FP_TOL` (0.5), `FORCE` (0), `BATCH_SIZE` (16), `MIN_FREE_MB` (1500), `ORIG_ROOT` (`/root/thao/ICBHI_2017`). Đặt `SEEDS_LEGACY=""` hoặc `SEEDS_NEW=""` để bỏ qua phase tương ứng.

```bash
bash scripts/f12_restore.sh                                        # fingerprint 20 epoch + seed 2
SEEDS_LEGACY="" SEEDS_NEW="" bash scripts/f12_restore.sh           # chỉ fingerprint
```

Kết quả đến thời điểm hiện tại:

| Run | Scale | SpecAug | Score | Ghi chú |
|---|---|---|---|---|
| Fingerprint 3 epoch, scale 1 | 1 | icbhi_ast_sup | 66.35 | khớp 66.70 (cách -0.35) |
| Fingerprint 3 epoch, scale 32768 | 32768 | icbhi_ast_sup | 64.68 | |
| legacy seed 1 | 1 | icbhi_ast_sup | 62.21 | |
| legacy seed 3 / 4 / 5 | 1 | icbhi_ast_sup | 50.00 / 50.02 / 50.00 | sụp ngay từ epoch 1 (Se 0, loss đứng khoảng 1.95) |
| sastruct seed 1 | 32768 | structured | **66.32** | best ở epoch 4, dừng tay ở epoch 11 (7 epoch không cải thiện), chưa ghi vào `state.json` |

Sau khi có F12 đạt mục tiêu, Phase 4 in lệnh chạy tiếp:

```bash
F12_TAG=<run> F17_TAG=frame_asd_F17_<x> F20_TAG=frame_asd_F20_mlp_<x> EXTRA_ARGS="--seed .. --specaug_policy .. --beats_wave_scale .." \
  bash scripts/3test.sh f17 f20
```

### 8.1 Oracle tháng 7 ([scripts/july_oracle.py](scripts/july_oracle.py))

Dùng checkpoint F20 tháng 7 còn sót lại để kiểm tra code hiện tại có lệch so với code tháng 7 hay không. Kết quả ở `save/july_rebuild/oracle.json`.

- **Phần A, eval head đã lưu**: ở scale 1, pooling topk, không đổi chỗ crackle/wheeze, head tháng 7 cho **66.49** (Sp 84.8, Se 48.2). Head đã lưu tái hiện đúng điểm của nó; nhận định cũ rằng nó "không tái hiện được" là sai. Đổi chỗ hai nhánh làm Score rơi xuống khoảng 47, và pooling mean cho 61.3.
- **Phần B, train lại 1 epoch F20** với đúng args tháng 7 trên backbone tháng 7 (best của F20 tháng 7 nằm ở epoch 1, Adam step 259). Head khởi tạo trùng khớp (cosine 1.0 trên các tensor có seed), head sau 1 epoch có cosine ≥ 0.998 với head tháng 7, moment Adam có cosine ≥ 0.998, và Score 66.59. Vậy **code train F20 hiện tại khớp code tháng 7**; phần không tái lập được chỉ là quỹ đạo F12.

### 8.2 Sweep F12 legacy ([scripts/july_rebuild.sh](scripts/july_rebuild.sh))

Cấu hình F12 tháng 7 (scale 1, `icbhi_ast_sup`, LR 7e-5, 15 epoch), quét seed 1-13. Seed 1-5 lấy lại từ `save/f12_restore/state.json`. Run có Se < 5 trong 3 epoch đầu bị dừng sớm (sụp). Trạng thái lưu ở `save/july_rebuild/state.json`.

| Seed | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Score | 62.21 | 63.45 | sụp | sụp | sụp | sụp | 61.82 | **64.02** | 63.50 | 62.77 | sụp | 63.84 | 62.98 |

- 5/13 seed sụp về 50. 8 seed còn lại nằm trong khoảng 61.8-64.0, không seed nào đạt 65. Giá trị 65.28 của F12 tháng 7 là một lần may mắn ở rìa trên phân phối, không phải do code khác.
- Hướng legacy dừng ở đây; checkpoint `F12_july_s8` đã bị xoá. Bước F17 -> F20 của chain này không chạy.
- [scripts/compare_backbones.py](scripts/compare_backbones.py) đo linear CKA theo từng layer, độ lệch trọng số so với AS2M và Cohen's kappa giữa các head. CKA không phân biệt được backbone (ngay AS2M chưa finetune đã đạt khoảng 0.92 so với backbone tháng 7), nên chỉ dùng để tham khảo.

## 9. Wavescale + fbank ICBHI, F12 -> F20 trực tiếp ([scripts/wavescale_f20.sh](scripts/wavescale_f20.sh))

Bỏ hướng legacy, chuyển sang scale 32768 + structured SpecAug, thử chuẩn hoá fbank theo thống kê ICBHI và chạy F20 thẳng từ F12 (bỏ F17).

- **Thống kê fbank** ([scripts/fbank_stats.py](scripts/fbank_stats.py), chỉ dùng 4142 chu kỳ train): ở scale 32768, fbank thô của ICBHI có mean 11.27 và std 5.13 (AudioSet: 15.42 / 6.56). Với hằng số AudioSet, đầu vào sau chuẩn hoá có mean -0.32 và std 0.39 trên tập train. Chuẩn hoá ICBHI đưa về đúng 0 ± 0.5. Mel bin 3 là bộ lọc rỗng (luôn bằng log floor -15.94, std 0), nên std theo bin bị chặn dưới ở 0.1 x std global.
- **Script**: với mỗi cấu hình, train F12 qua `3test.sh f12` nếu chưa có kết quả. Nếu F12 ≥ `GATE` (64.5), train F20 (BEATs đóng băng, head MLP 256, 20 epoch) qua `3test.sh f20` với `F17_TAG=frame_asd_F17_none`, nên backbone lấy thẳng từ F12. `EXTRA_ARGS` mang seed, SpecAug, scale và cờ fbank để F20 thấy đúng đầu vào như F12. Chỉ F12 tốt nhất giữ `best.pth` (sau khi F20 của nó xong, hoặc khi trượt gate). Mọi checkpoint F20 đều được giữ. Trạng thái ở `save/wavescale_f20/state.json`, bảng ở `save/wavescale_f20/summary.json`.

```bash
bash scripts/wavescale_f20.sh                    # run + summary, resume được
ONLY="fbnorm_global_s2" bash scripts/wavescale_f20.sh run
bash scripts/wavescale_f20.sh summary
```

Kết quả (Score; both = recall lớp both):

| Cấu hình | Seed | SpecAug | fbank | F12 (Sp / Se / both) | F20 (Sp / Se / both) | F20 - F12 |
|---|---|---|---|---|---|---|
| `wavescale` | 2 | icbhi_ast_sup | AudioSet | 64.56 (80.9 / 48.2 / 26.6) | 64.78 (81.4 / 48.2 / 20.3) | +0.22 |
| `sastruct_s1` | 1 | structured | AudioSet | **66.32** (84.5 / 48.1 / 4.9) | **66.01** (83.6 / 48.4 / 8.4) | -0.31 |
| `L2_sastruct` | 2 | structured | AudioSet | 64.96 (80.3 / 49.6 / 21.0) | 64.59 (79.2 / 50.0 / 22.4) | -0.37 |
| `fbnorm_global_s1` | 1 | structured | ICBHI global | 62.63 (77.0 / 48.3 / 7.7) | dưới gate | - |
| `fbnorm_global_s2` | 2 | structured | ICBHI global | 64.96 (81.8 / 48.1 / 21.0) | 64.31 (80.1 / 48.5 / 19.6) | -0.64 |
| `fbnorm_perbin_s1` | 1 | structured | ICBHI per_bin | 62.86 (89.9 / 35.9 / 2.8) | dưới gate | - |
| `fbnorm_perbin_s2` | 2 | structured | ICBHI per_bin | 61.90 (85.1 / 38.7 / 12.6) | dưới gate | - |

Kết luận:

- **Chuẩn hoá fbank ICBHI không cải thiện.** So với hằng số AudioSet cùng seed, global cho F12 -3.68 (seed 1) và 0.00 (seed 2); per_bin cho -3.46 và -3.06, và không đạt `min_se 48` (Se 36-39), tức chuẩn hoá theo từng bin làm mất hình dạng phổ mà BEATs dùng để nhận ra crackle/wheeze. Giữ hằng số AudioSet (mặc định).
- **F20 trực tiếp không cộng thêm điểm** so với F12 ở cấu hình structured (-0.31, -0.37, -0.64), khác với chain tháng 7 (F17 66.27 -> F20 66.70). Head linear đã tốt ngay trên backbone F12, và F20 chỉ train lại head trên cùng backbone.
- Tốt nhất hiện tại: F12 `frame_asd_F12_restore_sastruct_s1` (66.32, checkpoint còn giữ) và F20 `frame_asd_F20_mlp_sastruct_s1_direct` (66.01). Cả hai đều có recall both rất thấp (5-8%), trong khi seed 2 cho both khoảng 21%.
- Mọi chênh lệch dưới khoảng 0.3 có thể chỉ là nhiễu, vì ngưỡng và best epoch được chọn trên test fold.

## 10. Đánh giá và công cụ

| Script | Công dụng |
|---|---|
| [scripts/eval_frame_asd.py](scripts/eval_frame_asd.py) | Eval một checkpoint (`--run_dir`), có thể ghi đè `--min_se/--min_sp/--mil_pool/--mil_topk/--beats_wave_scale` |
| [scripts/sweep_frame_asd_inference.py](scripts/sweep_frame_asd_inference.py) | Grid `mil_topk` x `min_sp` x `min_se` trên một checkpoint, không train lại |
| [scripts/ensemble_frame_asd.py](scripts/ensemble_frame_asd.py) | Ensemble nhiều run bằng cách trung bình xác suất (`--run_dirs`, `--fusion`) |
| [scripts/ablation_frame_asd_summary.py](scripts/ablation_frame_asd_summary.py) | Bảng ladder HFTT với PROMOTE/REJECT (`--ladder f8` cho F8-F11) |
| [scripts/pick_best_run.py](scripts/pick_best_run.py) | Chọn run có Score cao nhất từ `class_metrics.json` |
| [scripts/f12_preproc_audit.py](scripts/f12_preproc_audit.py) | Audit preprocessing so với repo gốc (CPU, chỉ đọc) |
| `save/results.json` | `[Sp, Se, Score, 0]` của best epoch cho mọi run |

```bash
python scripts/eval_frame_asd.py --run_dir save/icbhi_beats_frame_asd_frame_asd_F12_wavescale --min_sp 72
```

## 11. Lưu ý

- Ngưỡng `tau_c, tau_w` và việc chọn best epoch đều dựa trên **chính test fold** (cùng protocol với tháng 7). Vì vậy điểm số hơi lạc quan, và chênh lệch dưới khoảng 0.3 có thể chỉ là nhiễu.
- Trên cùng máy, cùng seed cho lại đúng kết quả (legacy seed 2: 63.45 hai lần; L2 sastruct seed 2: 64.96 hai lần), dù `cudnn.benchmark=True`. Không chạy hai job GPU cùng lúc khi cần tái lập, vì việc chọn thuật toán của cudnn có thể đổi. Phương sai giữa các seed lớn (vài điểm), nên luôn so sánh nhiều seed.
- Full finetune ở scale 1 với LR 7e-5 dễ **sụp** (model đoán mọi chu kỳ là normal, Score 50). Scale 32768 kết hợp structured SpecAug ổn định hơn.
- `save/icbhi_beats_frame_asd_frame_asd_F12_beats_only/best_threshold.json` hiện cho 51.28 (đã bị một lần chạy lại ghi đè). Giá trị 63.45 của chain legacy lấy từ `save/results.json`.
- F20 tháng 7: `train_summary.json` ghi 66.70, còn `best_threshold.json` trong cùng thư mục cho 66.40.
- Không sửa một script bash đang chạy (bash đọc file dần dần trong lúc chạy). Hãy dừng nó giữa hai run; các script đều resume được.
