# lucirie/ml-regression-models architecture

> Architecture diagram of the GitHub repository lucirie/ml-regression-models, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucirie/ml-regression-models
- Repository: https://github.com/lucirie/ml-regression-models

## Overview

##### Project type and purpose
- This is an open-source, educational ML toolkit demonstrating core regression algorithms (univariate linear, multivariate linear, polynomial, and logistic) implemented from scratch in Jupyter notebooks using only NumPy, Pandas, and Matplotlib.
- Its primary goal is to illustrate the math and mechanics of each algorithm, with data loading, training loops, and visualization tightly coupled in the notebooks.

##### File structure
- Top-level directories:
- unilinear/ (train.csv, test.csv, unilinear.ipynb)
- multilinear/ (Student_Performance.csv, multilinear.ipynb)
- nonlinear/ (icecream.csv, nonlinear.ipynb)
- logistic/ (wdbc.data, logistic.ipynb)
- Each directory bundles:
a) A dataset file (CSV or raw data)
b) A single notebook orchestrating data ingestion, model implementation, training, evaluation, and plotting
- No separate library modules—logic is embedded in notebooks.

##### README for additional insights
- Emphasizes implementing algorithms “from scratch” with core Python scientific libraries.
- No external ML frameworks; focus is on algorithmic intuition, gradient descent, cost visualization, decision boundaries.

##### Diagramming the architecture
a. Main components
- Data Sources (CSV/WDBC files)
- Data Loader & Preprocessor (in-notebook code for reading files, normalization)
- Model Implementations (functions or classes for each regression type)
- Training & Optimization (gradient descent loops, cost function computations)
- Evaluation & Visualization (plots of cost over iterations, decision boundary, fit lines)
- External Libraries (NumPy, Pandas, Matplotlib)
- Jupyter Notebook Runner (driver that ties everything together)

b. Relationships and data flow
2) Loader → Model Implementation (feeds preprocessed arrays)
3) Model Implementation ↔ Training & Optimization (iteration loop)
4) Training → Evaluation & Visualization (outputs metrics & plots)
5) Notebook Runner sits atop all components, invoking each step
6) Each component depends on the external libraries (NumPy, Pandas, Matplotlib)

c. Architectural patterns & design principles
- Layered pipeline pattern: data ingestion → preprocessing → model → evaluation
- Modular separation by algorithm type, each in its own directory
- Reuse of core utility routines (e.g., normalization, cost computation) across notebooks

