# linusjuni/mathematical-modelling-linear-classification architecture

> Architecture diagram of the GitHub repository linusjuni/mathematical-modelling-linear-classification, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/linusjuni/mathematical-modelling-linear-classification
- Repository: https://github.com/linusjuni/mathematical-modelling-linear-classification

## Overview

##### Project type and purpose
- This is a research‐oriented data‐science pipeline for binary classification (pneumonia vs. healthy) on chest X-ray images.
- There is no client‐server or deployed web service; instead, it’s a modular set of scripts and utilities to preprocess data, extract features, train/evaluate models, and persist results.

##### File structure
- Top-level directories:
- data/ – raw MedMNIST training and test image folders
- models/ – serialized model files (*.joblib)
- src/ – all source code modules and experiment scripts
- In src/:
- part_1.py, part_2.py, part_3.py (and “_own_data_split” variants) orchestrate three experimental pipelines (raw‐pixels, Sobel‐gradients, HOG)
- model_utils.py, data_utils.py, evaluation_utils.py, visualization_utils.py – reusable functions
- individual model implementations (baseline.py, random_forest.py, ada_boost.py, gradient_boost.py, multi_layer_perceptron.py)
- helper notebooks (cat_dog_example.ipynb) and comparison scripts
- Config/build/deployment: none (experiments run via command‐line Python)

##### README for additional insights
- The README describes three “parts” focusing on different feature strategies, how to run each part, where models are saved, and how to load them via model_utils.py
- Emphasizes PCA as an optional dimensionality reduction step, visualizations, and hyperparameter tuning

##### Detail
- Both training and inference (loading models for new data) flows
- Multiple experiment entry points (scripts vs. comparison modules)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer"
        DataTrain["data/train"]:::data
        DataTest["data/test"]:::data
        DataUtils["data_utils.py"]:::data
    end

    %% Feature Extraction Layer
    subgraph "Feature Extraction Layer"
        Raw["Raw Flattening"]:::pre
        Sobel["Sobel Gradients"]:::pre
        HOG["HOG Features"]:::pre
    end

    %% Optional Dimensionality Reduction
    PCA["Optional PCA"]:::pre

    %% Model Training & Persistence
    subgraph "Model Training & Persistence"
        Baseline["Baseline Linear"]:::model
        RF["Random Forest"]:::model
        Ada["AdaBoost"]:::model
        GB["Gradient Boost"]:::model
        MLP["MLP"]:::model
        ModelUtils["model_utils.py"]:::model
        ModelsStore["models/*.joblib"]:::data
    end

    %% Evaluation & Visualization
    subgraph "Evaluation & Visualization"
        Eval["Evaluation Metrics"]:::eval
        Viz["Visualization"]:::eval
        PCAPlot["PCA Plotting"]:::eval
    end

    %% Experiment Orchestrator Scripts
    subgraph "Experiment Orchestrators"
        Part1["part_1.py"]:::script
        Part2["part_2.py"]:::script
        Part3["part_3.py"]:::script
        Part1Own["part_1_own_data_split.py"]:::script
        Part2Own["part_2_own_data_split.py"]:::script
        Part3Own["part_3_own_data_split.py"]:::script
        Part3Tune["part_3_tuning.py"]:::script
    end

    %% Comparison & Reporting
    subgraph "Comparison & Reporting"
        Comparison["model_comparison.py"]:::script
        ComparisonOwn["model_comparison_own_data_split.py"]:::script
    end

    %% Connections: Data to Features
    DataTrain -->|images| Raw
    DataTrain -->|images| Sobel
    DataTrain -->|images| HOG
    DataTest -->|images| Raw
    DataTest -->|images| Sobel
    DataTest -->|images| HOG
    DataUtils --> Raw
    DataUtils --> Sobel
    DataUtils --> HOG

    %% Features to PCA
    Raw --> PCA
    Sobel --> PCA
    HOG --> PCA

    %% PCA to Models
    PCA --> Baseline
    PCA --> RF
    PCA --> Ada
    PCA --> GB
    PCA --> MLP
    ModelUtils --> Baseline
    ModelUtils --> RF
    ModelUtils --> Ada
    ModelUtils --> GB
    ModelUtils --> MLP

    %% Persistence
    Baseline -->|model.joblib| ModelsStore
    RF -->|model.joblib| ModelsStore
    Ada -->|model.joblib| ModelsStore
    GB -->|model.joblib| ModelsStore
    MLP -->|model.joblib| ModelsStore

    %% Models to Evaluation & Visualization
    Baseline --> Eval
    RF --> Eval
    Ada --> Eval
    GB --> Eval
    MLP --> Eval
    Eval --> Viz
    PCA --> PCAPlot

    %% Orchestrators to Pipelines
    Part1 --> Raw
    Part1Own --> Raw
    Part2 --> Sobel
    Part2Own --> Sobel
    Part3 --> HOG
    Part3Own --> HOG
    Part3Tune --> HOG

    %% Comparison scripts consume models
    ModelsStore --> Comparison
    ModelsStore --> ComparisonOwn

    %% Click Events
    click DataUtils "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/data_utils.py"
    click Raw "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_1.py"
    click Raw "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_1_own_data_split.py"
    click Sobel "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_2.py"
    click Sobel "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_2_own_data_split.py"
    click HOG "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_3.py"
    click HOG "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_3_own_data_split.py"
    click HOG "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_3_tuning.py"
    click PCA "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/model_utils.py"
    click PCA "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/pca_plotting.py"
    click Baseline "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/baseline.py"
    click RF "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/random_forest.py"
    click Ada "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/ada_boost.py"
    click GB "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/gradient_boost.py"
    click MLP "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/multi_layer_perceptron.py"
    click ModelUtils "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/model_utils.py"
    click Eval "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/evaluation_utils.py"
    click Viz "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/visualization_utils.py"
    click PCAPlot "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/pca_plotting.py"
    click Part1 "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_1.py"
    click Part1Own "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_1_own_data_split.py"
    click Part2 "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_2.py"
    click Part2Own "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_2_own_data_split.py"
    click Part3 "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_3.py"
    click Part3Own "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_3_own_data_split.py"
    click Part3Tune "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/part_3_tuning.py"
    click Comparison "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/model_comparison.py"
    click ComparisonOwn "https://github.com/linusjuni/mathematical-modelling-linear-classification/blob/main/src/model_comparison_own_data_split.py"

    %% Styles
    classDef data fill:#d0e7f9,stroke:#0366d6,color:#0366d6;
    classDef pre fill:#d1f9d8,stroke:#28a745,color:#28a745;
    classDef model fill:#ffe5b4,stroke:#fd7e14,color:#fd7e14;
    classDef eval fill:#f3d1f9,stroke:#6f42c1,color:#6f42c1;
    classDef script fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
