# Cấu trúc dữ liệu, định dạng file và toàn bộ script

Cập nhật: 2026-10-09. Tài liệu tra cứu cho repo `EEG-sAAD-Grand-Challenge-Training-Dataset`: dữ liệu nằm ở đâu, mỗi
loại file có cấu trúc gì, và mỗi script làm việc gì. Số liệu về dữ liệu lấy từ chính các file trên đĩa.

Tài liệu liên quan: `CONTEXT_README.md` (ngữ cảnh dự án), `experiments/decoder_lodo/README_BEST.md` (phương pháp tốt
nhất), `docs_challenge/` (luật cuộc thi).

## 1. Bản đồ thư mục

| Đường dẫn | Dung lượng | Nội dung |
|---|---|---|
| `archives/datasets/` | 30 GB | file ZIP gốc của 5 dataset và `SHA256.txt`; bất biến |
| `data/cnd/` | 30 GB | 5 dataset ở định dạng extended CND (`.mat`); chỉ đọc |
| `data/superhuge/` | 33 GB | cùng dữ liệu chuyển sang định dạng SuperHuge (`.npy` + `metadata.pkl`); chỉ đọc |
| `baselines/matlab_linear/` | | baseline tuyến tính + HMM của ban tổ chức (MATLAB) |
| `baselines/matlab_scoring/` | | bộ chấm điểm chính thức (MATLAB) |
| `baselines/python/SuperHugeAAD/` | | gói Python cho các mạng sâu baseline (VLAAI, SSMamba, ...) |
| `tools/` | | bộ chuyển CND → SuperHuge do ban tổ chức cấp, và hai script xuất mẫu / vẽ |
| `scripts/` | | `download_datasets.sh` |
| `docs/reference/` | | hướng dẫn extended CND (PDF) và các file CSV mẫu |
| `docs_challenge/` | | bản sao luật cuộc thi lấy từ Codabench (xem `CONTEXT_3_RULES.md`) |
| `reports/eda_full/` | | phân tích toàn bộ dữ liệu (EDA): script, bảng, hình, báo cáo PDF |
| `reports/onboarding/` | | tài liệu nhập môn (PDF) và script dựng nó |
| `reports/eda_raw/`, `reports/research_summary/` | | báo cáo phụ |
| `experiments/decoder_lodo/` | 76 GB cache, 12 GB folds | benchmark LODO và toàn bộ phương pháp (mục 6) |
| `experiments/external_data/` | 141 GB | dữ liệu ngoài và script chuyển đổi (mục 4) |
| `experiments/envelope_reverse/` | | dựng lại cách ban tổ chức tính envelope |
| `artifacts/ssmamba_raw128_attended_speaker_dev/` | | ví dụ một bản nộp thử của baseline SSMamba (CSV + manifest) |
| `submissions/` | | để trống; nơi đặt file nộp bài |
| `CONTEXT_*.md` | | ngữ cảnh làm việc và bản sao bộ nhớ của Claude |
| `EEG-sAAD Data Story.html` | | trang giới thiệu dữ liệu; rất lớn, không đọc nguyên file |
| `1.md` | | bản sao cũ của mô tả phương pháp (ngày 5/10), đã bị `README_BEST.md` thay thế |
| `temp.py`, `scoring_result.zip` | | file lẻ không thuộc quy trình mô tả ở đây; `temp.py` và `scoring_result.zip` đều là file rỗng (0 byte) |

`experiments/` là một repo git cục bộ (chỉ chứa mã, cấu hình và JSON kết quả); `.gitignore` loại `cache/`, `folds/`,
`logs/`, `raw/`, `extract/`, `stage_a/`. Phần còn lại của gốc repo không nằm trong git.

## 2. Năm dataset huấn luyện

Số liệu dưới đây tính từ `reports/eda_full/tables/trial_index.parquet` (một dòng mỗi trial).

| Khoá trong mã | Tên | Máy ghi | Ngôn ngữ | Người nghe | Trial | Độ dài mỗi trial | Tổng | Kênh |
|---|---|---|---|---|---|---|---|---|
| `AVGC` | KUL-AV-GC (`AVGCAAD2024`) | BioSemi | Hà Lan | 13 | 99 | 600 s | 16,5 h | 64 |
| `DTU` | DTU (`DTU2018`) | BioSemi | Đan Mạch | 18 | 1080 | 50 s | 15,0 h | 64 |
| `KUL` | KUL (`KUL2016`) | BioSemi | Hà Lan | 16 | 320 | 124–399 s | 20,5 h | 64 |
| `UHD` | KUL-Ultra-High-Density (`KUL_AAD_UltraHD2021`) | BioSemi | Hà Lan | 30 | 120 | 389–395 s | 13,0 h | 253 trong SuperHuge (255 trong CND) |
| `USTC` | USTC (`USTC2026`) | NeuroScan | Trung Quốc | 18 | 360 | 120 s | 12,0 h | 64 |

