Metadata-Version: 2.4
Name: unilvq
Version: 0.2.0
Summary: UniLVQ: A Unified Learning Vector Quantization Framework for Supervised Learning Tasks
Home-page: https://github.com/thieu1995/UniLVQ
Author: Thieu
Author-email: nguyenthieu2102@gmail.com
License: GPLv3
Project-URL: Documentation, https://unilvq.readthedocs.io/
Project-URL: Source Code, https://github.com/thieu1995/UniLVQ
Project-URL: Bug Tracker, https://github.com/thieu1995/UniLVQ/issues
Project-URL: Change Log, https://github.com/thieu1995/UniLVQ/blob/main/ChangeLog.md
Project-URL: Forum, https://t.me/+fRVCJGuGJg1mNDg1
Keywords: Learning Vector Quantization,LVQ,Prototype-based Learning,LVQ1,LVQ2.1,LVQ3,GLVQ,GRLVQ,RSLVQ,Distance Learning,Prototype Optimization,Supervised Learning,Classification,Regression,Multi-class Classification,Function Approximation,Regression with Prototypes,PyTorch,Scikit-learn,BaseEstimator,Gradient Descent Optimization,Model Wrapping,Open-source Machine Learning,Model Interpretability,Prototype Visualization,Hybrid Learning,Lightweight Models,Low-Data Regimes,Benchmarking,machine learning,artificial intelligence,generalization,optimization algorithms,model selection,Cross-validation,automl,parameter search,mealpy,search algorithm,optimization framework,global optimization,local optimization,Computational intelligence,Robust optimization
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Benchmark
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<=1.26.0,>=1.17.1
Requires-Dist: scipy>=1.7.1
Requires-Dist: scikit-learn>=1.2.1
Requires-Dist: pandas<2.2,>=1.3.5
Requires-Dist: permetrics>=2.0.0
Requires-Dist: torch>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest==7.1.2; extra == "dev"
Requires-Dist: pytest-cov==4.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.1; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


# UniLVQ: A Unified Learning Vector Quantization Framework for Supervised Learning Tasks

[![GitHub release](https://img.shields.io/badge/release-0.2.0-yellow.svg)](https://github.com/thieu1995/UniLVQ/releases)
[![PyPI version](https://badge.fury.io/py/unilvq.svg)](https://badge.fury.io/py/unilvq)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/unilvq.svg)
![PyPI - Downloads](https://img.shields.io/pypi/dm/unilvq.svg)
[![Downloads](https://pepy.tech/badge/unilvq)](https://pepy.tech/project/unilvq)
[![Tests & Publishes to PyPI](https://github.com/thieu1995/UniLVQ/actions/workflows/publish-package.yml/badge.svg)](https://github.com/thieu1995/UniLVQ/actions/workflows/publish-package.yml)
[![Documentation Status](https://readthedocs.org/projects/unilvq/badge/?version=latest)](https://unilvq.readthedocs.io/en/latest/?badge=latest)
[![Chat](https://img.shields.io/badge/Chat-on%20Telegram-blue)](https://t.me/+fRVCJGuGJg1mNDg1)
[![DOI](https://img.shields.io/badge/DOI-10.6084%2Fm9.figshare.29002685-blue)](https://doi.org/10.6084/m9.figshare.29002685)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

---

## 📌 Overview

**UniLVQ** is an open-source Python library that provides a unified, extensible, and user-friendly 
implementation of **Learning Vector Quantization (LVQ)** algorithms for supervised learning. 
It supports both **classification** and **regression** tasks, and is designed to work seamlessly with the **scikit-learn API**.

Built on top of **NumPy** and **PyTorch**, UniLVQ combines rule-based and neural-inspired LVQ variants, 
making it suitable for both research and practical applications.


## 🚀 Features

- ✅ Unified base API compatible with `scikit-learn`
- ✅ Traditional rule-based LVQ variants: LVQ1, LVQ2.1, LVQ3, Optimized LVQ1:
  + `Lvq1Classifier`, `Lvq2Classifier`, `Lvq3Classifier`, `OptimizedLvq1Classifier`
- ✅ Loss-based LVQ models: GLVQ, GRLVQ, LGMLVQ (PyTorch-based):
  + `GlvqClassifier`, `GlvqRegressor`, `GrlvqClassifier`, `GrlvqRegressor`, `LgmlvqClassifier`
- ✅ Support for both classification and regression
- ✅ Built-in support for early stopping, metric evaluation, data scaling
- ✅ Modular design for easy extension and customization
- ✅ CI-tested, documented, and easy to use


## 🧠 Supported Models

| Type                  | Algorithms                                       | Module         |
|-----------------------|--------------------------------------------------|----------------|
| Rule-based LVQ        | LVQ1, LVQ2.1, LVQ3, Optimized LVQ1 (Classifiers) | `classic_lvq.py` |
| Generalized LVQ       | GLVQ (Classifier, Regressor)                     | `glvq.py`        |
| Generalized Relevance LVQ | GRLVQ (Classifier, Regressor)                    | `grlvq.py`       |
| Local Generalized Matrix LVQ | LGMLVQ (Classifier)                              | `lgmlvq.py`      |


## 📖 Citation Request 

Please include these citations if you plan to use this library:

```bibtex
@software{thieu20250515UniLVQ,
  author       = {Nguyen Van Thieu},
  title        = {UniLVQ: A Unified Learning Vector Quantization Framework for Supervised Learning Tasks},
  month        = June,
  year         = 2025,
  doi         = {10.6084/m9.figshare.28802435},
  url          = {https://github.com/thieu1995/UniLVQ}
}
```

## 📦 Installation

Install the latest version from PyPI:

```bash
pip install unilvq
```

Verify installation:

```sh
$ python
>>> import unilvq
>>> unilvq.__version__
```

## 🚀 Quick Start

For classification problem using LVQ1 classifier:

```python
from unilvq import Lvq1Classifier
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.metrics import accuracy_score

# Load data
X, y = load_iris(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.3)

# Train LVQ1 model
model = Lvq1Classifier(n_prototypes_per_class=1, learning_rate=0.1, seed=42)
model.fit(X_train, y_train)

# Evaluate
y_pred = model.predict(X_test)
print("Accuracy:", accuracy_score(y_test, y_pred))
```

As can be seen, you do it like any model from Scikit-Learn library such as SVC, RF, DT,... Please read the [examples](/examples) folder for more use cases.


## 📚 Documentation

Documentation is available at: 👉 https://unilvq.readthedocs.io

You can build the documentation locally:

```shell
cd docs
make html
```

## 🧪 Testing
You can run unit tests using:

```shell
pytest tests/
```

## 🤝 Contributing
We welcome contributions to `UniLVQ`! If you have suggestions, improvements, or bug fixes, feel free to fork 
the repository, create a pull request, or open an issue.


## 📄 License
This project is licensed under the GPLv3 License. See the LICENSE file for more details.


## 📎 Official channels 

* 🔗 [Official source code repository](https://github.com/thieu1995/UniLVQ)
* 📘 [Official document](https://unilvq.readthedocs.io/)
* 📦 [Download releases](https://pypi.org/project/unilvq/) 
* 🐞 [Issue tracker](https://github.com/thieu1995/UniLVQ/issues) 
* 📝 [Notable changes log](/ChangeLog.md)
* 💬 [Official discussion group](https://t.me/+fRVCJGuGJg1mNDg1)

---

Developed by: [Thieu](mailto:nguyenthieu2102@gmail.com?Subject=UniLVQ_QUESTIONS) @ 2025
