# Benchmark LODO cho mọi decoder của SuperHugeAAD

**50 thí nghiệm**. Chính: 13 decoder × 2 kiểu tiền xử lý (mat, py), dùng **z-score cả trial** (ban tổ chức đã cho phép, giống `loadSubject.m`). So sánh: 12 decoder × 2 (mat_rz, py_rz), dùng z-score chạy causal. SSMamba chỉ chạy bản chính. Mỗi thí nghiệm gồm 5 fold LODO (train 4 dataset, test dataset thứ 5), sau đó phát hiện switch bằng HMM p_stay = 0.998 và chấm bằng scorer chính thức (bản Python đã kiểm chứng). Kết quả là **MEAN qua 5 dataset held-out**.

## Chạy và theo dõi

```bash
cd experiments/decoder_lodo
bash runners/launch.sh           # tạo tmux 'decoder_lodo': cửa sổ cpu (tuyến tính), gpu (DNN), status
tmux attach -t decoder_lodo      # Ctrl-b n / Ctrl-b p đổi cửa sổ, Ctrl-b d để thoát ra (vẫn chạy nền)
bash status.sh                   # xem tiến độ nhanh mà không cần vào tmux
```

- **Tự động chạy tiếp:** mỗi hàng đợi chạy lần lượt các dòng trong `runners/queues/cpu.txt`, `gpu.txt` và `ssm.txt`. Thí nghiệm nào đã có `results/<exp>.json` thì bỏ qua; thí nghiệm lỗi thì tạo `results/<exp>.FAILED` rồi chạy tiếp.
- **Resume:** mỗi fold được lưu ở `folds/<exp>/<dataset>.pkl`. Nếu máy dừng giữa chừng, chạy lại `bash runners/launch.sh` sẽ tiếp tục từ fold còn thiếu.
- **Tổng hợp kết quả:** chạy lại sau mỗi thí nghiệm, gồm `results/summary.xlsx`, `results/summary_mean.csv`, `results/summary_per_dataset.csv`, `results/SUMMARY.md`.

## Thiết kế

| thành phần | lựa chọn |
|---|---|
| Decoder tuyến tính (CPU) | `wf` (Wiener filter, Ledoit-Wolf, lags 0–400 ms như baseline), `wf_persubject`, `wf_riemann`, `wf_forward` (mô hình forward), `cca`, `fbcca` |
| Decoder DNN (GPU) | `simple_cnn`, `lsm_cnn`, `deformer`, `vlaai_ws`, `vlaai`, `deformer_ws`, `ssmamba` (tắt subject embedding: ID subject không được làm input) |
| Tiền xử lý **mat** | giống baseline MATLAB (`crossDatasetMain.m`): file `pre_*.mat` có sẵn (32 Hz, lọc 1–9 Hz zero-phase, sửa kênh xấu) + 58 kênh của baseline + CAR + **z-score cả trial** cho EEG và từng envelope (N−1, kênh toàn 0 thì chia cho 1, đúng như MATLAB) |
| Tiền xử lý **py** | bộ lọc causal của EDA: HP 0.5 Hz causal, CAR, BP 1–9 Hz causal, anti-alias, 32 Hz + **z-score cả trial**. Cùng 58 kênh |
| **mat_rz / py_rz** | như mat / py nhưng z-score chạy causal (EW, τ = 30 s, robust, clip ±5) thay cho z-score cả trial. Dùng để đo chênh lệch |
| Validation | LODO 5 fold. DNN dừng sớm theo 1 subject/dataset lấy từ **các dataset train** (không dùng dataset test) |
| Huấn luyện DNN | cửa sổ 5 s, loss tương phản −r(attended) + r(ignored), AdamW 5e-4, tối đa 40 epoch × 250 batch, dừng sớm sau 6 epoch không cải thiện; đầu ra qua lớp EinMix → 1 kênh (giống RegressionInterface) |
| Bằng chứng | cửa sổ 1 s, bước 0.25 s: d = r(cột 0) − r(cột 1) |
| Switch | TỔNG HỢP, cùng bộ sinh, seed và thứ tự trial với EDA, nên mọi thí nghiệm chấm trên cùng một lịch switch |
| Integrator | HMM 2 trạng thái, p_stay = 0.998 mỗi bước 0.25 s; emission (mu, sd) fit trên evidence out-of-fold của 4 dataset train |
| Chấm điểm | scorer chính thức (bản Python) → Acc, SDT, L, H từng dataset held-out, rồi MEAN. Kèm miss_rate, null L/H (bằng chứng đảo dấu ngẫu nhiên), acc 1 s/10 s, SNR₁ |

## Lookahead (ngân sách 1 s)

| decoder | nhìn trước | ghi chú |
|---|---|---|
| wf, wf_persubject, wf_riemann | 0.4 s | lags EEG 0–400 ms |
| cca | 0.4 s | EEG 0–400 ms; envelope −250–0 ms |
| fbcca | 0.5 s | FIR `padding='same'` dài tối đa 32 mẫu |
| wf_forward | 0 s | dự đoán EEG từ envelope quá khứ |
| DNN (causal, **chính**) | 0.5 s | mỗi mẫu đọc từ cửa sổ kết thúc ≤ 0.75 s sau nó, nhưng cửa sổ evidence 1 s kết thúc tại t_end chỉ cần EEG đến t_end + 0.5 s. Từ 2026-10-04 (trước đó đóng nhãn với 0.75 s, kết quả cũ giữ nguyên); kiểm tra bằng `leakage_test.py` |
| direct_clf, ghép (fuse_*) | 0.75 s | quyết định tại hop a dùng EEG < a + 0.75 s; khi ghép, cửa sổ decoder j đi với hop j + `DEC_OFFSET` (mặc định 3) |
| DNN offline (tham khảo) | 3.75 s | **vi phạm luật**; lưu riêng trong `offline_reference_NONCOMPLIANT` |