Tổng cộng 1979 trial, 95 người, khoảng 77 giờ. Tất cả đều có hai người nói cạnh tranh; người nghe chú ý **một người nói
suốt trial** (không có chuyển chú ý). KUL-AV-GC là dataset duy nhất kiểm soát hướng nhìn; ở đó hướng chú ý đổi tại giây
300 nhưng người nói được chú ý thì không đổi. Các dataset khác không kiểm soát hướng nhìn.

Hai tập test ẩn (không có mặt trên đĩa; phát hành ngày 9/11/2026): KUL-DLAAD (BioSemi 64 kênh, 19 người × 8 trial, hướng
nhìn kiểm soát) và NJU-SUSTech-sAAD-GC (NeuroScan 64 kênh, 12 người, hướng nhìn kiểm soát). Cả hai có chuyển chú ý.

### Danh sách kênh

Cả 5 dataset được đưa về 58 kênh chung `b64ustc58`, ghép theo tên (viết hoa) theo thứ tự 64 kênh BioSemi chuẩn, bỏ 6 kênh
USTC không có (AF7, AF8, P9, P10, Iz, AFz). Trong `reports/eda_full/scripts/common.py`: `B64`, `MONTAGES` (`common57`,
`b64ustc58`, `b64uhd62`). Kênh mà một dataset thiếu được điền 0 (UHD thiếu một kênh).

## 3. Định dạng file của dữ liệu cuộc thi

### 3.1 Extended CND (`data/cnd/<dataset>/`)

```
<dataset>/
  dataCND/
    dataSub<N>.mat        EEG thô của người N (128 Hz)
    dataStim<N>.mat       envelope thô của người nói (128 Hz)
    pre_dataSub<N>.mat    EEG đã tiền xử lý (32 Hz, 1-9 Hz, đã thay kênh hỏng)
    pre_dataStim<N>.mat   envelope tương ứng (32 Hz)
  preprocessCND.m         script tiền xử lý của ban tổ chức (filtfilt bậc 2, 1-9 Hz)
  removeBadChannels.m     thay kênh hỏng
  chanInfoBiosemi64.mat   thông tin kênh (AVGC, DTU, KUL)
  eeg255ch_locs.csv, channel-layout.jpg   (UHD)   trialAndLabelInformation.xlsx   (USTC)
```

Ở KUL-UHD thư mục thô chỉ có một file `dataStim` dùng chung cho mọi người (các file `pre_dataStim` thì mỗi người một file). `dataSub` của UHD và USTC là MATLAB v7.3 (HDF5, đọc bằng
`h5py`); các file `pre_*` và các dataset còn lại là v5 (đọc bằng `scipy.io.loadmat(..., squeeze_me=True,
struct_as_record=False)`).

**`dataSub<N>.mat`** chứa biến `neural` (struct):

| Trường | Kiểu / kích thước | Ý nghĩa |
|---|---|---|
| `dataType` | chuỗi | `EEG` |
| `deviceName` | chuỗi | ví dụ `BioSemi ActiveTwo`, `Neuroscan SynAmps ...` |
| `fs` | số | 128 (thô) hoặc 32 (`pre_`) |
| `chanlocs` | mảng 64 struct | `labels`, `theta`, `radius`, `X`, `Y`, `Z`, ... của từng kênh |
| `data` | mảng (số trial) các ma trận `(T, kênh)` float64 | EEG của từng trial |
| `extChan` | struct `{data, description}` | kênh ngoài (EOG), `(T, 4)` ở AVGC; một số dataset không có |
| `attendedStream` | mảng các vector `(T,)` | luồng được chú ý theo từng mẫu: 1 hoặc 2 (1 = `envelope_stream1`) |
| `attendedAzimuth` | mảng các vector `(T,)` | hướng được chú ý theo từng mẫu, độ: âm là bên trái (±90 ở AVGC và KUL, ±60 ở DTU) |
| `origTrialPosition` | vector | vị trí gốc của trial trong lượt ghi (DTU, KUL) |
| `originalReference` | | tham chiếu gốc (DTU) |
| `processingPipeline` | | mô tả bước tiền xử lý (chỉ ở `pre_`) |

**`dataStim<N>.mat`** chứa biến `stim` (struct):

