Metadata-Version: 2.4
Name: multimodel_analysis
Version: 0.0.4
Summary: A Python Package for Automatic Multi-Model Analysis (Classification & Regression)
Author: Uditya Narayan Tiwari
Author-email: tiwarimerit@gmail.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: scikit-learn
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🚀 MultiModel Analysis

<div align="center">

<img src="multi_modelml.png" alt="MultiModel Analysis Banner" width="100%"/>

### **Train • Evaluate • Compare • Visualize Multiple Machine Learning Models in Minutes**

A lightweight, robust Python library that automates model benchmarking, metric evaluation, and visualization for both **Classification** and **Regression** tasks.

<p align="center">

[![PyPI Version](https://img.shields.io/pypi/v/multimodel_analysis.svg)](https://pypi.org/project/multimodel-analysis/)
[![Python](https://img.shields.io/pypi/pyversions/multimodel_analysis.svg)](https://pypi.org/project/multimodel-analysis/)
[![Downloads](https://img.shields.io/pypi/dm/multimodel-analysis)](https://pypi.org/project/multimodel-analysis/)
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
[![Built With](https://img.shields.io/badge/Built%20With-Scikit--Learn-orange)](https://scikit-learn.org/)
[![Open Source](https://img.shields.io/badge/Open%20Source-%E2%9D%A4-blue)]()

</p>

**Created & Maintained by [Uditya Narayan Tiwari](https://github.com/udityamerit)**

</div>

---

## 📖 Table of Contents

- [Overview](#-overview)
- [Why MultiModel Analysis?](#-why-multimodel-analysis)
- [Key Features](#-key-features)
- [Supported Models](#-supported-models)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
  - [Classification Example](#classification-workflow)
  - [Regression Example](#regression-workflow)
- [End-to-End Workflow](#-end-to-end-workflow)
- [API Reference](#-api-reference)
  - [MultiModelClassifier](#multimodelclassifier)
  - [MultiModelRegressor](#multimodelregressor)
- [Requirements](#-requirements)
- [License & Citation](#-license--author)

---

## 📖 Overview

Selecting the optimal Machine Learning model requires training, tuning, and comparing multiple algorithms. Traditionally, this process demands writing repetitive boilerplate code for:
- Splitting datasets and feature scaling
- Fitting each estimator individually
- Extracting evaluation metrics (Accuracy, F1, MAE, R², etc.)
- Generating figures (Confusion Matrices, ROC Curves, Scatter plots)
- Ranking models to recommend the best performer

**MultiModel Analysis** automates this entire pipeline into a clean, intuitive, production-grade interface. With just a few lines of code, you can train 8 classifiers or 7 regressors, evaluate their performance, generate publication-ready plots, and receive an instant recommendation for the best model.

---

## 💡 Why MultiModel Analysis?

Instead of writing repetitive, error-prone code like this:

```python
# Traditional Workflow (100+ lines of repetitive code)
model1.fit(X_train, y_train)
model2.fit(X_train, y_train)
pred1 = model1.predict(X_test)
pred2 = model2.predict(X_test)

acc1 = accuracy_score(y_test, pred1)
f1_1 = f1_score(y_test, pred1, average='weighted')
# ... Repeat for every model & plot manually
```

Simply write:

```python
from multimodel_analysis import MultiModelClassifier

# Automated Benchmarking Workflow
classifier = MultiModelClassifier(X, y, scaled_data=True)
results = classifier.run_all_models()
classifier.get_summary(results)
```

---

## ✨ Key Features

- ⚡ **Automated Multi-Model Benchmarking**: Train up to 8 classifiers or 7 regressors simultaneously.
- 🎯 **Multiclass & String Target Support**: Built-in `LabelEncoder` handles string targets (e.g. `'Cat'`, `'Dog'`), multi-class target variables, and binary targets smoothly.
- 📊 **Multiclass ROC-AUC Calculation**: Accurate One-vs-Rest ROC-AUC computation (`multi_class='ovr'`) for multiclass classification without silent metric failures.
- 📏 **DataFrame Feature Integrity**: Preserves pandas DataFrame column names and indices during standard scaling.
- 🛡️ **Fault-Tolerant Execution**: Exception handling insulates model fitting so a single failing estimator will not crash the overall benchmark.
- 🖥️ **Cross-Platform Safe**: Unicode print fallbacks prevent `charmap` / terminal encoding errors on Windows, macOS, and Linux console environments.
- 📈 **Publication-Ready Visualizations**: Automatically generates styled Confusion Matrices with class names, ROC curves, Regression error scatter plots, and metric bar charts.

---

## 🤖 Supported Models

### 🎯 Classification Models (`MultiModelClassifier`)
1. **Logistic Regression**
2. **Support Vector Machine (SVC)**
3. **K-Nearest Neighbors (KNN)**
4. **Decision Tree Classifier**
5. **Random Forest Classifier**
6. **Gaussian Naive Bayes**
7. **Gradient Boosting Classifier**
8. **AdaBoost Classifier**

### 📈 Regression Models (`MultiModelRegressor`)
1. **Linear Regression**
2. **Lasso Regression**
3. **Ridge Regression**
4. **Support Vector Regression (SVR)**
5. **Decision Tree Regressor**
6. **Random Forest Regressor**
7. **Gradient Boosting Regressor**

*(Note: `MultiModelRegressior` is retained as a backwards-compatible alias for legacy code).*

---

## 📦 Installation

### From PyPI (Recommended)

```bash
pip install multimodel-analysis
```

Upgrade to the latest version:

```bash
pip install --upgrade multimodel-analysis
```

### From GitHub Source

```bash
pip install git+https://github.com/udityamerit/Multimodel-Analysis-Pacakge.git
```

---

## 🚀 Quick Start

### Classification Workflow

```python
import pandas as pd
from multimodel_analysis import MultiModelClassifier

# 1. Load your dataset
df = pd.read_csv("dataset.csv")
X = df.drop("target", axis=1)
y = df["target"]  # Can be numeric or strings like 'Class_A', 'Class_B', 'Class_C'

# 2. Initialize classifier with feature scaling & stratified train/test split
classifier = MultiModelClassifier(
    X=X, 
    y=y, 
    test_size=0.3, 
    scaled_data=True, 
    random_state=42
)

# 3. Train all classification models
results = classifier.run_all_models()

# 4. Show tabular summary and visualizations
classifier.show_tabular_report(results)
classifier.plot_confusion_matrices(results)
classifier.plot_roc_curves(results)
classifier.plot_comparison(results)

# Or run all reporting functions in one call:
# classifier.get_summary(results)
```

---

### Regression Workflow

```python
import pandas as pd
from multimodel_analysis import MultiModelRegressor

# 1. Load housing dataset
df = pd.read_csv("housing.csv")
X = df.drop("Price", axis=1)
y = df["Price"]

# 2. Initialize regressor
regressor = MultiModelRegressor(
    X=X, 
    y=y, 
    test_size=0.3, 
    scaled_data=True, 
    random_state=42
)

# 3. Train all regression models
results = regressor.run_all_models()

# 4. Display report table & plots
regressor.show_tabular_report(results)
regressor.plot_true_vs_predicted(results)
regressor.plot_comparison(results)
```

---

## 🏗 End-to-End Workflow

```mermaid
flowchart LR
    A["📂 Load Dataset (X, y)"] --> B["🧹 Target & Data Preprocessing"]
    B --> C["🏷 LabelEncoder (String & Multiclass)"]
    C --> D{"⚙️ Feature Scaling?"}
    D -->|Enabled| E["📏 StandardScaler (Preserves Columns)"]
    D -->|Disabled| F["➡️ Raw Features"]
    E --> G["✂️ Stratified Train / Test Split"]
    F --> G
    G --> H{"🎯 Machine Learning Task"}
    H -->|Classification| I["🤖 Train 8 Classifiers"]
    H -->|Regression| J["📈 Train 7 Regressors"]
    I --> K["📊 Compute Accuracy, F1, ROC-AUC (OVR)"]
    J --> L["📈 Compute MAE, MSE, RMSE, R² Score"]
    K --> M["📈 Generate Figures & Tabular Benchmark"]
    L --> M
    M --> N["🏆 Recommend Best Model"]
```

---

## 📚 API Reference

### `MultiModelClassifier`

```python
MultiModelClassifier(X, y, test_size=0.3, scaled_data=False, random_state=42, stratify=True)
```

#### Parameters:
- `X`: *DataFrame or array-like of shape (n_samples, n_features)* — Feature matrix.
- `y`: *Series or array-like of shape (n_samples,)* — Target labels (numeric or categorical strings).
- `test_size`: *float, default=0.3* — Proportion of dataset for test split.
- `scaled_data`: *bool, default=False* — Fits and applies `StandardScaler` to features.
- `random_state`: *int, default=42* — Random seed for reproducibility.
- `stratify`: *bool, default=True* — Enables stratified splitting for balanced class ratios.

#### Key Methods:
- `.run_all_models()`: Fits all classification algorithms and returns evaluated metric tuples.
- `.show_tabular_report(models)`: Prints clean comparison table sorted by Accuracy and recommends the top model.
- `.plot_confusion_matrices(models)`: Displays styled confusion matrix heatmaps with actual class labels.
- `.plot_roc_curves(models)`: Plots combined ROC curves and AUC scores.
- `.plot_comparison(models)`: Generates metric comparison bar plots (Accuracy, Precision, Recall, F1).
- `.get_summary(models)`: Runs complete reporting and plotting pipeline.

---

### `MultiModelRegressor`

```python
MultiModelRegressor(X, y, test_size=0.3, scaled_data=False, random_state=42)
```

#### Parameters:
- `X`: *DataFrame or array-like of shape (n_samples, n_features)* — Feature matrix.
- `y`: *Series or array-like of shape (n_samples,)* — Continuous target variable.
- `test_size`: *float, default=0.3* — Proportion of dataset for test split.
- `scaled_data`: *bool, default=False* — Fits and applies `StandardScaler` to features.
- `random_state`: *int, default=42* — Random seed for reproducibility.

#### Key Methods:
- `.run_all_models()`: Fits all regressor algorithms and returns evaluation metric tuples.
- `.show_tabular_report(models)`: Displays tabular report sorted by $R^2$ Score and recommends the top regressor.
- `.plot_true_vs_predicted(models)`: Displays True vs Predicted value scatter plots with perfect prediction reference line.
- `.plot_comparison(models)`: Displays $R^2$ score bar plot comparison across models.
- `.get_summary(models)`: Runs complete reporting pipeline.

---

## 📚 Requirements

| Requirement | Supported Version |
|-------------|-------------------|
| **Python** | `>= 3.8` |
| **NumPy** | `*` |
| **Pandas** | `*` |
| **Matplotlib** | `*` |
| **Seaborn** | `*` |
| **Scikit-Learn** | `*` |

---

## 📜 License & Author

Distributed under the **Apache 2.0 License**. See `LICENSE` for more information.

**Author & Maintainer:**  
Uditya Narayan Tiwari  
📧 Email: [tiwarimerit@gmail.com](mailto:tiwarimerit@gmail.com)  
🌐 GitHub: [@udityamerit](https://github.com/udityamerit)  
📦 PyPI: [multimodel-analysis](https://pypi.org/project/multimodel-analysis/)
