vn6142027/mpddf-eeg-fatigue-phase2-v1

MPD-DF 4-second EEG fatigue classifier (Phase 2 baseline)

• Author: Kao Zi Cing
• Model repository: https://huggingface.co/vn6142027/mpddf-eeg-fatigue-phase2-v1

This repository contains a frozen PyTorch baseline for binary driving-fatigue classification from 32-channel EEG in the MPD-DF dataset. It is intended for research, reproducibility, and method comparison—not medical diagnosis or a standalone vehicle-safety controller.

The Hugging Face README.md is the primary model card. Detailed reproduction instructions are in REPRODUCIBILITY.md.

Model summary

• Input: 4 seconds of 32-channel EEG at 125 Hz (32 x 500).
• Output: probability of fatigue and a binary prediction.
• Labels: 0 = wake; 1 = MPD-DF Fatigue1–Fatigue4.
• Excluded labels: MPD-DF artifact/unknown labels 8 and 9.
• Window stride: 2 seconds (50% overlap).
• Architecture: temporal convolutional network with GroupNorm and GELU.
• Selection metric: validation average precision.
• Frozen epoch: 8.
• Frozen threshold: 0.6780605316162109.
• Split: 35 train / 7 validation / 8 held-out test subjects.
• Seed: 20260817.

Frozen performance

Metric	Validation	Held-out test
Average precision	0.565	0.451
AUROC	0.750	0.747
Balanced accuracy	0.677	0.672
Macro-F1	0.687	0.628
Fatigue precision	0.557	0.377
Fatigue recall	0.467	0.638
Specificity	0.886	0.706
Subject-macro balanced accuracy	0.657	0.647
Subject-macro F1	0.644	0.546

Test evaluation was executed once after freezing the checkpoint and validation threshold. The report audit confirms that metrics recomputed from saved test predictions exactly match the recorded test results.

Preprocessing

1. Start from the official timestamp-aligned MPD-DF EEG arrays at 500 Hz.
2. Reconstruct the continuous signal for each subject.
3. Apply fourth-order zero-phase Butterworth 1–40 Hz band-pass filtering.
4. Resample the continuous signal from 500 Hz to 125 Hz.
5. Create 4-second windows with a 2-second stride.
6. Reject windows containing labels 8/9 or mixed binary states.
7. Remove the temporal mean independently for every channel and window.
8. Divide by train-only channel standard deviations and clip z-scores to ±8.

Filtering and resampling are performed before windowing to avoid artificial filter boundaries between one-second epochs.

Quick inference

Inference expects an HDF5 file generated by the included Phase-2 preparation script. Its eeg dataset must have shape (windows, 32, 500).

python infer.py `
  --input-h5 path\to\MPDDF_binary_EEG_4s_XX.h5 `
  --output-csv predictions.csv `
  --device cuda

The output includes the fatigue probability, frozen-threshold prediction, and source start second when available.

Reproducing the reported results

The repository includes:

• frozen checkpoint and model configuration;
• immutable subject split and training statistics;
• validation/test predictions and results;
• one-shot test evaluation lock;
• training history and publication figures;
• full preprocessing, training, evaluation, and reporting source code;
• exact training/reporting environments;
• SHA256 hashes for every released file.

Run python verify_release.py before reproduction. See REPRODUCIBILITY.md for the remaining commands and official MPD-DF download locations.

Intended uses

• EEG fatigue-classification research.
• Reproduction and teaching.
• Benchmarking subject-independent methods.
• Development of improved cross-subject validation procedures.

Out-of-scope uses

• Medical diagnosis or treatment decisions.
• A sole trigger for vehicle intervention or safety-critical alarms.
• Claims of real-world driving performance without external validation.
• Inference on arbitrary EEG channel layouts or sampling rates.
• Identification or profiling of dataset participants.

Limitations

• Data were collected during controlled simulated driving, not ordinary road use.
• Performance varies substantially between subjects.
• Four-second windows overlap by 50% and are not independent observations.
• Labels were physician-annotated from EEG, which may favor EEG-based models.
• Binary grouping combines heterogeneous Fatigue1–Fatigue4 states.
• An earlier exploratory one-second baseline viewed the same subject split. This release is the first held-out evaluation of the fully frozen Phase-2 pipeline, but stronger confirmatory claims require subject-level cross-validation.

Dataset and attribution

The dataset is not bundled. Download MPD-DF from the official Figshare records:

• Raw dataset and questionnaires: https://doi.org/10.6084/m9.figshare.28455737
• Preprocessed dataset: https://doi.org/10.6084/m9.figshare.28113164
• Dataset paper: https://doi.org/10.1038/s41597-026-06634-4

The MPD-DF datasets are distributed under CC BY 4.0. See DATA_LICENSE_NOTICE.md.

Licenses

• Model weights and documentation: CC BY 4.0 (LICENSE_MODEL_AND_DOCS.md).
• Original code in this release: Apache License 2.0 (LICENSE_CODE).
• MPD-DF data and upstream materials retain their respective original licenses.

Citation

Before public upload, replace the author and repository placeholders in CITATION.cff. Cite both this model release and the MPD-DF dataset paper.