| Trường | Ý nghĩa |
|---|---|
| `names` | `{'envelope_stream1', 'envelope_stream2'}` |
| `data` | mảng cell `(2, số trial)`: envelope của luồng 1 và luồng 2, mỗi cái `(T,)` float64 |
| `fs` | 128 hoặc 32 |
| `condNames`, `condIdxs` | tên và chỉ số điều kiện thí nghiệm (ví dụ `MovingVideo`) |
| `streamWav` | tên file âm thanh của từng luồng; ở KUL-AV-GC tên này không khớp với âm thanh thật (xem EDA) |

Lưu ý: ở mọi dataset huấn luyện, `attendedStream` không đổi trong một trial. Quy ước nhãn nộp bài: 0 = luồng 1, 1 = luồng 2.

### 3.2 SuperHuge (`data/superhuge/`)

Do `tools/convert_cnd_to_superhuge.py` tạo ra; hai tầng song song `raw/` (128 Hz) và `preprocessed/` (32 Hz, từ các file `pre_*`).

```
data/superhuge/{raw,preprocessed}/
  eeg/dataset-<DDD>-subject-<SSS>-trial-<TTT>.npy                  (T, kênh) float64, thứ tự Fortran
  stimuli/env/dataset-<DDD>-subject-<SSS>-trial-<TTT>_env.npy      (T, 1, 2) float64
  meta/metadata.pkl                                                dict: khoá trial -> hàng metadata
```

- **Khoá trial**: `dataset-DDD-subject-SSS-trial-TTT`. Mã dataset: 001 = KUL-AV-GC, 003 = DTU, 004 = KUL, 005 = KUL-UHD, 007 = USTC. Chỉ số
  người và trial không nhất thiết khớp với dataset gốc (ban tổ chức nói rõ điều này).
- **Envelope: cột 0 luôn là luồng được chú ý** (quy ước của bộ chuyển đổi, thay vì thứ tự luồng 1, 2 của CND). Do đó nhãn
  nộp bài (0 = luồng 1 của CND) phải đổi lại bằng `att_col`/`col0_stream` trong cache EDA.
- **`metadata.pkl`** là dict; mỗi hàng có `dataset_id`, `subject_id`, `trial_id`, `signal_length`, `num_channel`, `fs`,
  `dataset_name` (ví dụ `KUL-AV-GC_preprocessed`), `channel_infos` (`{1: {'name': 'Fp1'}, ...}`), `num_speakers`,
  `extra_info`, `label` (nhãn cả trial: `left`/`right`/`L`/...), `stimuli_name`, `compet_stimuli_name`, `wav`, `env`,
  `env_fs`, `mel`, `wav2vec2`.
- Đọc nhanh bằng `reports/eda_full/scripts/common.py`: `trial_index()` (bảng một dòng mỗi trial), `load_eeg(key, stage)`,
  `load_env(key, stage)` (trả `(T, 2)`), `load_labels(key)`, `load_pp(row, variant, montage, ...)`.

### 3.3 Cache của EDA (`reports/eda_full/`)

| File | Nội dung |
|---|---|
| `config.yaml` | đường dẫn, danh sách dataset, hạt giống, tham số phân tích |
| `cache/cnd/<key>.npz` | nhãn từng mẫu rút từ CND: `att_stream` (uint8), `att_az` (float32), `att_col` (int8; cột envelope của SuperHuge đang được chú ý), `env_cnd` `(T, 2)`, `col0_stream`, `wav` (2 tên), `cond`, `orig_pos`, `eog` `(T, 8)`, `eog_desc` |
| `cache/pp/`, `cache/recon/`, `cache/evidence/`, ... | các bộ đệm trung gian của các pha EDA |
| `tables/trial_index.parquet` | bảng trial (cột: `key, ds, did, subject, trial, n, nch, fs, label, channels, subj_uid, dur_s`) |
| `tables/*.csv`, `*.parquet`, `*.xlsx` | 70 bảng kết quả (xem `README.md` và báo cáo PDF của thư mục này) |

### 3.4 Định dạng file nộp bài và file chấm điểm

Mỗi người một file CSV, ba cột, chỉ số từ 0, 128 Hz:

```
time_index,label,trial
0,0,0
1,0,0
...
```

- `time_index`: chỉ số mẫu trong trial, bắt đầu lại từ 0 ở mỗi trial; `label`: luồng được giải mã (0 = luồng 1, 1 = luồng 2); `trial`: chỉ số trial.
- Tên file: dự đoán `test_sample_NNN.csv`; nhãn chuẩn `GTlabels_test_sample_NNN.csv`; ghép theo **số trong tên file**. Mỗi thư
  mục là một tập test.
