# Thí nghiệm STFT + cây quyết định (XGBoost) cho Track 03

Ngày 2026-10-15. File này giải thích thí nghiệm làm gì, từng bước ra sao, vì sao làm như vậy, và kết quả nói lên điều gì.

## Tóm tắt

- **Bài toán:** với mỗi cửa sổ EEG 5 giây, đoán còn bao nhiêu giây nữa thì tới N2 đầu tiên (tối đa 600 s). Điểm là W-bMAE, thấp hơn là tốt hơn.
- **Cách làm:**
  - Dùng STFT để biến mỗi cửa sổ thành các con số mô tả tần số và diễn biến theo thời gian (feature).
  - Thêm các feature tóm tắt những cửa sổ trước đó trong cùng bản ghi. Chỉ dùng quá khứ, không dùng tương lai.
  - Cho một model cây (XGBoost, chạy trên GPU) học từ các con số đó.
- **Kết quả tốt nhất:** W-bMAE **46.7 ± 1.5 s** khi đánh giá chéo 5 fold theo người, chấm hai nhóm seen/unseen như bộ chấm sealed. Mốc "luôn đoán 35 s" đạt 62.1.
- **Điều học được:**
  - Thêm thông tin từ các cửa sổ trước giúp rõ ràng (−3.7 s).
  - Thời gian đã trôi (elapsed time) gần như không giúp gì thêm.
  - Ở 40 giây cuối trước N2, model vẫn kém hằng số.

