# koraykarabina/impacx_onhw architecture

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

- Interactive diagram: https://gitdiagram.com/koraykarabina/impacx_onhw
- Repository: https://github.com/koraykarabina/impacx_onhw

## Overview

##### Main System Components
- Data Layer:
– Dataset folder: holds the raw OnHW-chars dataset (stored as NumPy arrays and associated readme files).
- Preprocessing / Feature Extraction:
– Scripts such as OnHW_ML_extract_features_various_nsig.py handle feature extraction (using tools like tsfresh).
– Utility modules in the utils/ folder (e.g., config.py) provide configuration for preprocessing.
- Machine Learning Pipeline:
– Baseline ML training scripts like OnHW_ML_DL_baseline_and_optimized_train_and_eval.py that call functions for data filtering, feature extraction, and standard model training (e.g., KNN, logistic regression, SVM, etc.).
– Training scripts for specialized ML tasks: OnHW_ML_train_KNN_various_nsig.py and OnHW_ML_train_KNN_various_ncomp.py for training KNN models over different feature/n_component settings.
- Deep Learning Pipeline:
– Deep learning scripts (e.g., OnHW_DL_* scripts) to train standard deep learning models.
– Optimization module: OnHW_DL_optimize.py uses the Optuna framework to optimize deep learning model parameters.
- Evaluation & Ensemble:
– Scripts such as ensemble_evaluation.py process evaluation metrics, generate classification reports, confusion matrices, and perform ensemble voting (majority, soft voting, weighted, etc.).
- Visualization & Reporting:
– Results plotting: plot_kNN_results.py to produce figures (e.g., Figures 3 and 4) using matplotlib.
– Results aggregation and visualization are handled by results_to_visual.py, which creates HTML reports.
- Explainability & Failure Analysis:
– Explain.py produces per-fold explainability outputs (bar charts and detailed time series graphs).
– Failure analysis modules: failure_space_analysis.py and failure_space_array.py provide insights into where models err (bar graphs and matrices).
- Utility Modules:
– The “utils” folder includes config, helpers, and routines for file/folder management which are used across the entire pipeline for consistency.

##### Interactions and Data Flow
– Data begins at the dataset layer: the raw dataset is ingested.
– Preprocessing Stage: Data is pre-processed, features are extracted (with configurations driven by utils/config.py).
– Training Stage: There is separate branching:
- ML Training: Baseline and metric learned versions run sequentially using the preprocessed features.
- DL Training: Baseline deep learning models and optimized deep learning models are trained and evaluated.
– Evaluation Stage: After training, results are stored in a designated “output” directory (and sub-folders such as ml_results, dl_results, etc.). Various scripts perform:
- Model evaluation (including ensemble voting).
- Failure space and explainability analyses.
– Visualization Stage: Final results, accuracies, confusion matrices, and performance plots are generated and aggregated to produce visual reports.