- Cấu trúc thư mục chấm: `<outRoot>/groundtruth/`, `<outRoot>/plain/`, `<outRoot>/causal/`.
- Ví dụ thực: `artifacts/ssmamba_raw128_attended_speaker_dev/` (`csv/`, `local_groundtruth/`, `manifest.json` với
  `label_type`, `sampling_rate_hz`, `lookahead_ms`, `window_seconds`, ...).
- Ban tổ chức nói định dạng nộp chính thức và script nộp sẽ công bố sau; nếu khác, cập nhật mục này.

## 4. Dữ liệu ngoài (`experiments/external_data/`)

| Thư mục | Dữ liệu | Quy mô đã chuyển đổi | Dùng để |
|---|---|---|---|
| `Fuglsang2020/` | DTU hai người nói, BIDS (Zenodo 3618205) | 44 người, 1401 trial, 58 kênh, khoảng 20 giờ | train bổ sung; tính giá trị quần thể của căn chỉnh |
| `SparrKULee/` | KU Leuven, một người nói | khoảng 105 người, 793 lượt, khoảng 190 giờ | pretrain |
| `AASD/` | AASD (Zenodo 17413336), tiếng Trung; người nghe **tự quyết định** lúc chuyển chú ý và bấm phím (179 = trái, 184 = phải) | 18 người × 50 trial (chỉ trial 1–50; 51–60 là điều kiện thụ động), mỗi trial 60 s, trung vị 5 lần chuyển | chỉ đánh giá |
| `Carta2026/` | Carta et al. 2026 (PLOS Biology; Zenodo 20569817): hai bài TED trái / phải cộng tiếng ồn 16 người nói; chuyển chú ý **theo tín hiệu hình ảnh** mỗi 15–30 s | 24 người × 20 trial, mỗi trial 175 s, trung vị 6 lần chuyển; EEG đã xử lý sẵn (ICA, 0,5–20 Hz, 64 Hz) | chỉ đánh giá |
| `Broderick2018/` | Cocktail Party (Dryad) | 33 người, 128 kênh, chỉ có envelope tính sẵn | đã thử, không dùng |

Cấu trúc chung: `raw/` (file tải về), `extract/` (đã giải nén), `cache/` (đã chuyển đổi), `*.log`.

**`cache/<prep>/<khoá>.npz`** (Fuglsang, AASD, Carta): `eeg` `(T, 58)` float32, `env` `(T, 2)` float32, `att` `(T,)` int8, `t0` (giây).
AASD và Carta thêm `att128` `(n128,)` int8 (nhãn thật từng mẫu 128 Hz) và `n128`. Ở AASD và Carta, **cột 0 của `env` là
luồng bên trái, cột 1 là luồng bên phải** (không phụ thuộc người nghe đang chú ý bên nào; `att` cho biết bên đang được chú
ý, nhãn lấy từ phím bấm ở AASD và từ lịch tín hiệu chuyển ở Carta). Ở Fuglsang, cột 0 là người được chú ý và `att` luôn 0.
**`cache/index.csv`**: AASD/Carta có `key, subject, trial, n, n_switches, share_left`; Fuglsang có `key, subject, n32, attend`.

**SparrKULee**: mỗi lượt gồm `SPK_S<người>_<bài>_R<lượt>.npz` (`env` `(T, 2)`, `att`, `t0`) và `..._eeg.npy` (EEG `(T, 58)`
float16, đọc bằng `mmap`). Một người nói nên `env[:, 1]` là chính envelope đó, dịch nửa độ dài (mẫu âm "không khớp").

**Tín hiệu mục tiêu**: `cache/glimpsenorm/<khoá>.npz` (có `dom`) hoặc `glimpseonorm` (có thêm `orel`, `odiff`).

**Thông tin đăng nhập SparrKULee** chỉ nằm ở `/root/.netrc_sparrkulee`, không được đưa vào mã hay tài liệu.

## 5. Cache và kết quả của benchmark (`experiments/decoder_lodo/`)

### 5.1 `config.yaml`

Đường dẫn dữ liệu, `fs: 32`, `montage: b64ustc58`, định nghĩa mọi kiểu tiền xử lý (`preps`), tham số mạng (`dnn`), cửa sổ evidence
(`evidence`: 1 s, bước 0,25 s), HMM (`switch`: `p_stay: 0.998`), tăng cường (`dnn_augment`, `aug_variants`),
huấn luyện chuỗi (`dnn_seq`).

### 5.2 Cache dữ liệu đã tiền xử lý: `cache/<prep>/<khoá>.npz`

| Trường | Kích thước | Ý nghĩa |
|---|---|---|
| `eeg` | `(T, 58)` float32 | EEG sau tiền xử lý |
| `env` | `(T, 2)` float32 | envelope của hai luồng, z-score cả trial |
| `att` | `(T,)` int8 | cột envelope đang được chú ý (0 hoặc 1) |
| `t0` | số | thời điểm (giây) của mẫu đầu tiên so với đầu trial |