Các thuật ngữ trong file này được giải thích ở [mục 11](#11-bảng-thuật-ngữ).

## 1. Code ở đâu, chạy thế nào

| File | Nội dung |
|---|---|
| [run_stft_tree.py](run_stft_tree.py) | toàn bộ thí nghiệm: đọc dữ liệu, trích feature, train, chấm điểm, viết báo cáo |
| [run.sh](run.sh) | lệnh chạy đầy đủ (5 fold × 3 seed), ghi log vào `results/run.log` |
| `cache/` | feature đã trích (`base_features.npz`, `windows.csv`, `recordings.csv`); lần sau không phải trích lại |
| [results/summary.md](results/summary.md) | bảng kết quả, tự sinh khi chạy xong |
| `results/scores_by_fold.csv` | điểm theo từng fold, seed, biến thể, nhóm |
| `results/scores_by_recording.csv` | điểm của **từng bản ghi**, dùng để so cặp giữa các biến thể |
| `results/importance.json` | độ quan trọng của từng feature |
| `results_smoke/` | kết quả của lần chạy thử nhanh (`--smoke`), chỉ để kiểm tra code, không dùng làm kết quả |

Chạy trong tmux để có thể ngắt kết nối server:

```bash
tmux new-session -d -s stft_tree "bash /root/disk_3tb/Neural_Interfaces_2026_Track_3_Sleep_Onset/experiments/stft_tree/run.sh; exec bash"
tmux attach -t stft_tree            # xem; thoát mà không dừng: Ctrl-b rồi d
tail -f experiments/stft_tree/results/run.log
```

Các tùy chọn:

- `--smoke`: 2 fold, rất ít cây, khoảng 1.5 phút. Dùng để kiểm tra code chạy được.
- `--seeds 0 1 2`: các seed cần chạy.
- `--variants freq freq_ctx`: chỉ chạy một số biến thể.
- `--skip-cv`: chỉ chạy split công khai.

Thời gian chạy:

- Trích feature lần đầu: khoảng 30 s cho 540 bản ghi.
- Lượt đầy đủ: 9.6 phút, mỗi lần train khoảng 5-17 s trên V100.

Môi trường: python của conda (`/root/miniconda3/bin/python`), xgboost 3.1.2, chạy với `device="cuda"`. Nếu GPU không dùng được, script tự chuyển sang CPU và in cảnh báo trong log.

## 2. Dữ liệu và nhãn

- **Nguồn:** 540 bản ghi Muse (NEMAR nm000287), 4 kênh TP9, AF7, AF8, TP10, 128 Hz, đọc trực tiếp từ file BrainVision gốc trong `2026-competition/tracks/sleep_onset/data/`.
- **Cửa sổ:**
  - Mỗi bản ghi được cắt thành các cửa sổ 5 s (640 mẫu) liền nhau, không chồng lên nhau, bắt đầu từ đầu bản ghi.
  - Chỉ giữ các cửa sổ kết thúc trước hoặc đúng lúc N2, vì đó đúng là những cửa sổ bộ chấm đưa vào model. Phần 300 s sau N2 có trong file nhưng không bao giờ được chấm.
  - Tổng cộng **80,975 cửa sổ**.
- **Nhãn:** giống hệt neuralbench (`SleepOnsetTargetExtractor`):

  y = clip(thời điểm N2 − thời điểm kết thúc cửa sổ, 0, 600)

- **Không dùng** độ dài file, số mẫu hay thống kê của cả bản ghi. Độ dài file làm lộ đáp án: độ dài = onset + 300 s ở cả 540 bản ghi.

## 3. Bước 1: trích feature từ mỗi cửa sổ bằng STFT (217 feature)

### STFT là gì, dùng thế nào ở đây

FFT cho biết một đoạn tín hiệu có những tần số nào. STFT cắt đoạn tín hiệu thành nhiều khúc ngắn rồi FFT từng khúc, nên cho biết tần số nào xuất hiện vào lúc nào.

Với mỗi cửa sổ 5 s và mỗi kênh:

1. Trừ giá trị trung bình của cửa sổ, để bỏ độ lệch nền.
2. Cắt thành **7 khúc 2 s** (256 mẫu), mỗi khúc cách nhau 0.5 s, nhân cửa sổ Hann để làm mềm hai đầu.
3. FFT từng khúc, được công suất theo tần số với độ phân giải 0.5 Hz (từ 0 đến 64 Hz).
4. Có hai cách dùng 7 khúc này:
   - **Lấy trung bình** 7 khúc thành một phổ ít nhiễu (phương pháp Welch). Phần lớn feature tần số tính từ phổ này.
   - **Xem 7 khúc thay đổi ra sao** trong 5 s. Đây là các feature "thời gian trong cửa sổ".

Đây đúng là phép biến đổi mà nhánh phổ của CNN+GRU đang dùng (`torch.stft`, n_fft 256, hop 64). Ở đây ta tự tính feature thay vì để mạng nơ-ron tự học.

### Danh sách feature

Mỗi feature theo kênh được tính cho cả 4 kênh.

| Nhóm | Feature | Số lượng | Vì sao (theo EDA) |
|---|---|---|---|
| Công suất theo băng | log công suất delta 0.5-4, theta 4-8, alpha 8-11, sigma 11-15, beta 15-30, gamma 30-45 Hz; tổng 0.5-45 Hz | 7 × 4 | công suất giảm dần khi tới gần N2, mạnh nhất ở beta, gamma, alpha |
| Công suất tương đối | công suất mỗi băng chia cho tổng | 6 × 4 | so sánh được giữa người có biên độ khác nhau |
| Tỉ số | theta/alpha, sigma/beta, delta/beta | 3 × 4 | các feature "đến muộn", thay đổi trong 1.5-2.5 phút cuối |
| Hình dạng phổ | entropy phổ, SEF95, SEF50 (tần số chứa 95% và 50% công suất), độ dốc 1/f, sigma residual, tần số đỉnh alpha | 6 × 4 | 1/f slope và sigma residual là dấu hiệu sắp vào N2 |
| Thời gian trong cửa sổ | độ lệch chuẩn qua 7 khúc của log delta, alpha, beta, gamma và tổng | 5 × 4 | alpha bật tắt, artifact ngắn |
| Miền thời gian | log biên độ (SD), log line length, log biên độ lớn nhất, tỉ lệ mẫu chạm 780 µV | 4 × 4 | artifact là tín hiệu của trạng thái thức |
| Chất lượng | số kênh hỏng (biên độ > 200 µV hoặc RMS 30-45 Hz > 5 µV) | 1 | tỉ lệ kênh hỏng giảm từ 31% xuống 3.5% khi tới gần N2 |
| Tương quan kênh | TP9-TP10, AF7-AF8, TP9-AF7, AF8-TP10 | 4 | AF7-AF8 chứa chuyển động mắt ngang |
| Phổ thô | log công suất từng dải 1 Hz từ 1 đến 44 Hz, trung bình cặp thái dương (TP) và cặp trán (AF) | 44 × 2 | để cây tự tìm những dải tần mà các băng cố định bỏ sót |

Tổng: 124 + 1 + 4 + 88 = **217 feature**. Mỗi feature chỉ dùng 640 mẫu của chính cửa sổ đó.

## 4. Bước 2: feature ngữ cảnh từ các cửa sổ trước (210 feature)

Một cửa sổ 5 s đứng một mình rất nhiễu. EDA cho thấy phải nhìn vài phút mới thấy xu hướng.

**Chọn feature gốc:** 20 feature chính được lấy trung bình theo cặp kênh (TP và AF), cộng thêm số kênh hỏng và tương quan AF7-AF8, được 42 feature gốc. 20 feature chính gồm:

- công suất tuyệt đối và tương đối của 6 băng;
- 3 tỉ số;
- 1/f slope, sigma residual, entropy;
- log biên độ, tỉ lệ clip.

**Tính 5 dạng tóm tắt quá khứ** cho mỗi feature gốc, trong từng bản ghi, theo thứ tự thời gian. Tổng là 42 × 5 = **210 feature**.

| Dạng | Công thức | Ý nghĩa |
|---|---|---|
| EMA 30 s | m_t = a·x_t + (1 − a)·m_(t−1), với a = 1 − e^(−5/30) ≈ 0.15 | trung bình trượt ngắn: "nửa phút vừa qua thế nào" |
| EMA 120 s | a ≈ 0.041 | "2 phút vừa qua" |
| EMA 300 s | a ≈ 0.016 | "5 phút vừa qua" |
| EMA 30 s − running mean | running mean = trung bình từ đầu bản ghi tới hiện tại | "bây giờ khác mức bình thường của chính người này đêm nay bao nhiêu" (giảm khác biệt giữa người) |
| EMA 30 s − EMA 300 s | | "xu hướng đang lên hay xuống" |

Mọi EMA bắt đầu bằng giá trị của cửa sổ đầu tiên.

**Kiểm tra causal tự động:** mỗi lần chạy, script lấy 5 bản ghi ngẫu nhiên, cắt mỗi bản ghi ở một điểm ngẫu nhiên, rồi tính lại feature ngữ cảnh. Kết quả phải trùng hệt với phần đầu của feature tính trên cả bản ghi. Nếu không trùng, script dừng ngay. Kết quả là 5/5 trùng, tức feature không dùng tương lai.

**Biến thể có elapsed time:** thêm một feature là số giây từ đầu bản ghi đến cuối cửa sổ. FAQ của cuộc thi cho phép dùng thông tin này.

## 5. Bước 3: model XGBoost

### Model cây là gì

- **Một cây quyết định** là chuỗi câu hỏi có/không, ví dụ "sigma/beta EMA 30 s > 0.2? Nếu có thì 1/f slope < −1.5?". Đi hết các câu hỏi thì tới một lá, mỗi lá cho một con số dự đoán.
- **Gradient boosting** xây hàng trăm cây nhỏ nối tiếp nhau. Mỗi cây mới cố sửa phần sai còn lại của các cây trước.
- **Ưu điểm:** nhanh, không cần chuẩn hoá feature, và chịu được feature thừa.

### Loss khớp với metric

W-bMAE tính sai số trung bình **trong từng bin** của từng bản ghi (bin 0-40, 40-90, 90-300, 300-600 s), nhân trọng số 10/5/3/1, rồi lấy trung bình qua các bản ghi. Để model học đúng mục tiêu này:

- Dùng loss là **sai số tuyệt đối** (`reg:absoluteerror`).
- Mỗi cửa sổ có một **trọng số** = trọng số bin / tổng trọng số các bin có mặt trong bản ghi / số cửa sổ của bản ghi trong bin đó.

Ví dụ: một bản ghi có 8 / 10 / 40 / 80 cửa sổ trong 4 bin. Tổng trọng số bin là 10 + 5 + 3 + 1 = 19, nên trọng số mỗi cửa sổ là:

- bin 0-40: 10/19/8;
- bin 40-90: 5/19/10;
- bin 90-300: 3/19/40;
- bin 300-600: 1/19/80.

Với cách đặt này, tổng "trọng số × sai số" của bản ghi đúng bằng W-bMAE của nó. Một cửa sổ ở 40 giây cuối nặng khoảng 100 lần một cửa sổ còn xa.

Điểm xuất phát của model là **trung vị có trọng số** của nhãn, tức khoảng 35 s. Đây cũng chính là mốc hằng số. Dự đoán được cắt vào khoảng [0, 600].

### Huấn luyện

| Tham số | Giá trị |
|---|---|
| learning rate | 0.05 |
| độ sâu cây | 6 |
| min_child_weight | 20 (trọng số đã được đưa về trung bình 1 mỗi cửa sổ) |
| subsample / colsample | 0.8 / 0.5 |
| số cây | tối đa 4000, dừng sớm sau 200 cây không cải thiện |

Quy trình chọn số cây:

1. Tách 15% số người trong tập train ra làm **tập kiểm tra nội bộ**.
2. Train và dừng khi điểm trên tập nội bộ thôi giảm (early stopping).
3. Train lại trên **toàn bộ tập train** với đúng số cây tìm được.

Tập giữ ngoài để chấm điểm không bao giờ được dùng để chọn bất cứ thứ gì. Các tham số trên chưa được tinh chỉnh.

## 6. Bước 4: cách chấm điểm

### Bốn biến thể

| Tên | Feature dùng |
|---|---|
| `const` | không gì cả: luôn đoán trung vị có trọng số của tập train (35 s) |
| `freq` | 217 feature của cửa sổ hiện tại |
| `freq_ctx` | + 210 feature ngữ cảnh |
| `freq_ctx_elapsed` | + elapsed time |

### Đánh giá chéo 5 fold theo người, mô phỏng bộ chấm sealed

Bộ chấm sealed tính điểm riêng cho hai nhóm rồi lấy trung bình:

- **seen:** đêm mới của người đã có trong train;
- **unseen:** người hoàn toàn mới.

Để mô phỏng điều đó:

1. Chia ngẫu nhiên 203 người thành 5 phần, khoảng 40 người mỗi phần. Ở fold k, mọi đêm của phần k bị giữ ngoài, tạo thành nhóm **unseen**.
2. Với 153 người có từ 2 đêm trở lên, bốc ngẫu nhiên 1 đêm và gán vào một fold khác fold unseen của họ. Ở fold đó, đêm này bị giữ ngoài còn các đêm khác của họ vẫn ở trong train, tạo thành nhóm **seen**.
3. Điểm của fold = (W-bMAE nhóm seen + W-bMAE nhóm unseen) / 2.

| Fold | Bản ghi train | Seen | Unseen (người) |
|---|---|---|---|
| 0 | 403 | 27 | 110 (41) |
| 1 | 414 | 29 | 97 (41) |
| 2 | 386 | 39 | 115 (41) |
| 3 | 393 | 33 | 114 (40) |
| 4 | 411 | 25 | 104 (40) |

Qua 5 fold, mỗi bản ghi đều được chấm ở nhóm unseen đúng một lần, và 153 bản ghi được chấm thêm ở nhóm seen. Cách chia fold được cố định (seed 0), nên mọi biến thể chấm trên đúng cùng những bản ghi. Mỗi biến thể chạy 3 seed (0, 1, 2); seed thay đổi tập kiểm tra nội bộ và phần ngẫu nhiên khi chọn mẫu của XGBoost.

Mỗi lần chấm dùng **hàm `binned_mae` chính thức** của repo cuộc thi (`benchmark_utils/metrics.py`), nên cách chia bin và trọng số giống hệt Codabench.

### So cặp trên từng bản ghi

Muốn biết biến thể B có thật sự tốt hơn A không, ta lấy hiệu điểm của B và A **trên cùng một bản ghi** (cùng fold, cùng seed), rồi tính trung bình và sai số chuẩn của các hiệu đó.

Độ khó riêng của từng đêm bị triệt tiêu trong phép trừ, nên phép so này nhạy hơn nhiều so với so điểm trung bình. Mỗi phép so có 2079 cặp = 3 seed × (540 bản ghi unseen + 153 bản ghi seen).

### Bài cắt đầu bản ghi

Bài này đo model dựa vào "đồng hồ" bao nhiêu:

- Với mỗi bản ghi giữ ngoài, bỏ ngẫu nhiên 0-50% số cửa sổ đầu.
- Bản ghi khi đó bắt đầu từ chỗ cắt: EMA, running mean và elapsed time đều tính lại từ đó.

Nếu một model sụt nhiều ở bài này, nghĩa là nó đang dựa vào việc đếm thời gian từ đầu bản ghi. Điều đó rủi ro nếu bộ sealed được cắt khác dữ liệu công khai.

Tập cửa sổ của bài này khác tập gốc (ít cửa sổ xa hơn), nên chỉ so các biến thể với nhau trong cùng bài, không so với điểm của tập gốc.

### Split công khai

Train trên 500 bản ghi train công khai, chấm trên 40 bản ghi test, giống warm-up Codabench. Tập này chỉ có nhóm seen và sai số chuẩn khoảng 6-7 s, nên chỉ dùng để đối chiếu.

## 7. Kết quả

### CV 5 fold × 3 seed

| Biến thể | Seen | Unseen | **Macro** (mean ± SD qua fold) | Khi cắt đầu bản ghi |
|---|---|---|---|---|
| const | 62.2 | 62.0 | **62.1 ± 0.9** | |
| freq | 50.7 | 50.7 | **50.7 ± 1.0** | 48.7 |
| freq_ctx | 46.1 | 47.3 | **46.7 ± 1.5** | 45.2 |
| freq_ctx_elapsed | 45.9 | 47.2 | **46.5 ± 1.2** | 45.4 |

So cặp trên từng bản ghi (âm nghĩa là biến thể sau tốt hơn):

| So sánh | Hiệu ± SE | Đọc là |
|---|---|---|
| freq − const | −11.36 ± 0.23 s | feature STFT học được thật |
| freq_ctx − freq | −3.73 ± 0.30 s | ngữ cảnh từ các cửa sổ trước giúp rõ ràng |
| freq_ctx_elapsed − freq_ctx | −0.11 ± 0.09 s | elapsed time gần như không thêm gì |

MAE theo bin, tính trên mọi cửa sổ giữ ngoài:

| Biến thể | 0-40 s | 40-90 s | 90-300 s | 300-600 s |
|---|---|---|---|---|
| const | **17.2** | **27.9** | 156.6 | 482.4 |
| freq | 21.8 | 30.2 | 103.0 | 371.2 |
| freq_ctx | 21.8 | 29.0 | 88.5 | 341.2 |
| freq_ctx_elapsed | 22.1 | 29.4 | **87.2** | **337.5** |

### Split công khai (40 bản ghi test)

| Biến thể | W-bMAE |
|---|---|
| const | 60.7 |
| freq | 51.7 |
| freq_ctx | 50.9 |
| freq_ctx_elapsed | 51.2 |

Các mốc cũ trên cùng 40 bản ghi: boosted tree cũ 52.5, CNN+GRU 50.4 và 55.8. Với sai số chuẩn khoảng 6-7 s, các con số này không phân biệt được với nhau.

### Feature quan trọng nhất

- **Biến thể `freq`:** 1/f slope ở TP10 và TP9, sigma/beta, theta/alpha, delta/beta, công suất 2-3 Hz ở kênh thái dương.
- **Biến thể `freq_ctx`:** gần như toàn bộ top 20 là feature ngữ cảnh, nhất là EMA 30 s và "EMA 30 s − running mean" của delta tương đối, sigma/beta, 1/f slope, theta/alpha ở kênh thái dương.

Cả hai danh sách khớp với dự đoán của EDA: các feature "đến muộn", ở dạng tương đối theo bản ghi.

## 8. Ý nghĩa

1. **Tóm tắt các cửa sổ trước là bước có giá trị nhất** (−3.7 s). Phần lợi nằm ở các bin xa: MAE ở 90-300 s giảm từ 103 xuống 88.
2. **Model không cần đồng hồ.** Elapsed time chỉ thêm −0.1 s, và không làm model sụt khi bị cắt đầu bản ghi. Model dựa vào EEG chứ không dựa vào cách bộ dữ liệu được cắt, nên ít rủi ro hơn khi lên tập sealed.
3. **Điểm yếu lớn nhất là 40 giây cuối.**
   - Ở bin 0-40 s (khoảng một nửa trọng số metric), model sai 21.8 s, trong khi luôn đoán 35 s chỉ sai 17.2 s.
   - Nguyên nhân: model không chắc chắn phân biệt được "còn 20 s" với "còn 200 s", nên đôi khi đoán xa và bị phạt nặng.
   - CNN+GRU cũng gặp đúng vấn đề này.
4. **Model học rất nhanh rồi bắt đầu overfit.** Early stopping chỉ giữ 27-306 cây (thường dưới 120). Chỉnh tham số cây khó đem lại nhiều; cần thay đổi cách dự đoán.

## 9. Hạn chế

- **Chưa phải bài nộp.** Muốn nộp phải viết lại phần trích feature và EMA thành một solver chạy từng cửa sổ (`predict` giữ trạng thái EMA, `reset_state` khi sang bản ghi mới). Cũng chưa kiểm tra máy chấm Codabench có cài xgboost hay không.
- **Không lọc tín hiệu.** Feature tính trên tín hiệu thô sau khi chỉ trừ trung bình theo cửa sổ. Các thí nghiệm lọc ở [PREPROCESS_EXPERIMENTS.md](../../PREPROCESS_EXPERIMENTS.md) có thể chạy lại bằng chính harness này.
- **Tham số XGBoost chưa tinh chỉnh**, và chỉ có một cách chia fold.
- **Nhóm seen trong CV nhỏ** (153 bản ghi, 25-39 mỗi fold), nên điểm seen dao động nhiều hơn điểm unseen.

## 10. Bước tiếp theo đề xuất

1. **Sửa bin 0-40 s bằng head phân phối:**
   - Train thêm một classifier đoán xác suất cho từng khoảng thời gian (hoặc hazard).
   - Giải mã bằng weighted median theo trọng số metric.
   - Khi model không chắc, dự đoán tự kéo về khoảng 35 s như hằng số.
2. **Sàng lọc nhanh các thí nghiệm tiền xử lý** E1 (lọc), E6 (input tương đối), E7 (sửa phổ), E9 (độ phân giải STFT) bằng harness này. Mỗi cấu hình khoảng 10 phút.
3. **Nếu giữ hướng cây:** viết solver streaming và kiểm tra thư viện có sẵn trên máy chấm.

## 11. Bảng thuật ngữ

Các thuật ngữ được gom theo nhóm. Cột cuối cho biết thuật ngữ xuất hiện ở đâu trong thí nghiệm này.

### 11.1 Bài toán và cách chấm điểm

| Thuật ngữ | Nghĩa | Trong thí nghiệm này |
|---|---|---|
| Cửa sổ (window) | đoạn tín hiệu 5 s (640 mẫu ở 128 Hz); model nhận từng cửa sổ một | 80,975 cửa sổ trước N2 |
| N2 | giai đoạn ngủ nhẹ thứ hai, đánh dấu bằng các spindle và K-complex; "N2 đầu tiên" là mốc ngủ thật sự | điểm cần dự đoán thời gian tới |
| Onset | thời điểm N2 đầu tiên xuất hiện, tính bằng giây từ đầu bản ghi | median 690 s ở bộ train |
| Target, nhãn (y) | số giây từ cuối cửa sổ tới onset, cắt vào [0, 600] | `y = clip(onset − thời điểm cuối cửa sổ, 0, 600)` |
| Trần 600 s (cap) | mọi giá trị lớn hơn 600 được ghi thành 600 | 30.2% cửa sổ nằm ở đúng 600 |
| Bin | nhóm theo target: 0-40, 40-90, 90-300, 300-600 s | trọng số 10, 5, 3, 1 |
| MAE | sai số tuyệt đối trung bình, tức trung bình của giá trị tuyệt đối (dự đoán − thật) | loss của model |
| bMAE | MAE tính riêng trong từng bin rồi lấy trung bình các bin | |
| W-bMAE | bMAE có trọng số bin 10/5/3/1; tính trong từng bản ghi rồi lấy trung bình qua bản ghi; thấp hơn là tốt hơn | điểm chính, tính bằng giây |
| Hằng số (const) | model luôn đoán một con số cố định, không nhìn EEG; con số tối ưu là trung vị có trọng số, khoảng 35 s | mốc tối thiểu, 62.1 s trong CV |
| Trung vị có trọng số | giá trị mà tổng trọng số ở hai phía bằng nhau; với trọng số của metric nó tối thiểu hoá W-bMAE | điểm xuất phát của XGBoost |
| Warm-up | giai đoạn thử: chấm trên 40 bản ghi test công khai, chỉ mang tính tham khảo | split công khai |
| Sealed | giai đoạn chấm chính thức trên dữ liệu riêng chưa công bố | cố gắng mô phỏng bằng CV |
| Seen | đêm mới của người đã có trong dữ liệu train | nhóm điểm 1 |
| Unseen | người hoàn toàn mới, không có đêm nào trong train | nhóm điểm 2 |
| Macro-average | lấy trung bình của điểm seen và điểm unseen, mỗi nhóm nặng bằng nhau | điểm xếp hạng sealed |
| ICC | tỉ lệ sự khác nhau giữa các đêm được giải thích bởi "đó là ai"; từ 0 (người nào cũng như nhau) tới 1 (mọi đêm của một người giống hệt nhau) | ICC của onset là 0.38 |
| Hazard | xác suất sự kiện xảy ra ngay lúc này, biết rằng chưa xảy ra | giải thích vì sao elapsed time dự đoán được |
| Elapsed time | số giây tính từ đầu bản ghi tới cửa sổ hiện tại | một feature phụ, biến thể `freq_ctx_elapsed` |
| Streaming | model nhận từng cửa sổ một theo thứ tự thời gian và phải trả lời ngay | cách chấm của Codabench |
| Causal (nhân quả) | chỉ dùng cửa sổ hiện tại và các cửa sổ trước, không dùng tương lai | mọi feature ngữ cảnh |
| `reset_state()` | hàm gọi khi sang bản ghi mới để xoá trạng thái đã tích luỹ | cần khi viết solver |
| Rò rỉ nhãn (leak) | thông tin để lộ đáp án, ví dụ độ dài file = onset + 300 s | không được dùng |

### 11.2 Tín hiệu và phổ

| Thuật ngữ | Nghĩa | Trong thí nghiệm này |
|---|---|---|
| EEG | điện não đồ, tín hiệu điện đo trên da đầu | 4 kênh Muse |
| TP9, TP10 | điện cực sau tai, vùng thái dương | được gộp thành cặp "TP" |
| AF7, AF8 | điện cực trán | được gộp thành cặp "AF" |
| Hz | số chu kỳ mỗi giây; 128 Hz là 128 mẫu mỗi giây | tần số lấy mẫu |
| µV | microvolt, đơn vị biên độ EEG | clip ở khoảng 780 µV |
| FFT | biến đổi cho biết tín hiệu chứa những tần số nào, nhưng không cho biết chúng xuất hiện lúc nào | thành phần của STFT |
| STFT | cắt tín hiệu thành nhiều khúc ngắn rồi FFT từng khúc, cho biết tần số nào xuất hiện vào lúc nào | 7 khúc 2 s mỗi cửa sổ 5 s |
| Cửa sổ Hann | hàm nhân làm mềm hai đầu mỗi khúc để không sinh tần số giả | dùng trong STFT |
| Welch | lấy trung bình phổ của nhiều khúc để giảm nhiễu | phổ trung bình 7 khúc |
| Công suất, PSD | độ mạnh của tín hiệu ở từng tần số | log công suất theo băng |
| Băng tần (band) | một khoảng tần số: delta 0.5-4, theta 4-8, alpha 8-11, sigma 11-15, beta 15-30, gamma 30-45 Hz | 6 băng |
| Delta | sóng chậm, mạnh khi ngủ sâu | |
| Theta | sóng chậm vừa, tăng lúc buồn ngủ | |
| Alpha | khoảng 8-11 Hz, mạnh khi nhắm mắt thư giãn, giảm dần khi buồn ngủ | |
| Sigma | 11-15 Hz, băng của spindle | |
| Beta, gamma | sóng nhanh, gắn với tỉnh táo và hoạt động cơ; giảm khi sắp ngủ | |
| Spindle | cụm sóng ngắn ở khoảng 11-15 Hz, đặc trưng của N2 | |
| Công suất tương đối | công suất của một băng chia cho tổng công suất 0.5-45 Hz | `rel_*` |
| Tỉ số băng | chia công suất hai băng, ví dụ sigma/beta, theta/alpha, delta/beta | các feature "đến muộn" |
| Log | lấy logarit để các con số có độ lớn khác nhau đủ gần nhau | `log_*` |
| 1/f slope (aperiodic) | độ dốc của phổ khi vẽ theo thang log; khi buồn ngủ phổ dốc hơn | `aper_slope` |
| Sigma residual | phần sigma nhô lên so với đường 1/f | `sigma_resid` |
| Entropy phổ | phổ trải đều trên nhiều tần số hay tập trung ở vài tần số | `spec_entropy` |
| SEF95, SEF50 | tần số mà dưới đó chứa 95% hoặc 50% công suất | |
| Line length | tổng độ lệch giữa các mẫu liên tiếp; tăng theo biên độ và tần số | `log_linelen` |
| Clipping | tín hiệu chạm trần của ADC (khoảng 780 µV) nên bị cắt phẳng | `clip_frac` |
| Artifact | thành phần không phải EEG (cử động, chớp mắt, tiếp xúc kém) | tín hiệu của trạng thái thức |
| Kênh hỏng (BAD) | kênh có biên độ lớn nhất > 200 µV hoặc RMS 30-45 Hz > 5 µV | `n_bad` |
| Alpha blocking | alpha giảm khi người đó mở mắt hoặc tập trung | |
| Trôi nền | mức trung bình của tín hiệu dịch chậm, dưới khoảng 0.5 Hz, do mồ hôi hoặc điện cực xê dịch | chưa lọc, thử ở E1 |
| High-pass, low-pass, band-pass | bộ lọc giữ tần số cao, thấp, hoặc một dải | thí nghiệm E1 |
| IIR có trạng thái | bộ lọc causal mang trạng thái từ cửa sổ này sang cửa sổ sau | cách lọc hợp lệ khi streaming |
| Notch | bộ lọc cắt hẹp quanh 50 hoặc 60 Hz (nhiễu điện lưới) | thay bằng dừng ở 45 Hz |

### 11.3 Feature và model

| Thuật ngữ | Nghĩa | Trong thí nghiệm này |
|---|---|---|
| Feature | một con số mô tả cửa sổ, đưa vào model | 217 theo cửa sổ + 210 ngữ cảnh |
| Ngữ cảnh | feature tóm tắt các cửa sổ trước đó trong cùng bản ghi | EMA, running mean |
| EMA | trung bình trượt mũ: cửa sổ mới có trọng số lớn, cửa sổ cũ phai dần; "30 s" là hằng số thời gian | 30, 120, 300 s |
| Running mean | trung bình từ đầu bản ghi tới hiện tại | dùng để tính "EMA − running mean" |
| Cây quyết định | chuỗi câu hỏi có/không dẫn tới một con số dự đoán ở lá | |
| Gradient boosting | xây nhiều cây nối tiếp, mỗi cây sửa sai số còn lại của các cây trước | |
| XGBoost | thư viện gradient boosting nhanh, chạy được trên GPU | model của thí nghiệm |
| Learning rate | mỗi cây mới được cộng vào với trọng số bao nhiêu; nhỏ thì học chậm nhưng ổn định | 0.05 |
| Độ sâu cây (max_depth) | số câu hỏi tối đa trên một đường đi | 6 |
| min_child_weight | tổng trọng số tối thiểu của một lá; càng lớn càng khó overfit | 20 |
| subsample, colsample | tỉ lệ cửa sổ và tỉ lệ feature được dùng cho mỗi cây | 0.8 và 0.5 |
| Sample weight | trọng số của từng cửa sổ trong loss | trọng số đúng bằng W-bMAE |
| `reg:absoluteerror` | loss là sai số tuyệt đối (tối ưu cho MAE) | |
| Early stopping | dừng thêm cây khi điểm trên tập kiểm tra không cải thiện nữa | 27-306 cây |
| Overfit | model học thuộc dữ liệu train nên điểm trên dữ liệu mới tệ hơn | |
| Độ quan trọng (total gain) | tổng mức giảm sai số mà một feature đem lại khắp các cây | `importance.json` |
| GPU, CUDA | card đồ hoạ dùng để train nhanh; `device="cuda"` | V100 |

### 11.4 Đánh giá và quy trình

| Thuật ngữ | Nghĩa | Trong thí nghiệm này |
|---|---|---|
| CV (cross-validation) | chia dữ liệu thành nhiều phần, lần lượt giữ một phần ra chấm, phần còn lại để train | 5 fold |
| Fold | một lần chia trong CV | 5 fold |
| Chia theo người | mọi đêm của một người nằm cùng một phía, tránh lộ thông tin giữa train và test | |
| Seed | số khởi tạo cho phần ngẫu nhiên; đổi seed để đo mức dao động | 0, 1, 2 |
| Tập kiểm tra nội bộ | phần train được tách riêng (15% số người) để chọn số cây | không phải tập chấm |
| So cặp | lấy hiệu điểm của hai biến thể trên cùng một bản ghi rồi trung bình | triệt tiêu độ khó của từng đêm |
| SD (độ lệch chuẩn) | mức dao động của các giá trị quanh trung bình | "± SD qua fold" |
| SE (sai số chuẩn) | độ bất định của giá trị trung bình, bằng SD chia căn bậc hai của số mẫu | "± SE" ở so cặp |
| Biến thể | một cấu hình feature: `const`, `freq`, `freq_ctx`, `freq_ctx_elapsed` | |
| Bài cắt đầu bản ghi | bỏ ngẫu nhiên 0-50% số cửa sổ đầu để đo model dựa vào đồng hồ bao nhiêu | cột "Khi cắt đầu bản ghi" |
| Smoke test | chạy thử rất nhanh để chắc code không lỗi, kết quả không dùng | `--smoke` |
| Cache | kết quả trích feature được lưu lại để lần sau không phải tính lại | `cache/` |
| tmux | công cụ giữ chương trình chạy khi ngắt kết nối server | session `stft_tree` |
