📊 Project 2 — Supervised Data Classification Pipeline (Iris KNN)

DecodeLabs Industrial Training Kit (Batch 2026)

---

A production-grade, modular, and leak-free supervised machine learning pipeline that classifies Iris flowers using K-Nearest Neighbors (KNN). The project implements strict architectural design boundaries, robust cross-validation tuning, full unit/integration testing, and includes a premium dark-mode dashboard to analyze the evaluation metrics and plots.

---

📸 Interactive Dashboard Showroom & Analytical Views

Below are placeholders and theoretical explanations for each of the six interactive views available on the dark-mode dashboard.

1. Overview Tab

• Theoretical Context: This view provides a high-level summary of the training results. It displays top-level metrics (Test Accuracy, Macro F1, and Optimal K), the hyperparameter tuning curve indicating validation error rate variations across K, the annotated $3\times3$ Confusion Matrix, and the primary Petal Length vs. Petal Width decision boundary. This summary helps to evaluate if the model is well-balanced or displaying signs of underfitting/overfitting.
• Visual Screenshot:

2. EDA & Distributions

• Theoretical Context: Exploratory Data Analysis (EDA) is vital for understanding data characteristics. The Feature Correlation Matrix displays Pearson correlation coefficients between features: $$r = \frac{\sum (x_i - \bar{x})(y_i - \bar{y})}{\sqrt{\sum (x_i - \bar{x})^2 \sum (y_i - \bar{y})^2}}$$ The distribution plots show how features overlap across the target classes. Significant overlap indicates region ambiguity, suggesting the model may require multi-dimensional combinations to achieve clean separation.
• Visual Screenshot:

3. Pairwise Projections

• Theoretical Context: Since high-dimensional feature spaces cannot be fully visualized, we project the dataset onto six distinct 2D feature planes. This projection shows cluster densities, class boundaries, and classification results. Misclassified points are highlighted with red x markers, allowing researchers to diagnose whether errors occur in cluster boundaries or as isolated outliers.
• Visual Screenshot:

4. Decision Regions

• Theoretical Context: Decision boundaries illustrate how the KNN classifier divides the feature space. In this tab, we visualize boundaries for all six feature pairs by evaluating a dense grid of predictions while keeping the remaining features constant at their training means. Smaller values of $K$ yield complex, fragmented decision regions, while larger $K$ values smooth out the boundaries, showing the bias-variance trade-off in action.
• Visual Screenshot:

5. Model Evaluation

• Theoretical Context: A single accuracy score is often insufficient for evaluating class performance, particularly if class distributions are imbalanced. The Receiver Operating Characteristic (ROC) curve plots the True Positive Rate (Sensitivity) against the False Positive Rate (1 - Specificity) across different decision thresholds. The Area Under the Curve (AUC) indicates the probability that the model ranks a randomly chosen positive instance higher than a negative one.
• Visual Screenshot:

6. Theoretical Hub

• Theoretical Context: The Theoretical Hub serves as an educational reference. It covers the mathematical formulation of Euclidean distance, the Standard Scaling equation used to prevent features with larger scales from dominating the distance calculation, the mechanics of K-Fold Cross-Validation, and standard metrics like Precision, Recall, and F1-Score.
• Visual Screenshot:

---

🌟 Key Features

1. Strict Data Leakage Prevention: The Preprocessor object is designed to fit statistics strictly on training data only. We enforce this through custom validation APIs and a dedicated regression test suite.
2. Dynamic K-Tuning (Elbow Method): Evaluates odd K values (1 to 29) using 5-fold cross-validation on the training set. It implements a robust elbow heuristic that avoids noisy dips (like K=1 overfitting) and prioritizes stable minimums.
3. Advanced ML Diagnostics (23 Plots): Rejects single-metric evaluations. Enforces the generation of 23 diagnostic plots covering feature distributions, pairwise correlations, 2D decision boundary spaces, and OVR ROC curves.
4. Educational Theoretical Hub: Provides an interactive theoretical environment embedded in the dashboard explaining the mathematics of KNN distance metrics, K-tuning heuristics, data leakage, and evaluation math.
5. Seamless Local Server (server.py): A zero-dependency Python script that starts a local web server, automatically handles directory redirects (mapping / directly to /ui/ so you avoid plain text directory indexes), and instantly launches your default browser to view the dashboard.
6. Modern Glassmorphism Design: Custom dark-theme web dashboard using modern typography (Inter), custom-styled webkit scrollbars, hover-state animations, and neon glow effects.

---

📊 Diagnostics & Visualization Hub

The dashboard is structured into six interactive analytical views hosting a total of 23 diagnostic plots and interactive educational modules:

1. Overview Tab (3 Key Metrics & Plots)

• Test Accuracy Card & Macro F1 Card: Real-time evaluation indicators.
• Hyperparameter Tuning Curve: Shows 5-fold CV error rates over candidate $K$ values.
• Confusion Matrix: Fully annotated $3\times3$ class correctness matrix.
• Primary Decision Boundary: Displays boundaries projected on Petal Length vs. Petal Width.

2. EDA & Distributions (5 Plots)

• Feature Correlation Matrix: Heatmap displaying Pearson correlation coefficients across all 4 features.
• Sepal Length, Sepal Width, Petal Length, Petal Width Distributions: 4 class-wise histograms showing frequency counts and distribution overlapping.

3. Pairwise Projections (6 Plots)

• 6 distinct scatter plots displaying all possible 2D feature combinations.
• Outlines Train vs Test samples, and explicitly highlights Misclassified points using red cross markers.

4. Decision Regions (6 Plots)

• 6 distinct KNN decision boundary plots representing predictions across all 2D feature planes.
• Evaluates classification boundaries on meshgrids while holding remaining features constant at their training means.

5. Model Evaluation (3 Plots)

• One-vs-Rest (OvR) ROC Curves: 3 independent curves (Setosa, Versicolor, Virginica) showing True Positive Rate vs False Positive Rate across all classification thresholds with calculated Area Under the Curve (AUC) scores.

6. Theoretical Hub

• Formulates mathematical representations of distance metrics, scaling equations, cross-validation mechanisms, and classification metrics.

---

📐 Architecture & Data Flow

This project follows a strict pipeline orchestrator pattern where stage modules never import each other. All communications are mediated through the orchestrator (pipeline.py), making the stages isolated, highly modular, and testable in absolute isolation.

Pipeline Execution Flow

flowchart TD
    subgraph Data Ingestion
        A[data.py: load_dataset] -->|DatasetBundle| B[splitting.py: split_dataset]
    end
    subgraph Leak-Free Preprocessing
        B -->|Train/Test Splits| C[preprocessing.py: Preprocessor]
        C -->|Fit statistics on Train set ONLY| D[StandardScaler]
        C -->|Transform Train & Test separately| E[Scaled Arrays]
    end
    subgraph Hyperparameter Tuning
        E -->|Scaled Train set ONLY| F[tuning.py: select_k]
        F -->|5-Fold CV Elbow Method| G[Optimal K]
    end
    subgraph Model Training & Prediction
        G --> H[model.py: build_model]
        H -->|Fit Scaled Train set| I[KNeighborsClassifier]
        I -->|Predict Scaled Test set| J[Predictions]
    end
    subgraph Evaluation & Artifact Preservation
        J --> K[evaluation.py: evaluate]
        K --> L[outputs/evaluation_report.json]
        K --> M[outputs/confusion_matrix.png]
        K --> N[outputs/k_tuning_curve.png]
        K --> O[outputs/decision_boundary.png]
        K --> P[outputs/model_artifact.joblib]
    end

Loading

---

📂 Project Structure

Project2Decodelabs/
├── docs/                      # Architectural specs & screenshots
│   ├── ARCHITECTURE.md        # Architectural constraints & module boundaries
│   ├── PRD.md                 # Product Requirement Document
│   ├── TESTING.md             # Verification specifications
│   └── dashboard.png          # High-resolution dashboard screenshot
├── outputs/                   # Serialized outputs (gitignored except .gitkeep)
│   ├── confusion_matrix.png   # Transparent dark-themed Confusion Matrix plot
│   ├── decision_boundary.png  # Transparent dark-themed KNN Decision Boundary plot
│   ├── evaluation_report.json # Detailed precision/recall/F1 metrics in JSON
│   ├── k_tuning_curve.png     # Transparent dark-themed error rate curve
│   └── model_artifact.joblib  # Serialized Model & Preprocessing Pipeline
├── src/
│   └── project2/
│       ├── __init__.py
│       ├── config.py          # CLI Arguments and Configuration Dataclasses
│       ├── data.py            # Data Ingestion, validation, and balance checks
│       ├── preprocessing.py   # Leak-free Scaling Wrapper around StandardScaler
│       ├── splitting.py       # Shuffled, Stratified Shuffle Split
│       ├── tuning.py          # Dynamic K selection using K-Fold CV on training data
│       ├── model.py           # Model factory creating KNeighborsClassifier
│       ├── evaluation.py      # Detailed metrics and transparent plot generations
│       ├── pipeline.py        # Central Orchestrator compiling all modules
│       └── run.py             # Main Python CLI entrypoint
├── tests/                     # Exhaustive pytest verification suite
│   ├── test_data.py
│   ├── test_evaluation.py
│   ├── test_model.py
│   ├── test_no_leakage.py     # Explicit data-leakage regression tests
│   ├── test_pipeline_e2e.py   # End-to-end integration tests
│   ├── test_preprocessing.py
│   ├── test_splitting.py
│   └── test_tuning.py
├── ui/                        # Dashboard client files
│   ├── index.html             # Dashboard markup with modern glassmorphism
│   ├── script.js              # Fetching and populating evaluation metrics
│   └── styles.css             # Neon glow design, padding, & custom scrollbar
├── pyproject.toml             # Ruff lint and Pytest configurations
├── requirements.txt           # Python package dependencies
└── server.py                  # Local Python dashboard server & browser opener