`T = (số mẫu 32 Hz) − 64`, vì cắt 1 s ở hai đầu; ví dụ AVGC 19200 → 19136, `t0 = 1,0`. Các kiểu tiền xử lý (`<prep>`):

| Tên | Nội dung |
|---|---|
| `mat` | file `pre_*` + 58 kênh + CAR + z-score cả trial (cách của baseline MATLAB) |
| `mat_rea`, `mat_rea30`, `mat_rea120` | thêm căn chỉnh Euclid nhân quả, khởi động lại mỗi trial (hằng số quên 60 / 30 / 120 s) |
| `mat_reac` | như `mat_rea` nhưng **mang trạng thái qua các trial của một người** (không hợp lệ ở giai đoạn test) |
| `mat_reap` | không mang trạng thái, khởi động từ giá trị quần thể |
| `eaP_n<N>_t<T>`, `eaI_n<N>_t<T>` | khởi động từ giá trị quần thể (`P`) hoặc ma trận đơn vị (`I`), trọng lượng khởi đầu `N` giây, hằng số quên `T` giây; **`eaP_n5_t60` là bản tốt nhất** |
| `mat_reac_tw*`, `mat_reac_beq`, `mat_reac_gamma`, `mat_reac_phase` | các biến thể đã thử và bỏ (làm trắng theo thời gian, cân bằng phổ, kênh gamma, kênh pha) |
| `mat_rz`, `py`, `py_rz`, `fft`, `fft15` | lọc nhân quả hoặc lọc FFT (`fft*` không hợp lệ) |

Các file phụ: `cache/ea_prior_fug.npy` `(58, 58)` (giá trị quần thể của căn chỉnh), `cache/glimpse<…>/<khoá>.npz` (tín hiệu
mục tiêu, mục 4), mỗi trường `(T, 2)` float32: `dom`, `orel`, `odiff`, `glim`, `mask`, `m`.

### 5.3 Evidence của từng fold: `folds/<thí nghiệm>/<DS>.pkl`

Pickle `{"evidence": {"causal": {khoá trial: {...}}, "offline": {...}}, "info": {...}}` (`offline` chỉ có ở decoder, là bản tham
khảo vi phạm luật). Mỗi trial:

| Trường | Kích thước | Ý nghĩa |
|---|---|---|
| `r0`, `r1` | `(n,)` float32 | điểm của luồng 0 và luồng 1 ở mỗi bước 0,25 s (decoder: tương quan Pearson trung bình; bộ phân loại: ±logit/2) |
| `att` | `(n,)` int8 | nhãn đúng của cửa sổ |
| `t_end` | `(n,)` float32 | thời điểm kết thúc cửa sổ (giây trong trial) |
| `r0_10`, `r1_10`, `att10` | `(n/40,)` | cửa sổ 10 s không chồng, để tính độ chính xác thuần |
| `r0f`, `r1f` | `(n, số mục tiêu)` float16 | tương quan theo từng mục tiêu (`env`, `onset`, `dom`); chỉ có ở decoder đa mục tiêu |
| `pre_switched` | bool | chỉ ở bộ phân loại: chuyển chú ý giả đã được áp lên đầu vào |

`info`: `decoder, prep, held_out, fit_s, total_s, lookahead_s, best_val, channels` (+ `controls` với bộ phân loại, + `crf`
nếu huấn luyện chuỗi). Chuyển chú ý giả được tạo lại cùng một lịch cho mọi thí nghiệm (cùng hạt giống `SEED + chỉ số dataset`).

### 5.4 Kết quả

| File | Nội dung |
|---|---|
| `results/<thí nghiệm>.json` | `experiment, decoder, prep, targets, loss, init_from, extra_train, window_s, train_seed, lookahead_s, ...` và `causal` = `{per_dataset: {DS: {Acc, SDT, L, H, nSwitches, nUndetected, miss_rate, emis_mu, emis_sd, null_L, null_H, acc1, acc10, snr1}}, mean: {...}, info: {...}, target_weights}` |
| `results/summary_mean.csv`, `summary_per_dataset.csv`, `summary.xlsx`, `SUMMARY.md`, `CATALOG.md` | bảng gom toàn bộ thí nghiệm (do `summarize.py` sinh) |
| `results/research/fuse_general.csv` | mọi lần ghép trên LODO: `ds, a, p_stay, H, Acc, SDT, name, n_dec, n_clf` |
| `results/research/fuse_external.csv` | mọi lần ghép trên chuyển chú ý thật |
| `results/research/*_evidence_s<seed>.pkl` | evidence thô trên AASD / Carta |
| `results/research/aasd_c1_*.json`, `ext_c1_*.json`, `ext_clf_*.json` | điểm của từng mô hình trên dữ liệu thật |
| `results/research/tune_ea.csv`, `hmm_bank.csv`, `adapt_within_trial.csv`, `leakage_test.csv`, ... | kết quả các phân tích khác |
| `models/pretrain_spk_*.pt` | trọng số pretrain trên SparrKULee (`torch.save` của `state_dict`) |
| `models/all5_direct_clf*.pt` | bộ phân loại train trên cả 5 dataset (cho chấm dữ liệu thật) |
| `logs/<thí nghiệm>.log`, `logs/jobs/<job>.log`, `logs/jobqueue.log`, `logs/fuse_*.log` | nhật ký; `fuse_*.log` có bảng điểm in sẵn |

