# EEG-sAAD dataset audit starter

## Mục tiêu
Bộ code này tạo **bản đồ cấu trúc dữ liệu** cho 5 dataset trước khi thiết kế preprocessing/model. Nó chỉ đọc dữ liệu, không lọc EEG, không resample, không ghi đè file nguồn.

## Cấu trúc nguồn theo thông tin hiện có

```text
/root/disk_3tb/EEG-sAAD-Grand-Challenge-Training-Dataset/data/cnd/
├── AVGCAAD2024/
├── DTU2018/
├── KUL2016/
├── KUL_AAD_UltraHD2021/
└── USTC2026/
    ├── dataCND/
    ├── chanInfoBiosemi64.mat
    ├── preprocessCND.m
    └── removeBadChannels.m
```

Các file `dataStim*.mat`, `pre_dataStim*.mat`, `dataSub*.mat`,
`pre_dataSub*.mat` có thể nằm ở cấp dataset hoặc bên trong `dataCND`.
Script tìm đệ quy nên không yêu cầu chúng ở một vị trí cố định.

## 1. Cài dependencies

```bash
python -m pip install numpy scipy h5py
```

Không bắt buộc: `pandas`, `matplotlib`, `mne`. Giai đoạn audit hiện tại không cần MNE.

## 2. Chạy audit

```bash
python analyze_eeg_datasets.py \
  --root /root/disk_3tb/EEG-sAAD-Grand-Challenge-Training-Dataset/data/cnd \
  --out /root/disk_3tb/eeg-thao/preprocessing/audit \
  --max-load-mb 128
```

Nếu thư mục dataset có tên khác hoặc muốn audit một subset:

```bash
python analyze_eeg_datasets.py --root /path/to/cnd --out /path/to/output \
  --datasets AVGCAAD2024 DTU2018 KUL2016
```

## 3. Kết quả

- `audit/README_AUDIT.md`: báo cáo tổng quan dễ đọc.
- `audit/audit_report.json`: chi tiết cấu trúc, biến MATLAB, thống kê mẫu nhỏ.
- `audit/file_inventory.csv`: danh sách mọi file, extension, dung lượng.
- `audit/mat_files_index.json`: metadata từng file `.mat`.
- `audit/matlab_scripts_index.json`: function và các dòng MATLAB có liên quan đến load/filter/resample/rereference/events.

## 4. Cách đọc kết quả để quyết định preprocessing

Với mỗi file MATLAB, cần xác minh:

1. **Vai trò**: raw continuous EEG, EEG đã preprocess, stimulus envelope, event/trigger hay metadata.
2. **Shape**: xác định trục channel × time hay time × channel. Không đoán chỉ từ shape.
3. **Sampling rate**: tìm `fs`, `srate`, `samplingRate`, metadata tương đương.
4. **Channel**: số kênh, tên kênh, thứ tự kênh, reference, EOG/ECG/stim channels.
5. **Đơn vị**: Volt, microvolt hay đơn vị ADC. Không scale khi chưa xác nhận.
6. **Events**: onset, duration, trigger code, trial id, boundary/segment markers.
7. **Preprocessing history**: xem `preprocessCND.m`, `removeBadChannels.m` và các script gọi chúng.
8. **Stimulus alignment**: kiểm tra envelope và EEG cùng mốc thời gian chưa; sampling rate có khớp không; có latency/audio trigger không.

## 5. Nguyên tắc trước khi build model

- Không gộp thẳng 5 dataset trước khi chuẩn hóa schema.
- Không áp cùng một montage/channel mapping cho mọi dataset nếu chưa đối chiếu `chanInfo` và metadata từng bộ.
- Không resample chỉ dựa trên một sampling rate giả định.
- Không dùng `pre_dataSub` như raw data; đây có thể là dữ liệu đã qua xử lý.
- Tách train/validation/test theo **subject** (và cân nhắc dataset/site) để tránh leakage.
- Fit normalization, artifact thresholds và mọi phép biến đổi học từ dữ liệu chỉ trên training split.
- Với auditory attention decoding, xác định rõ attended stream/target labels; tên hai stream không tự cho biết stream nào được chú ý.

## 6. Ghi chú về `dataStim1.mat` đã xem trước đó

File này có struct `stim` với các trường `names`, `data`, `fs`, `condNames`,
`condIdxs`, `streamWav`. Trong bản đã kiểm tra:
- `fs = 128 Hz`;
- `data` có shape 2 × 6, mỗi phần tử là vector 76,800 mẫu (600 giây);
- hai envelope là `envelope_stream1` và `envelope_stream2`;
- `condIdxs = [1, 3, 4, 1, 3, 4]` ánh xạ vào `condNames`.

Đây là thông tin của **một file cụ thể**, không được mặc định đúng cho mọi dataset/trial. Hãy dùng report để xác minh tất cả các file khác.

## 7. Bước tiếp theo sau audit

Sau khi chạy xong, gửi lại `README_AUDIT.md`, `audit_report.json` (hoặc zip thư mục audit), cùng nội dung hai script MATLAB `preprocessCND.m` và `removeBadChannels.m`. Từ đó mới có thể viết preprocessing pipeline chính xác theo từng dataset và thiết kế schema thống nhất cho model.