d. Key technologies
- Python 3.x
- NumPy (array ops, linear algebra)
- Pandas (dataframes, CSV I/O)
- Matplotlib (plotting)
- Jupyter Notebook (interactive execution)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Libraries
    subgraph "External Libraries"
        NumPy["NumPy"]:::ext
        Pandas["Pandas"]:::ext
        Matplotlib["Matplotlib"]:::ext
    end

    %% Univariate Linear Regression Module
    subgraph "Univariate Linear Regression"
        direction TB
        ULR_Notebook["unilinear.ipynb"]:::comp
        ULR_Train["train.csv"]:::data
        ULR_Test["test.csv"]:::data
        ULR_Loader["Data Loader & Preprocessor"]:::comp
        ULR_Model["Model Implementation"]:::comp
        ULR_Trainer["Training & Optimization"]:::comp
        ULR_Visualizer["Evaluation & Visualization"]:::viz
    end

    %% Multivariate Linear Regression Module
    subgraph "Multivariate Linear Regression"
        direction TB
        MLR_Notebook["multilinear.ipynb"]:::comp
        MLR_Data["Student_Performance.csv"]:::data
        MLR_Loader["Data Loader & Preprocessor"]:::comp
        MLR_Model["Model Implementation"]:::comp
        MLR_Trainer["Training & Optimization"]:::comp
        MLR_Visualizer["Evaluation & Visualization"]:::viz
    end

    %% Polynomial (Nonlinear) Regression Module
    subgraph "Polynomial (Nonlinear) Regression"
        direction TB
        NLR_Notebook["nonlinear.ipynb"]:::comp
        NLR_Data["icecream.csv"]:::data
        NLR_Loader["Data Loader & Preprocessor"]:::comp
        NLR_Model["Model Implementation"]:::comp
        NLR_Trainer["Training & Optimization"]:::comp
        NLR_Visualizer["Evaluation & Visualization"]:::viz
    end

    %% Logistic Regression Module
    subgraph "Logistic Regression"
        direction TB
        LOGR_Notebook["logistic.ipynb"]:::comp
        LOGR_Data["wdbc.data"]:::data
        LOGR_Loader["Data Loader & Preprocessor"]:::comp
        LOGR_Model["Model Implementation"]:::comp
        LOGR_Trainer["Training & Optimization"]:::comp
        LOGR_Visualizer["Evaluation & Visualization"]:::viz
    end

    %% Data Flow: Univariate
    ULR_Train --> ULR_Loader
    ULR_Test --> ULR_Loader
    ULR_Loader --> ULR_Model
    ULR_Model --> ULR_Trainer
    ULR_Trainer --> ULR_Visualizer
    ULR_Notebook --> ULR_Loader
    ULR_Notebook --> ULR_Model
    ULR_Notebook --> ULR_Trainer
    ULR_Notebook --> ULR_Visualizer

    %% Data Flow: Multivariate
    MLR_Data --> MLR_Loader
    MLR_Loader --> MLR_Model
    MLR_Model --> MLR_Trainer
    MLR_Trainer --> MLR_Visualizer
    MLR_Notebook --> MLR_Loader
    MLR_Notebook --> MLR_Model
    MLR_Notebook --> MLR_Trainer
    MLR_Notebook --> MLR_Visualizer

    %% Data Flow: Nonlinear
    NLR_Data --> NLR_Loader
    NLR_Loader --> NLR_Model
    NLR_Model --> NLR_Trainer
    NLR_Trainer --> NLR_Visualizer
    NLR_Notebook --> NLR_Loader
    NLR_Notebook --> NLR_Model
    NLR_Notebook --> NLR_Trainer
    NLR_Notebook --> NLR_Visualizer

    %% Data Flow: Logistic
    LOGR_Data --> LOGR_Loader
    LOGR_Loader --> LOGR_Model
    LOGR_Model --> LOGR_Trainer
    LOGR_Trainer --> LOGR_Visualizer
    LOGR_Notebook --> LOGR_Loader
    LOGR_Notebook --> LOGR_Model
    LOGR_Notebook --> LOGR_Trainer
    LOGR_Notebook --> LOGR_Visualizer

    %% Dependencies on External Libraries
    ULR_Loader -.->|uses| Pandas
    ULR_Loader -.->|uses| NumPy
    ULR_Model -.->|uses| NumPy
    ULR_Trainer -.->|uses| NumPy
    ULR_Visualizer -.->|uses| Matplotlib

    MLR_Loader -.->|uses| Pandas
    MLR_Loader -.->|uses| NumPy
    MLR_Model -.->|uses| NumPy
    MLR_Trainer -.->|uses| NumPy
    MLR_Visualizer -.->|uses| Matplotlib

    NLR_Loader -.->|uses| Pandas
    NLR_Loader -.->|uses| NumPy
    NLR_Model -.->|uses| NumPy
    NLR_Trainer -.->|uses| NumPy
    NLR_Visualizer -.->|uses| Matplotlib

    LOGR_Loader -.->|uses| Pandas
    LOGR_Loader -.->|uses| NumPy
    LOGR_Model -.->|uses| NumPy
    LOGR_Trainer -.->|uses| NumPy
    LOGR_Visualizer -.->|uses| Matplotlib

    %% Click Events
    click ULR_Notebook "https://github.com/lucirie/ml-regression-models/blob/main/unilinear/unilinear.ipynb"
    click ULR_Train "https://github.com/lucirie/ml-regression-models/blob/main/unilinear/train.csv"
    click ULR_Test "https://github.com/lucirie/ml-regression-models/blob/main/unilinear/test.csv"

    click MLR_Notebook "https://github.com/lucirie/ml-regression-models/blob/main/multilinear/multilinear.ipynb"
    click MLR_Data "https://github.com/lucirie/ml-regression-models/blob/main/multilinear/Student_Performance.csv"

    click NLR_Notebook "https://github.com/lucirie/ml-regression-models/blob/main/nonlinear/nonlinear.ipynb"
    click NLR_Data "https://github.com/lucirie/ml-regression-models/blob/main/nonlinear/icecream.csv"

    click LOGR_Notebook "https://github.com/lucirie/ml-regression-models/blob/main/logistic/logistic.ipynb"
    click LOGR_Data "https://github.com/lucirie/ml-regression-models/blob/main/logistic/wdbc.data"

    click README "https://github.com/lucirie/ml-regression-models/blob/main/README.md"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef comp fill:#90EE90,stroke:#000,stroke-width:1px
    classDef viz fill:#FFA500,stroke:#000,stroke-width:1px
    classDef ext fill:#D3D3D3,stroke:#000,stroke-width:1px
```