**Quy ước tên thí nghiệm**: `<bộ giải mã>__<prep><tag>`, ví dụ `vlaai_ws__eaP_n5_t60_aug_cluster_onset_dom_xFUG_ptSPK` (decoder
`vlaai_ws`, prep `eaP_n5_t60`, tăng cường `cluster`, mục tiêu `onset_dom`, thêm Fuglsang `xFUG`, pretrain `ptSPK`) hoặc
`direct_clf__eaP_n5_t60_w10b3_ptSPK_aug-sw2` (bộ phân loại, cửa sổ 10 s `w10`, 3 khối `b3`, tăng cường `sw2`). Hậu tố `_s1`, `_s2`,
`_s3` là seed; seed 0 không có hậu tố (xem mục 7 của `CONTEXT_4_OPERATIONS.md`).

### 5.5 Hàng chờ job: `runners/jobs/{pending,running,done,failed,held}/<tên>.json`

```json
{"name": "417b_dec_eaP_n5_t60_s0", "cmd": "<lệnh shell>", "added": "...", "started": "...", "finished": "...", "returncode": 0}
```

`returncode` 137 là bị hệ điều hành kill vì hết RAM; 143 là nhận tín hiệu dừng từ bên ngoài. Đầu ra thô ở `logs/jobs/<tên>.log`.

## 6. Toàn bộ script

Chạy bằng `../../.venv/bin/python` (python hệ thống thiếu thư viện). Mô tả lấy từ đầu mỗi file; chạy `head -30 <file>` để xem cách dùng.

### 6.1 Công cụ của ban tổ chức (`tools/`, `scripts/`, `baselines/`)

| Script | Việc làm |
|---|---|
| `tools/convert_cnd_to_superhuge.py` | chuyển CND sang SuperHuge (mục 3.2) |
| `tools/export_all_features_labels_sample.py` | xuất mọi đặc trưng và nhãn theo mẫu của vài lát CND vào CSV mẫu |
| `tools/plot_cnd_superhuge_100samples.py` | vẽ 100 mẫu CND và SuperHuge cạnh nhau để so |
| `scripts/download_datasets.sh` | tải 5 dataset |
| `baselines/matlab_linear/crossDatasetMain.m` | chạy baseline tuyến tính + HMM; `functions/` (nạp dữ liệu `loadSubject.m`, huấn luyện `trainLinearDecoder.m`, chuyển chú ý tổng hợp `generateSyntheticSwitches.m`, `runHMMPostprocessor.m`, `expandToSamples.m`, `exportPredictions.m`, ...) và `HMM/` (`forwardBackward.m`, `computeLikelihood.m`) |
| `baselines/matlab_scoring/crossDatasetScoring.m` | chấm điểm một thư mục CSV; `scorePredictions.m`, `computeSwitchLatency.m`, `reportScores.m`, `readLabelCsv.m`, `defaultLatencyOpts.m` |
| `baselines/python/SuperHugeAAD/` | gói `superhuge` (mô hình trong `superhuge/model/`: `pure_cnn` = VLAAI, `ssmamba`, `former`, `linear`, `loss`, ...), thư mục `train/`, `tools/`, `tests/` |

### 6.2 Phân tích dữ liệu (`reports/eda_full/scripts/`)

Chạy tuần tự bằng `run_all.sh`; mỗi bước có thể chạy lại (cache theo trial / theo người).