---

🚀 Step-by-Step Quick Start

1. Set Up the Virtual Environment

Create a clean environment to isolate project dependencies.

# Navigate to the project root
cd Project2Decodelabs

# Create a virtual environment
python3 -m venv .venv

# Activate the virtual environment
# -> On Linux / macOS:
source .venv/bin/activate
# -> On Windows (Command Prompt):
# .venv\Scripts\activate
# -> On Windows (PowerShell):
# .venv\Scripts\Activate.ps1

2. Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

3. Execute the Machine Learning Pipeline

To run the end-to-end pipeline, use the main entrypoint. We use PYTHONPATH=src to tell Python to search inside the src directory.

PYTHONPATH=src python -m project2.run

Expected Console Output:

Loaded dataset: 150 samples, 4 features, 3 classes
Class balance: 50/50/50
Train/test split: 120 / 30 (stratified, seed=42)
Tuning K over 1..29 (odd only) via 5-fold CV on TRAIN ONLY...
Chosen K = 3 (Elbow region: sustained low error starting at K=3 (avoiding K=1))
Test Accuracy: 0.93 | Macro F1: 0.93
Confusion Matrix:
                  setosa  versicolor   virginica
setosa                10           0           0
versicolor             0          10           0
virginica              0           2           8
Artifacts written to outputs/

This generates model_artifact.joblib, evaluation_report.json, and the two transparent dark-themed plot files in outputs/.

4. Launch the Results Dashboard

Run the dashboard server directly using Python. This will start hosting the files and automatically open the dashboard in your default web browser.

python server.py

Note: The server runs on port 8000 by default. If you need to use a custom port (e.g. 8080), simply pass it as an argument:

python server.py 8080

---

🛠️ CLI Customization Options

You can customize the execution of the pipeline using CLI arguments without altering the codebase:

Argument	Type	Default Value	Description
--source	str	"iris"	Dataset source. Set to "iris" or path to a custom CSV file (must contain a target column).
--test-size	float	0.2	Fraction of the dataset held out for model evaluation (e.g., 0.3 for 30%).
--seed	int	42	Random state seed for splitting and reproducibility.
--k-min	int	1	Minimum odd range value of K neighbors to evaluate during tuning.
--k-max	int	29	Maximum odd range value of K neighbors to evaluate during tuning.
--cv-folds	int	5	Number of cross-validation folds to evaluate K parameter.
--output-dir	str	"outputs/"	Directory where evaluation reports, plots, and models are saved.

Example using custom parameters:

PYTHONPATH=src python -m project2.run --test-size 0.3 --seed 123 --k-max 15 --cv-folds 3

---

🧪 Running the Verification Suite

The project includes an extensive test suite verifying mathematical correctness, data isolation, and API integrity.

To execute the entire test suite, run:

PYTHONPATH=src pytest

To run the tests with a coverage report:

PYTHONPATH=src pytest --cov=src --cov-report=term-missing

🛡️ Leakage-Free Regression Tests (test_no_leakage.py)

To guarantee that model evaluations are completely honest and free of data leakage:

• Scaler State Isolation: Verifies that calling .transform() on test splits does not modify the scaler's internal metrics (mean/variance).
• Fit Isolation: Monkeypatches sklearn interfaces during a full pipeline run, asserting that the memory ID of test data is never passed to any fit method.
• Static Check: Enforces that the hyperparameter tuning script (tuning.py) does not contain or reference test variables.

---

🎓 Graduation Criteria (Definition of Done)

As part of the DecodeLabs Industrial Training qualification gate, this project satisfies the following conditions:

• Performance Gate: Test Accuracy $\ge 90%$ and Macro F1 $\ge 90%$.
• Robust Verification: $100%$ pass rate across all 16 unit, integration, and leakage regression tests.
• Linting Discipline: Zero warnings or errors when analyzed with Ruff.
• Reproducibility Guarantee: Given the same seed, runs generate identical serialized models and JSON reports byte-for-byte.