# chahmed12/eeg-absence-detection architecture

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

- Interactive diagram: https://gitdiagram.com/chahmed12/eeg-absence-detection
- Repository: https://github.com/chahmed12/eeg-absence-detection

## Overview

EEG Absence Detection turns annotated multichannel EEG recordings into seizure-event intervals, evaluated by patient-held-out validation and presented through a Streamlit demo. The documented workflow is signal loading and causal filtering, annotation/window labeling, feature or raw-window modeling, temporal postprocessing, then event-level evaluation and visualization. Separate experimental branches cover LightGBM and deep-learning models, including EEGNet and threshold selection. Source excerpts establish several module calls; broader pipeline-stage links rely on the README, so unsampled implementation details are not expanded.

Main entry points: [`src/io.py`](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/io.py) (Signal and annotation I/O), [`src/postprocess.py`](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/postprocess.py) (Event reconstruction), [`src/evaluation.py`](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/evaluation.py) (Event evaluation), [`scripts/verify_three_checks.py`](https://github.com/chahmed12/eeg-absence-detection/blob/main/scripts/verify_three_checks.py) (Validation checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data and targets"]
  node_recordings["EEG recordings"]
  node_annotations["Seizure annotations"]
  node_signal_io["Signal and annotation I/O<br/>[io.py]"]
  node_labeling["Sample labeling<br/>[labeling.py]"]
end

subgraph group_signal["Signal preparation"]
  node_config["Pipeline configuration<br/>[config.py]"]
  node_preprocess["Causal filtering<br/>[preprocess.py]"]
  node_windowing["Window generation<br/>[windowing.py]"]
  node_features["EEG features<br/>[features.py]"]
end

subgraph group_detection["Detection models"]
  node_classical["Classical models<br/>[models.py]"]
  node_deep_learning["Deep learning<br/>[deep_learning.py]"]
  node_exp_lightgbm["Nested LightGBM"]
  node_exp_eegnet["EEGNet experiment"]
  node_exp_threshold["Threshold selection"]
end

subgraph group_assessment["Assessment and results"]
  node_verify["Validation checks"]
  node_postprocess["Event reconstruction<br/>[postprocess.py]"]
  node_evaluation["Event evaluation<br/>[evaluation.py]"]
  node_visualization["EEG visualization<br/>[viz.py]"]
end

subgraph group_interface["Interactive demo"]
  node_streamlit["Streamlit demo<br/>[streamlit_app.py]"]
end

node_analyst(("Analyst"))

node_analyst -->|"opens demo"| node_streamlit
node_recordings -->|"loads"| node_signal_io
node_annotations -->|"loads and audits"| node_signal_io
node_signal_io -->|"filters signal"| node_preprocess
node_config -->|"configures paths"| node_signal_io
node_signal_io -->|"supplies annotations"| node_labeling
node_labeling -->|"labels windows"| node_windowing
node_preprocess -->|"prepares signal"| node_features
node_windowing -->|"segments signal"| node_features
node_features -->|"provides features"| node_classical
node_windowing -->|"provides raw windows"| node_deep_learning
node_exp_lightgbm -->|"uses models"| node_classical
node_exp_lightgbm -->|"evaluates folds"| node_evaluation
node_exp_lightgbm -->|"loads recordings"| node_signal_io
node_exp_lightgbm -->|"reconstructs events"| node_postprocess
node_exp_eegnet -->|"uses network"| node_deep_learning
node_exp_eegnet -->|"evaluates folds"| node_evaluation
node_exp_eegnet -->|"loads recordings"| node_signal_io
node_exp_eegnet -->|"reconstructs events"| node_postprocess
node_exp_threshold -->|"selects thresholds"| node_postprocess
node_exp_threshold -->|"scores events"| node_evaluation
node_classical -.->|"scores windows"| node_postprocess
node_deep_learning -.->|"scores windows"| node_postprocess
node_postprocess -->|"returns intervals"| node_evaluation
node_evaluation -.->|"reports metrics"| node_visualization
node_streamlit -->|"loads data"| node_signal_io
node_streamlit -->|"uses event intervals"| node_postprocess
node_streamlit -->|"uses event metrics"| node_evaluation
node_streamlit -->|"renders views"| node_visualization
node_verify -->|"checks models"| node_classical
node_verify -->|"checks networks"| node_deep_learning
node_verify -->|"checks evaluation"| node_evaluation
node_verify -->|"loads recordings"| node_signal_io
node_verify -->|"checks reconstruction"| node_postprocess

click node_config "https://github.com/chahmed12/eeg-absence-detection/blob/main/src/config.py"
click node_signal_io "https://github.com/chahmed12/eeg-absence-detection/blob/main/src/io.py"
click node_preprocess "https://github.com/chahmed12/eeg-absence-detection/blob/main/src/preprocess.py"
click node_labeling "https://github.com/chahmed12/eeg-absence-detection/blob/main/src/labeling.py"
click node_windowing "https://github.com/chahmed12/eeg-absence-detection/blob/main/src/windowing.py"
click node_features "https://github.com/chahmed12/eeg-absence-detection/blob/main/src/features.py"
click node_classical "https://github.com/chahmed12/eeg-absence-detection/blob/main/src/models.py"
click node_deep_learning "https://github.com/chahmed12/eeg-absence-detection/blob/main/src/deep_learning.py"
click node_exp_lightgbm "https://github.com/chahmed12/eeg-absence-detection/blob/main/scripts/scripts_step6_exp00_lightgbm_nested.py"
click node_exp_eegnet "https://github.com/chahmed12/eeg-absence-detection/blob/main/scripts/scripts_step6_exp03_eegnet.py"
click node_exp_threshold "https://github.com/chahmed12/eeg-absence-detection/blob/main/scripts/scripts_step6_exp04_threshold.py"
click node_verify "https://github.com/chahmed12/eeg-absence-detection/blob/main/scripts/verify_three_checks.py"
click node_postprocess "https://github.com/chahmed12/eeg-absence-detection/blob/main/src/postprocess.py"
click node_evaluation "https://github.com/chahmed12/eeg-absence-detection/blob/main/src/evaluation.py"
click node_visualization "https://github.com/chahmed12/eeg-absence-detection/blob/main/src/viz.py"
click node_streamlit "https://github.com/chahmed12/eeg-absence-detection/blob/main/app/streamlit_app.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_recordings,node_annotations,node_signal_io,node_labeling toneBlue
class node_config,node_preprocess,node_windowing,node_features toneAmber
class node_classical,node_deep_learning,node_exp_lightgbm,node_exp_eegnet,node_exp_threshold toneMint
class node_verify,node_postprocess,node_evaluation,node_visualization toneRose
class node_streamlit,node_analyst toneIndigo
```

## Components

### Data and targets

- **EEG recordings**
- **Seizure annotations**
- [Signal and annotation I/O](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/io.py): `src/io.py`
- [Sample labeling](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/labeling.py): `src/labeling.py`

### Signal preparation

- [Pipeline configuration](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/config.py): `src/config.py`
- [Causal filtering](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/preprocess.py): `src/preprocess.py`
- [Window generation](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/windowing.py): `src/windowing.py`
- [EEG features](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/features.py): `src/features.py`

### Detection models

- [Classical models](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/models.py): `src/models.py`
- [Deep learning](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/deep_learning.py): `src/deep_learning.py`
- [Nested LightGBM](https://github.com/chahmed12/eeg-absence-detection/blob/main/scripts/scripts_step6_exp00_lightgbm_nested.py): `scripts/scripts_step6_exp00_lightgbm_nested.py`
- [EEGNet experiment](https://github.com/chahmed12/eeg-absence-detection/blob/main/scripts/scripts_step6_exp03_eegnet.py): `scripts/scripts_step6_exp03_eegnet.py`
- [Threshold selection](https://github.com/chahmed12/eeg-absence-detection/blob/main/scripts/scripts_step6_exp04_threshold.py): `scripts/scripts_step6_exp04_threshold.py`

### Assessment and results

- [Validation checks](https://github.com/chahmed12/eeg-absence-detection/blob/main/scripts/verify_three_checks.py): `scripts/verify_three_checks.py`
- [Event reconstruction](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/postprocess.py): `src/postprocess.py`
- [Event evaluation](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/evaluation.py): `src/evaluation.py`
- [EEG visualization](https://github.com/chahmed12/eeg-absence-detection/blob/main/src/viz.py): `src/viz.py`

### Interactive demo

- [Streamlit demo](https://github.com/chahmed12/eeg-absence-detection/blob/main/app/streamlit_app.py): `app/streamlit_app.py`

### Other components

- **Analyst**

## Connections

- Analyst → Streamlit demo: opens demo (evidence: `README.md`)
- EEG recordings → Signal and annotation I/O: loads (evidence: `README.md`)
- Seizure annotations → Signal and annotation I/O: loads and audits (evidence: `src/io.py`)
- Signal and annotation I/O → Causal filtering: filters signal (evidence: `src/io.py`)
- Pipeline configuration → Signal and annotation I/O: configures paths (evidence: `src/config.py`)
- Signal and annotation I/O → Sample labeling: supplies annotations (evidence: `README.md`)
- Sample labeling → Window generation: labels windows (evidence: `README.md`)
- Causal filtering → EEG features: prepares signal (evidence: `README.md`)
- Window generation → EEG features: segments signal (evidence: `src/features.py`)
- EEG features → Classical models: provides features (evidence: `README.md`)
- Window generation → Deep learning: provides raw windows (evidence: `src/deep_learning.py`)
- Nested LightGBM → Classical models: uses models (evidence: `scripts/scripts_step6_exp00_lightgbm_nested.py`)
- Nested LightGBM → Event evaluation: evaluates folds (evidence: `scripts/scripts_step6_exp00_lightgbm_nested.py`)
- Nested LightGBM → Signal and annotation I/O: loads recordings (evidence: `scripts/scripts_step6_exp00_lightgbm_nested.py`)
- Nested LightGBM → Event reconstruction: reconstructs events (evidence: `scripts/scripts_step6_exp00_lightgbm_nested.py`)
- EEGNet experiment → Deep learning: uses network (evidence: `scripts/scripts_step6_exp03_eegnet.py`)
- EEGNet experiment → Event evaluation: evaluates folds (evidence: `scripts/scripts_step6_exp03_eegnet.py`)
- EEGNet experiment → Signal and annotation I/O: loads recordings (evidence: `scripts/scripts_step6_exp03_eegnet.py`)
- EEGNet experiment → Event reconstruction: reconstructs events (evidence: `scripts/scripts_step6_exp03_eegnet.py`)
- Threshold selection → Event reconstruction: selects thresholds (evidence: `scripts/scripts_step6_exp04_threshold.py`)
- Threshold selection → Event evaluation: scores events (evidence: `scripts/scripts_step6_exp04_threshold.py`)
- Classical models → Event reconstruction: scores windows
- Deep learning → Event reconstruction: scores windows
- Event reconstruction → Event evaluation: returns intervals (evidence: `src/evaluation.py`)
- Event evaluation → EEG visualization: reports metrics
- Streamlit demo → Signal and annotation I/O: loads data (evidence: `app/streamlit_app.py`)
- Streamlit demo → Event reconstruction: uses event intervals (evidence: `app/streamlit_app.py`)
- Streamlit demo → Event evaluation: uses event metrics (evidence: `app/streamlit_app.py`)
- Streamlit demo → EEG visualization: renders views (evidence: `app/streamlit_app.py`)
- Validation checks → Classical models: checks models (evidence: `scripts/verify_three_checks.py`)
- Validation checks → Deep learning: checks networks (evidence: `scripts/verify_three_checks.py`)
- Validation checks → Event evaluation: checks evaluation (evidence: `scripts/verify_three_checks.py`)
- Validation checks → Signal and annotation I/O: loads recordings (evidence: `scripts/verify_three_checks.py`)
- Validation checks → Event reconstruction: checks reconstruction (evidence: `scripts/verify_three_checks.py`)