| Script | Việc làm |
|---|---|
| `common.py` | hàm dùng chung: đường dẫn, bảng trial, nạp dữ liệu, bộ lọc, thống kê |
| `a0_field_tree.py`, `a1_qc.py`, `a2_qc_report.py` | cây trường của CND; kiểm tra chất lượng từng trial và tổng hợp |
| `b1_cnd_extract.py` | rút nhãn từng mẫu từ CND và gắn vào khoá SuperHuge (`cache/cnd/`) |
| `b2_envelope_audit.py`, `b4_envelope_identity.py` | kiểm tra envelope và danh tính kích thích |
| `b3_drift_classifier.py` | đoán nhãn chỉ từ trôi chậm của tín hiệu (kiểm tra đi tắt) |
| `c0_cache_pp.py` | dựng cache đã lọc và hạ mẫu |
| `c1_xcorr.py`, `c2_decoders.py`, `c3_windows.py`, `c4_decoder_report.py` | tương quan chéo, bộ giải mã ridge ngược, đánh giá theo cửa sổ, báo cáo |
| `d0_spatial_cache.py`, `d1_fingerprint.py`, `d3_spatial.py`, `d4_physiology.py` | giải mã không gian, "dấu vân tay" của dataset và người, sinh lý |
| `e0_scorer_tests.py`, `scorer.py` | **bộ chấm điểm Python**, bản chuyển từng dòng của MATLAB, và các bài kiểm tra tương đương |
| `e1_switch.py` | HMM, chuyển chú ý tổng hợp (`synth_trial`), đóng nhãn 128 Hz (`expand`), tích hợp |
| `e2_spatial_switch.py` | phát hiện chuyển chú ý thật của KUL-AV-GC bằng nhãn hướng |
| `e3_lookahead_test.py` | kiểm tra rò rỉ cho pipeline EDA |
| `f1_verdicts.py`, `f2_howto.py`, `f2_report.py` | kết luận cho các giả thuyết và dựng báo cáo PDF |
| `run_all.sh` | chạy toàn bộ EDA |
| `reports/onboarding/build_guide.py`, `make_figures.py` | dựng tài liệu nhập môn |

### 6.3 Benchmark và phương pháp (`experiments/decoder_lodo/`)

**Dữ liệu và tiền xử lý**

| Script | Việc làm |
|---|---|
| `common_exp.py` | hàm dùng chung: đường dẫn, nạp trial, tương quan cửa sổ (`sliding_corr`, `evidence_from_features`), tên file fold |
| `prepare_data.py` | dựng cache cho mọi kiểu tiền xử lý (`python prepare_data.py <prep>`); chứa `causal_ea`, `ea_prior`, `causal_tw`, `zscore_trial` |
| `build_ea_prior.py` | tính giá trị quần thể của căn chỉnh Euclid từ Fuglsang |
| `build_glimpse.py` | tính các tín hiệu mục tiêu `dom`, `orel`, `odiff`, `glim`, `mask` từ envelope thô |
| `tune_ea.py` | dò tham số căn chỉnh Euclid bằng bộ giải mã tuyến tính |

**Huấn luyện và chấm LODO**

| Script | Việc làm |
|---|---|
| `decoders.py` | mọi bộ giải mã dùng chung một giao diện: tuyến tính, CCA, `vlaai_ws`, ADT, HappyQuokka, ...; tăng cường dữ liệu, loss đối kháng, `DNNDec`, `apply_overrides` |
| `run_experiment.py` | một thí nghiệm = một bộ giải mã × một prep, 5 fold LODO rồi chấm; cờ chính: `--decoder --prep --tag --train-seed --targets --aug-variant --extra-train --init-from --evidence-weights --save-recon --set --aug-set --adv` |
| `direct_classifier.py` | bộ phân loại trực tiếp (EEG + hai luồng → A/B), phản đối xứng, có đối chứng chống đi tắt và chế độ `--pretrain-spk` |
| `pretrain_sparrkulee.py` | pretrain decoder trên SparrKULee |
| `score.py` | chấm một thí nghiệm: chuyển chú ý giả, HMM, đóng nhãn, bộ chấm chính thức; trọng số LDA |
| `summarize.py` | gom `results/*.json` vào bảng tổng hợp |
| `hp_summary.py` | bảng dò siêu tham số so với mốc |
| `integrators.py`, `msm.py`, `reliability.py`, `tune_pstay.py`, `decision_targets.py`, `rescore_weights.py` | các thí nghiệm về khâu quyết định: bộ tích hợp, mô hình Markov chuyển chế độ, evidence có trọng số độ tin cậy, p_stay, trọng số mục tiêu |

**Ghép nhiều mô hình**

| Script | Việc làm |
|---|---|
| `fuse_general.py` | **ghép** một tập decoder và một tập bộ phân loại bất kỳ rồi chấm (`--dec --clf --a --pstay --name`) |
| `fuse_evidence.py` | căn thời gian decoder – bộ phân loại (`DEC_OFFSET`), ghép bằng LDA |
| `fuse_mix.py`, `fuse_learn.py`, `fuse_ensemble.py` | ghép theo tỉ lệ, học trọng số bằng loss chuỗi, trung bình seed |
| `multiscale_decoder.py` | evidence của decoder trên cửa sổ dài hơn |
| `hmm_bank.py` | bộ HMM nhiều tốc độ chuyển |
| `adapt_within_trial.py` | tự thích nghi trong trial bằng nhãn giả |