##### Architectural Patterns and Technical Aspects
– Pipeline/Workflow Architecture: The project operates as a sequential series of steps (data → feature extraction → training → evaluation → visualization), with several branching points for ML vs. DL.
– Modularity: The code is separated into multiple single-purpose scripts to allow easier re-running and tracking of experiments.
– Configurability: The configuration in utils/config.py and use of external dependencies (e.g., tsfresh, optuna) shows design for experiment reproducibility.
– Data Persistence: Intermediate and final outputs are stored on disk in a structured “output” directory; this is key for later analysis and visualization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    Dataset["Dataset Ingestion\n(raw data)"]:::dataset

    %% Preprocessing & Feature Extraction
    subgraph "Preprocessing & Feature Extraction"
        Preprocess["Feature Extraction\n(tsfresh & numpy)"]:::preprocessing
        Config["Config Utility"]:::preprocessing
    end

    %% Machine Learning Pipeline
    subgraph "Machine Learning Pipeline"
        ML_Baseline["Baseline/Optimized Training\n(OnHW_ML_DL_baseline_and_optimized_train_and_eval.py)"]:::ml
        ML_KNN_various_nsig["KNN Training (VarFeatures)\n(OnHW_ML_train_KNN_various_nsig.py)"]:::ml
        ML_KNN_various_ncomp["KNN Training (VarComponents)\n(OnHW_ML_train_KNN_various_ncomp.py)"]:::ml
    end

    %% Deep Learning Pipeline
    subgraph "Deep Learning Pipeline"
        DL_Optimize["DL Optimization\n(OnHW_DL_optimize.py)"]:::dl
    end

    %% Evaluation & Ensemble
    Evaluation["Evaluation & Ensemble\n(ensemble_evaluation.py)"]:::evaluation

    %% Visualization & Reporting
    subgraph "Visualization & Reporting"
        Visualize_Plot["Results Plotting\n(plot_kNN_results.py)"]:::visualization
        Visualize_HTML["Results Reporting\n(results_to_visual.py)"]:::visualization
    end

    %% Explainability & Failure Analysis
    subgraph "Explainability & Failure Analysis"
        Explain["Explainability\n(explain.py)"]:::explain
        Failure_Analysis["Failure Analysis\n(failure_space_analysis.py)"]:::explain
        Failure_Array["Failure Array Analysis\n(failure_space_array.py)"]:::explain
    end

    %% Utility Modules
    Utility["Utility Modules\n(utils/ folder)"]:::utility

    %% Data Flow Connections
    Dataset --> Preprocess
    Preprocess --> ML_Baseline
    Preprocess --> ML_KNN_various_nsig
    Preprocess --> ML_KNN_various_ncomp
    Preprocess --> DL_Optimize

    ML_Baseline --> Evaluation
    ML_KNN_various_nsig --> Evaluation
    ML_KNN_various_ncomp --> Evaluation
    DL_Optimize --> Evaluation

    Evaluation --> Visualize_Plot
    Evaluation --> Visualize_HTML
    Evaluation --> Explain
    Evaluation --> Failure_Analysis
    Evaluation --> Failure_Array

    %% Utility support connection (dashed)
    Utility --- Config

    %% Legend
    subgraph "Legend"
        L1["Data: Dataset Ingestion"]:::dataset
        L2["Preprocessing: Feature Extraction/Config"]:::preprocessing
        L3["ML Pipeline: Training Scripts"]:::ml
        L4["DL Pipeline: Optimization"]:::dl
        L5["Evaluation: Ensemble Methods"]:::evaluation
        L6["Visualization: Plotting & Reporting"]:::visualization
        L7["Explainability: Analysis Modules"]:::explain
        L8["Utility: General Helpers"]:::utility
    end

    %% Click Events
    click Dataset "https://github.com/koraykarabina/impacx_onhw/tree/master/dataset/"
    click Preprocess "https://github.com/koraykarabina/impacx_onhw/blob/master/OnHW_ML_extract_features_various_nsig.py"
    click Config "https://github.com/koraykarabina/impacx_onhw/blob/master/utils/config.py"
    click ML_Baseline "https://github.com/koraykarabina/impacx_onhw/blob/master/OnHW_ML_DL_baseline_and_optimized_train_and_eval.py"
    click ML_KNN_various_nsig "https://github.com/koraykarabina/impacx_onhw/blob/master/OnHW_ML_train_KNN_various_nsig.py"
    click ML_KNN_various_ncomp "https://github.com/koraykarabina/impacx_onhw/blob/master/OnHW_ML_train_KNN_various_ncomp.py"
    click DL_Optimize "https://github.com/koraykarabina/impacx_onhw/blob/master/OnHW_DL_optimize.py"
    click Evaluation "https://github.com/koraykarabina/impacx_onhw/blob/master/ensemble_evaluation.py"
    click Visualize_Plot "https://github.com/koraykarabina/impacx_onhw/blob/master/plot_kNN_results.py"
    click Visualize_HTML "https://github.com/koraykarabina/impacx_onhw/blob/master/results_to_visual.py"
    click Explain "https://github.com/koraykarabina/impacx_onhw/blob/master/explain.py"
    click Failure_Analysis "https://github.com/koraykarabina/impacx_onhw/blob/master/failure_space_analysis.py"
    click Failure_Array "https://github.com/koraykarabina/impacx_onhw/blob/master/failure_space_array.py"
    click Utility "https://github.com/koraykarabina/impacx_onhw/tree/master/utils/"

    %% Styles
    classDef dataset fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef preprocessing fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef ml fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef dl fill:#cce5ff,stroke:#0066cc,stroke-width:2px;
    classDef evaluation fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef visualization fill:#e6ccff,stroke:#660099,stroke-width:2px;
    classDef explain fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef utility fill:#d9d9d9,stroke:#666666,stroke-width:2px;
```
