# ciglenecki/eeg-driver-fatigue-detection architecture

> Architecture diagram of the GitHub repository ciglenecki/eeg-driver-fatigue-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ciglenecki/eeg-driver-fatigue-detection
- Repository: https://github.com/ciglenecki/eeg-driver-fatigue-detection

## Overview

This repository implements an EEG driver-fatigue research workflow: prepare CNT recordings, filter and transform signals into epoch-level features, clean and normalize a dataframe, train and compare classifiers, then rank significant electrodes. The README documents entropy combinations, participant-held-out SVM tuning, four classifier families, and model reporting; sampled sources show the dataframe, normalization, model configuration, and electrode-weight calculations. Several training and postprocessing files are indexed but not excerpted, so documented capabilities are included while uncertain internal call links are omitted.

Main entry points: [`src/postprocess_significant_electrodes.py`](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/postprocess_significant_electrodes.py) (Electrode Analysis), [`src/preprocess_create_df_from_signals.py`](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/preprocess_create_df_from_signals.py) (Dataframe Builder), [`data/dataframes`](https://github.com/ciglenecki/eeg-driver-fatigue-detection/tree/main/data/dataframes) (Feature Dataframes), [`src/model_summary.py`](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/model_summary.py) (Model Summary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_preparation["Signal Preparation"]
  node_unpack["Unpack Data"]
  node_signal_processing["Signal Processing<br/>[utils_signal.py]"]
  node_signal_config["Signal Configuration<br/>[utils_env.py]"]
end

subgraph group_features["Feature Data"]
  node_feature_extraction["Feature Extraction"]
  node_dataframe_builder["Dataframe Builder"]
  node_data_cleaning["Data Cleaning"]
end

subgraph group_training["Model Training"]
  node_model_config["Classifier Configuration<br/>[model.py]"]
  node_entropy_search["Entropy Search<br/>[train_entropies.py]"]
  node_svm_tuning["SVM Tuning"]
  node_model_training["Model Training<br/>[train_models.py]"]
end

subgraph group_analysis["Evaluation Analysis"]
  node_model_summary["Model Summary<br/>[model_summary.py]"]
  node_electrode_analysis["Electrode Analysis"]
  node_all_electrodes["All-Driver Weights"]
  node_driver_electrodes["Per-Driver Weights"]
end

subgraph group_infrastructure["Shared Runtime"]
  node_file_saver["Artifact Persistence"]
  node_functions["Workflow Utilities<br/>[utils_functions.py]"]
  node_paths["Path Configuration<br/>[utils_paths.py]"]
  node_plotting["Plotting<br/>[utils_plot.py]"]
  node_data_stats["Dataframe Statistics<br/>[utils_df_stats.py]"]
end

node_researcher(("Researcher"))
node_cnt_data[("EEG Recordings")]
node_data_store[("Feature Dataframes")]
node_model_store[("Saved Models")]
node_report_store[("Reports")]

node_researcher -->|"prepares data"| node_unpack
node_cnt_data -->|"provides recordings"| node_unpack
node_unpack -.->|"supplies signals"| node_dataframe_builder
node_signal_config -->|"configures processing"| node_dataframe_builder
node_dataframe_builder -->|"filters and crops"| node_signal_processing
node_dataframe_builder -->|"extracts features"| node_feature_extraction
node_dataframe_builder -->|"saves dataframes"| node_data_store
node_data_store -->|"loads dataframe"| node_data_cleaning
node_data_cleaning -->|"saves cleaned data"| node_data_store
node_data_store -->|"provides training data"| node_entropy_search
node_data_store -->|"provides training data"| node_svm_tuning
node_data_store -->|"provides training data"| node_model_training
node_model_config -->|"configures SVM"| node_entropy_search
node_model_config -->|"provides parameter ranges"| node_svm_tuning
node_model_config -->|"configures classifiers"| node_model_training
node_entropy_search -->|"reports combinations"| node_report_store
node_svm_tuning -->|"reports parameters"| node_report_store
node_model_training -->|"saves models"| node_model_store
node_model_training -->|"reports performance"| node_report_store
node_model_store -->|"supplies models"| node_model_summary
node_model_summary -->|"writes summaries"| node_report_store
node_data_store -->|"provides dataframe"| node_electrode_analysis
node_model_store -->|"provides SVM"| node_electrode_analysis
node_electrode_analysis -->|"dispatches all mode"| node_all_electrodes
node_electrode_analysis -->|"dispatches driver mode"| node_driver_electrodes
node_electrode_analysis -->|"reports weights"| node_report_store
node_dataframe_builder -->|"saves artifacts"| node_file_saver
node_file_saver -->|"formats metadata"| node_functions
node_dataframe_builder -->|"uses helpers"| node_functions
node_dataframe_builder -->|"uses data paths"| node_paths
node_data_cleaning -->|"saves cleaned data"| node_file_saver
node_data_cleaning -->|"uses dataframe path"| node_paths
node_model_summary -->|"loads and saves"| node_file_saver
node_model_summary -->|"uses helpers"| node_functions
node_model_summary -->|"uses report paths"| node_paths
node_electrode_analysis -->|"loads model"| node_file_saver
node_electrode_analysis -->|"uses helpers"| node_functions
node_electrode_analysis -->|"uses report paths"| node_paths
node_researcher -->|"requests evaluation"| node_model_training
node_researcher -->|"requests analysis"| node_electrode_analysis

click node_unpack "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/preprocess_unzip_data.py"
click node_signal_processing "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_signal.py"
click node_signal_config "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_env.py"
click node_feature_extraction "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_feature_extraction.py"
click node_dataframe_builder "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/preprocess_create_df_from_signals.py"
click node_data_cleaning "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/preprocess_preprocess_df.py"
click node_data_store "https://github.com/ciglenecki/eeg-driver-fatigue-detection/tree/main/data/dataframes"
click node_model_config "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/model.py"
click node_entropy_search "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/train_entropies.py"
click node_svm_tuning "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/train_svm_params.py"
click node_model_training "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/train_models.py"
click node_model_store "https://github.com/ciglenecki/eeg-driver-fatigue-detection/tree/main/models"
click node_model_summary "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/model_summary.py"
click node_electrode_analysis "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/postprocess_significant_electrodes.py"
click node_all_electrodes "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/postprocess_significant_electrodes_all.py"
click node_driver_electrodes "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/postprocess_significant_electrodes_users.py"
click node_report_store "https://github.com/ciglenecki/eeg-driver-fatigue-detection/tree/main/reports"
click node_file_saver "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_file_saver.py"
click node_functions "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_functions.py"
click node_paths "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_paths.py"
click node_plotting "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_plot.py"
click node_data_stats "https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_df_stats.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_unpack,node_signal_processing,node_signal_config toneBlue
class node_feature_extraction,node_dataframe_builder,node_data_cleaning,node_cnt_data,node_data_store,node_model_store,node_report_store toneAmber
class node_model_config,node_entropy_search,node_svm_tuning,node_model_training toneMint
class node_model_summary,node_electrode_analysis,node_all_electrodes,node_driver_electrodes toneRose
class node_file_saver,node_functions,node_paths,node_plotting,node_data_stats,node_researcher toneIndigo
```

## Components

### Signal Preparation

- [Unpack Data](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/preprocess_unzip_data.py): `src/preprocess_unzip_data.py`
- [Signal Processing](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_signal.py): `src/utils_signal.py`
- [Signal Configuration](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_env.py): `src/utils_env.py`

### Feature Data

- [Feature Extraction](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_feature_extraction.py): `src/utils_feature_extraction.py`
- [Dataframe Builder](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/preprocess_create_df_from_signals.py): `src/preprocess_create_df_from_signals.py`
- [Data Cleaning](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/preprocess_preprocess_df.py): `src/preprocess_preprocess_df.py`

### Model Training

- [Classifier Configuration](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/model.py): `src/model.py`
- [Entropy Search](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/train_entropies.py): `src/train_entropies.py`
- [SVM Tuning](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/train_svm_params.py): `src/train_svm_params.py`
- [Model Training](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/train_models.py): `src/train_models.py`

### Evaluation Analysis

- [Model Summary](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/model_summary.py): `src/model_summary.py`
- [Electrode Analysis](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/postprocess_significant_electrodes.py): `src/postprocess_significant_electrodes.py`
- [All-Driver Weights](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/postprocess_significant_electrodes_all.py): `src/postprocess_significant_electrodes_all.py`
- [Per-Driver Weights](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/postprocess_significant_electrodes_users.py): `src/postprocess_significant_electrodes_users.py`

### Shared Runtime

- [Artifact Persistence](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_file_saver.py): `src/utils_file_saver.py`
- [Workflow Utilities](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_functions.py): `src/utils_functions.py`
- [Path Configuration](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_paths.py): `src/utils_paths.py`
- [Plotting](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_plot.py): `src/utils_plot.py`
- [Dataframe Statistics](https://github.com/ciglenecki/eeg-driver-fatigue-detection/blob/main/src/utils_df_stats.py): `src/utils_df_stats.py`

### Other components

- **Researcher**
- **EEG Recordings**
- [Feature Dataframes](https://github.com/ciglenecki/eeg-driver-fatigue-detection/tree/main/data/dataframes): `data/dataframes`
- [Saved Models](https://github.com/ciglenecki/eeg-driver-fatigue-detection/tree/main/models): `models`
- [Reports](https://github.com/ciglenecki/eeg-driver-fatigue-detection/tree/main/reports): `reports`

## Connections

- Researcher → Unpack Data: prepares data (evidence: `README.md`)
- EEG Recordings → Unpack Data: provides recordings (evidence: `README.md`)
- Unpack Data → Dataframe Builder: supplies signals
- Signal Configuration → Dataframe Builder: configures processing (evidence: `src/preprocess_create_df_from_signals.py`)
- Dataframe Builder → Signal Processing: filters and crops (evidence: `src/preprocess_create_df_from_signals.py`)
- Dataframe Builder → Feature Extraction: extracts features (evidence: `src/preprocess_create_df_from_signals.py`)
- Dataframe Builder → Feature Dataframes: saves dataframes (evidence: `src/preprocess_create_df_from_signals.py`)
- Feature Dataframes → Data Cleaning: loads dataframe (evidence: `src/preprocess_preprocess_df.py`)
- Data Cleaning → Feature Dataframes: saves cleaned data (evidence: `src/preprocess_preprocess_df.py`)
- Feature Dataframes → Entropy Search: provides training data (evidence: `src/train_entropies.py`)
- Feature Dataframes → SVM Tuning: provides training data (evidence: `src/train_svm_params.py`)
- Feature Dataframes → Model Training: provides training data (evidence: `src/train_models.py`)
- Classifier Configuration → Entropy Search: configures SVM (evidence: `src/train_entropies.py`)
- Classifier Configuration → SVM Tuning: provides parameter ranges (evidence: `src/train_svm_params.py`)
- Classifier Configuration → Model Training: configures classifiers (evidence: `src/train_models.py`)
- Entropy Search → Reports: reports combinations (evidence: `src/train_entropies.py`)
- SVM Tuning → Reports: reports parameters (evidence: `src/train_svm_params.py`)
- Model Training → Saved Models: saves models (evidence: `src/train_models.py`)
- Model Training → Reports: reports performance (evidence: `README.md`)
- Saved Models → Model Summary: supplies models (evidence: `src/model_summary.py`)
- Model Summary → Reports: writes summaries (evidence: `src/model_summary.py`)
- Feature Dataframes → Electrode Analysis: provides dataframe (evidence: `src/postprocess_significant_electrodes.py`)
- Saved Models → Electrode Analysis: provides SVM (evidence: `src/postprocess_significant_electrodes.py`)
- Electrode Analysis → All-Driver Weights: dispatches all mode (evidence: `src/postprocess_significant_electrodes.py`)
- Electrode Analysis → Per-Driver Weights: dispatches driver mode (evidence: `src/postprocess_significant_electrodes.py`)
- Electrode Analysis → Reports: reports weights (evidence: `src/postprocess_significant_electrodes.py`)
- Dataframe Builder → Artifact Persistence: saves artifacts (evidence: `src/preprocess_create_df_from_signals.py`)
- Artifact Persistence → Workflow Utilities: formats metadata (evidence: `src/utils_file_saver.py`)
- Dataframe Builder → Workflow Utilities: uses helpers (evidence: `src/preprocess_create_df_from_signals.py`)
- Dataframe Builder → Path Configuration: uses data paths (evidence: `src/preprocess_create_df_from_signals.py`)
- Data Cleaning → Artifact Persistence: saves cleaned data (evidence: `src/preprocess_preprocess_df.py`)
- Data Cleaning → Path Configuration: uses dataframe path (evidence: `src/preprocess_preprocess_df.py`)
- Model Summary → Artifact Persistence: loads and saves (evidence: `src/model_summary.py`)
- Model Summary → Workflow Utilities: uses helpers (evidence: `src/model_summary.py`)
- Model Summary → Path Configuration: uses report paths (evidence: `src/model_summary.py`)
- Electrode Analysis → Artifact Persistence: loads model (evidence: `src/postprocess_significant_electrodes.py`)
- Electrode Analysis → Workflow Utilities: uses helpers (evidence: `src/postprocess_significant_electrodes.py`)
- Electrode Analysis → Path Configuration: uses report paths (evidence: `src/postprocess_significant_electrodes.py`)
- Researcher → Model Training: requests evaluation (evidence: `README.md`)
- Researcher → Electrode Analysis: requests analysis (evidence: `README.md`)
