# srovins/wesad architecture

> Architecture diagram of the GitHub repository srovins/wesad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/srovins/wesad
- Repository: https://github.com/srovins/wesad

## Overview

##### Project Type and Purpose
- This is a machine‐learning pipeline for “Stress Detection from Multimodal Wearable Sensor Data” using an autoencoder to extract latent features, followed by classical classifiers (SVM, MLP) for 3-class stress classification.
- It is not a full-stack web app but rather an experimental research/analysis project: data ingestion, preprocessing, feature extraction, model training, and result analysis.

##### File Structure
- Top-level scripts:
- merge_subj_data.py — loads raw WESAD data, filters and merges sensor streams
- extract_ae_latent_features.py — builds/trains autoencoder, extracts and saves latent features
- ae_feature_extractor.py — contains autoencoder architecture definitions and training logic
- DataPreprocessing.py — (if present) additional cleaning or filtering utilities
- Jupyter notebooks for exploratory analysis and classification experiments:
- ExploratoryDataAnalysis.ipynb
- CNN_Baseline.ipynb, Model1-DNN.ipynb, SVM_classifier.ipynb, MLP_classifier.ipynb
- Data folders:
- data/WESAD/ — raw sensor files
- data/ — generated pickles (merged signals)
- features/train & features/test — latent feature datasets (leave-one-subject-out folds)
- trained_models/ — saved autoencoder encoder weights by fold
- No web server or external API; dependencies are standard Python data science/ML libs (NumPy, Pandas, scikit-learn, TensorFlow/Keras).

##### README for Insights
- The project flow is clearly defined in 3 ordered steps: data merge/preprocess → AE feature extraction → classifier training + analysis.
- No deployment or microservices; this is a batch/offline pipeline.

##### Main Components & Interactions
a. Data Ingestion and Preprocessing
- Component: “Raw WESAD Data” (external data source)
- Process: merge_subj_data.py
- Output: merged pickles (subj_merged_*.pkl, merged_chest_fltr.pkl) in data/
b. Autoencoder Feature Extraction
- Component: ae_feature_extractor.py + extract_ae_latent_features.py
- Sub-components:
– AE Model Definition (encoder, decoder)
– Training Engine (LOSOV folds)
– Feature Extraction Module
- Output: latent feature pickles in features/train/ and features/test/
c. Classifier Training & Evaluation
- Components (notebooks):
– SVM_classifier.ipynb
– MLP_classifier.ipynb
– (optional CNN_Baseline.ipynb, Model1-DNN.ipynb)
- Inputs: latent feature pickles
- Outputs: classification results, performance metrics, plots
d. Model Artifacts
- trained_models/c/*.h5 — saved encoder weights by fold

##### Architectural Patterns & Principles
- Modular pipeline: clear separation of data preparation, feature engineering, and modeling stages.
- Reproducibility: scripts produce deterministic output files; notebooks consume them.
- Leave-one-subject-out (LOSOV) cross-validation pattern, enforced at AE and classifier stages.
- Data-centric design: persistent pickle files as “data at rest” between stages.

##### Technologies & Frameworks
- Python scripting (merge_subj_data.py, extract_ae_latent_features.py)
- Jupyter Notebooks for analysis and classifier prototyping
- TensorFlow/Keras for autoencoder design and training
- scikit-learn for SVM, MLP classifiers
- Pandas/NumPy for data handling, pickle for serialization

##### Detailed Recommendations
- “Raw WESAD Data” block on the far left, annotated with the URL of the dataset.
- Then a “Autoencoder Pipeline” container:
- Split into AE Training (encoder/decoder) and Latent Feature Extraction.
- Output to two data stores: features/train and features/test.
- To the right, place two analysis modules: SVM Notebook and MLP Notebook, both consuming the feature stores and producing evaluation plots/tables.
- Underneath, illustrate the trained_models/c folder, showing that encoder weights are persisted for replication.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    RawData["Raw WESAD Data"]:::data
    click RawData "https://github.com/srovins/wesad/tree/main/data/WESAD/"

    MergePreprocess["merge_subj_data.py"]:::process
    click MergePreprocess "https://github.com/srovins/wesad/blob/main/merge_subj_data.py"

    PreprocessingUtils["DataPreprocessing.py"]:::process
    click PreprocessingUtils "https://github.com/srovins/wesad/blob/main/DataPreprocessing.py"

    MergedPickles["Merged Pickles (data/*.pkl)"]:::data

    RawData -->|reads| MergePreprocess
    MergePreprocess -->|uses| PreprocessingUtils
    MergePreprocess -->|outputs| MergedPickles

    %% Autoencoder Pipeline
    subgraph "Autoencoder Pipeline"
        direction TB
        AEDef["ae_feature_extractor.py"]:::process
        click AEDef "https://github.com/srovins/wesad/blob/main/ae_feature_extractor.py"
        AEExtract["extract_ae_latent_features.py"]:::process
        click AEExtract "https://github.com/srovins/wesad/blob/main/extract_ae_latent_features.py"
        loopNote{{"LOSOV loop\nfor each subject"}}:::note
        MergedPickles --> AEExtract
        AEExtract -->|defines model| AEDef
        AEExtract -->|extracts latent features| FeaturesTrain
        AEExtract -->|extracts latent features| FeaturesTest
        AEDef --> loopNote
        AEExtract --> loopNote
    end

    %% Feature Stores
    FeaturesTrain["Latent Features (features/train/)"]:::data
    click FeaturesTrain "https://github.com/srovins/wesad/tree/main/features/train/"
    FeaturesTest["Latent Features (features/test/)"]:::data
    click FeaturesTest "https://github.com/srovins/wesad/tree/main/features/test/"

    %% Model Artifacts
    TrainedModels["Encoder Weights (trained_models/c/*.h5)"]:::model
    click TrainedModels "https://github.com/srovins/wesad/tree/main/trained_models/c/"

    AEExtract --> TrainedModels

    %% Analysis & Visualization
    subgraph "Analysis & Visualization"
        direction TB
        EDA["ExploratoryDataAnalysis.ipynb"]:::analysis
        click EDA "https://github.com/srovins/wesad/blob/main/ExploratoryDataAnalysis.ipynb"
        SVM["SVM_classifier.ipynb"]:::analysis
        click SVM "https://github.com/srovins/wesad/blob/main/SVM_classifier.ipynb"
        MLP["MLP_classifier.ipynb"]:::analysis
        click MLP "https://github.com/srovins/wesad/blob/main/MLP_classifier.ipynb"
        CNN["CNN_Baseline.ipynb"]:::analysis
        click CNN "https://github.com/srovins/wesad/blob/main/CNN_Baseline.ipynb"
        DNN["Model1-DNN.ipynb"]:::analysis
        click DNN "https://github.com/srovins/wesad/blob/main/Model1-DNN.ipynb"
    end

    FeaturesTrain --> EDA
    FeaturesTrain --> SVM
    FeaturesTrain --> MLP
    FeaturesTrain --> CNN
    FeaturesTrain --> DNN

    FeaturesTest --> EDA
    FeaturesTest --> SVM
    FeaturesTest --> MLP
    FeaturesTest --> CNN
    FeaturesTest --> DNN

    classDef data fill:#BBDEFB,stroke:#2196F3,color:#0D47A1;
    classDef process fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
    classDef analysis fill:#FFE0B2,stroke:#F57C00,color:#E65100;
    classDef model fill:#E1BEE7,stroke:#8E24AA,color:#4A148C;
    classDef note fill:#FFFFFF,stroke:#757575,stroke-dasharray: 5 5;
```