**Chuyển chú ý thật**

| Script | Việc làm |
|---|---|
| `eval_external.py` | train decoder trên 5 dataset, chạy và chấm trên AASD / Carta |
| `eval_external_clf.py` | như trên cho bộ phân loại |
| `fuse_external.py` | ghép và chấm trên dữ liệu thật |
| `aasd_synthetic.py` | cùng evidence AASD, chấm với nhãn thật so với chuyển chú ý giả |

**Kiểm tra tuân thủ**

| Script | Việc làm |
|---|---|
| `leakage_test.py` | **kiểm tra lookahead đầu-cuối**: thay đầu vào từ τ trở đi bằng nhiễu và đo mẫu nhãn sớm nhất bị đổi; có bốn đối chứng âm |

**Hàng chờ và vận hành**

| Script | Việc làm |
|---|---|
| `runners/jobqueue.py` | hàng chờ job có kiểm tra tải, GPU, RAM (`add`, `status`, `run`) |
| `runners/launch.sh`, `run_queue.sh`, `status.sh` | khởi động hàng chờ trong tmux; chạy một danh sách thí nghiệm; xem tiến độ |
| `runners/sparrkulee_chain.sh`, `sparrkulee_chain_adt.sh` | chuỗi tải → chuyển đổi → pretrain SparrKULee |
| `runners/run_*.sh` | các lô thí nghiệm cũ (tăng cường, cửa sổ, FFT, warm-up, tín hiệu, độ tin cậy, ...) |
| `debug/ensemble_pstay.py`, `debug/vlaai_ablation.py` | chẩn đoán |

### 6.4 Chuyển đổi dữ liệu ngoài (`experiments/external_data/`)

| Script | Việc làm |
|---|---|
| `download.sh` | tải các dataset ngoài (3 luồng song song, tiếp tục được) |
| `Fuglsang2020/stage_a_extract.py` | **chạy bằng python hệ thống** (cần `mne`): BIDS → trial `.npz` ở `stage_a/` |
| `Fuglsang2020/stage_b_convert.py <prep>` | `stage_a` → cache của benchmark với tiền xử lý đã chọn |
| `Fuglsang2020/build_glimpse_fug.py` | tín hiệu mục tiêu cho Fuglsang |
| `SparrKULee/download_sparrkulee.py`, `convert_sparrkulee.py`, `build_glimpse_spk.py` | tải (cần tài khoản), chuyển đổi, tín hiệu mục tiêu cho pretrain |
| `AASD/convert_aasd.py`, `Carta2026/convert_carta.py`, `Broderick2018/convert_broderick.py` | chuyển đổi từng dataset |
| `build_glimpse_ext.py` | tín hiệu `dom` cho AASD và Carta từ âm thanh |
| `derive_prep.py <prep>` | tạo bản căn chỉnh không mang trạng thái cho AASD và Carta từ cache `mat` |
| `experiments/envelope_reverse/reverse.py` | dựng lại cách ban tổ chức tính envelope (gammatone, mũ 0,6) |

## 7. Luồng dữ liệu

```
data/cnd (.mat) ──tools/convert_cnd_to_superhuge.py──> data/superhuge (.npy + metadata.pkl)
        │                                                       │
        └─ reports/eda_full/scripts/b1_cnd_extract.py ──> cache/cnd/<key>.npz (nhãn từng mẫu)
                                                                │
data/superhuge ──prepare_data.py──> decoder_lodo/cache/<prep>/<key>.npz   (+ build_glimpse.py ──> cache/glimpse*/)
dữ liệu ngoài ──external_data/*/convert*.py──> external_data/*/cache/<prep>/

cache/<prep> ──run_experiment.py / direct_classifier.py──> folds/<tn>/<DS>.pkl + results/<tn>.json
folds/…      ──fuse_general.py──────────────────────────> results/research/fuse_general.csv + logs/fuse_*.log
models/…     ──eval_external*.py, fuse_external.py──────> results/research/*_evidence_*.pkl, fuse_external.csv
(mọi lần chấm dùng score.py + reports/eda_full/scripts/{scorer.py, e1_switch.py})
```

Với bản nộp cuối còn thiếu: script train mô hình cuối trên cả 5 dataset và script suy luận đọc dữ liệu test, chạy mô hình
nhân quả, xuất CSV nhãn 128 Hz theo định dạng ở mục 3.4.