Nhãn được phát từ t_end + lookahead − 1 s. Lưu ý: tiền xử lý **mat** dùng file đã lọc zero-phase, bản thân việc này dùng dữ liệu tương lai. Ban tổ chức đã cho phép z-score cả trial.

## Lỗi trong package SuperHugeAAD và cách xử lý (package gốc không bị sửa)

| thành phần | lỗi | xử lý trong `decoders.py` |
|---|---|---|
| `VLAAI_ws.__init__` | `NameError: name '_' is not defined` (khối chia sẻ trọng số không nhận được số kênh đầu vào khác nhau) | thêm lớp chiếu 1×1 C → num_kernels[-1], sau đó dùng khối của package |
| `rebok_vlaai.yaml` | tên tham số không khớp class | dùng `output_context_kernel_size=17` |
| `FilterbankCCA.update` | không tăng `_n_samples`, nên `fit()` chia cho 0 và cho ra NaN | tự đếm mẫu; giải CCA bằng đúng hàm của package ở float64 + ridge nhỏ |
| `ForwardWienerFilter.predict` | pattern einops sai | tự tính dự đoán từ trọng số đã fit |
| `RiemannianWienerFilter.update` | lưu một ma trận p×p cho mỗi mẫu, không chạy được ở quy mô corpus | trung bình Riemann của hiệp phương sai theo từng subject |
| LODO qua `MultiRunCLI` | lỗi `unhashable type: 'MetadataElement'` (log cũ) | không dùng CLI; tự viết vòng LODO |
| SSMamba | thiếu CUDA kernel Cauchy, chạy chậm (~5 phút/epoch) | giữ nguyên, xếp cuối hàng đợi |

## Cấu trúc thư mục

```
decoder_lodo/
├── config.yaml            mọi tham số (tiền xử lý, DNN, augmentation, HMM)
├── common_exp.py          đường dẫn, nạp dữ liệu, tính bằng chứng r0/r1
├── prepare_data.py        cache các kiểu tiền xử lý: mat, py, fft, mat_rz, py_rz
├── decoders.py            13 decoder (tuyến tính + DNN), augmentation, warm-up
├── run_experiment.py      1 thí nghiệm = 1 decoder × 1 tiền xử lý × 5 fold LODO → results/<exp>.json
├── score.py               switch tổng hợp + HMM + scorer chính thức
├── integrators.py         (bước 1–2) HMM thích nghi / CUSUM trên GPU, trên bằng chứng đã lưu
├── msm.py                 Markov switching model mức mẫu trên GPU (cần --save-recon)
├── summarize.py           gộp kết quả → results/summary.xlsx, SUMMARY.md, CATALOG.md
├── status.sh              xem tiến độ mọi hàng đợi
├── runners/               script chạy trong tmux (launch.sh, run_queue.sh, queues/, run_*.sh)
│   └── jobqueue.py        HÀNG ĐỢI CHUNG có giới hạn tài nguyên (xem bên dưới)
├── debug/                 thí nghiệm chẩn đoán nhỏ (debug VLAAI, ensemble + p_stay)
├── cache/<prep>/          dữ liệu đã tiền xử lý (≈10 GB)
├── folds/<exp>/           kết quả từng fold (bằng chứng, có thể kèm reconstruction)
├── logs/                  log từng thí nghiệm (<exp>.log/.stdout) và từng hàng đợi (queue_*.log)
└── results/
    ├── <exp>.json         kết quả 1 thí nghiệm (MEAN + từng dataset held-out)
    ├── summary.xlsx       mọi thí nghiệm; mỗi nhóm A–H một sheet group_X
    ├── CATALOG.md         danh mục thí nghiệm theo nhóm, tốt nhất mỗi nhóm in đậm
    └── research/          kết quả phân tích: ensemble/p_stay, integrators_*, msm_*
```

**Hàng đợi job (từ 2026-09-30, dùng cho mọi thí nghiệm mới):** scheduler chạy trong tmux cửa sổ `jobq`, chỉ khởi động job
mới khi < 2 job của nó đang chạy, tải CPU (1 phút) < 7 và GPU còn ≥ 6 GB; job chạy `nice -n 10`, 2 luồng BLAS, scorer 3 worker.
```bash
../../.venv/bin/python runners/jobqueue.py add 020_ten_job -- "<lệnh>"   # tiền tố số = thứ tự ưu tiên
../../.venv/bin/python runners/jobqueue.py status
```
Log từng job: `logs/jobs/<tên>.log`, log scheduler: `logs/jobqueue.log`.

**Nhóm thí nghiệm** (đặt theo hậu tố tên, xem `results/CATALOG.md`):
A benchmark chính · B z-score causal (`_rz`) · C sửa VLAAI (`_wu10`, `_skip`) · D độ dài cửa sổ (`_w3s/_w7s/_w10s`) ·
E augmentation (`_aug*`) · F tiền xử lý FFT (`__fft`) · H lặp seed (`_s1.._s3`).

## File

Xem sơ đồ ở mục Cấu trúc thư mục phía trên.
