<!--  -->
<h1 align="center">
IMBENS: Class-imbalanced Ensemble Learning in Python
</h1>
<table align="center">
<tr>
<td>Status</td>
<td>
<a href="https://codecov.io/gh/ZhiningLiu1998/imbalanced-ensemble">
<img src="https://codecov.io/gh/ZhiningLiu1998/imbalanced-ensemble/branch/main/graph/badge.svg?token=46Y73QPA68"></a>
<a href='https://dl.circleci.com/status-badge/redirect/gh/ZhiningLiu1998/imbalanced-ensemble/tree/main'>
<img src='https://dl.circleci.com/status-badge/img/gh/ZhiningLiu1998/imbalanced-ensemble/tree/main.svg?style=shield' alt='CircleCI Status'></a>
<a href='https://imbalanced-ensemble.readthedocs.io/en/latest/?badge=latest'>
<img alt="Read the Docs" src="https://img.shields.io/readthedocs/imbalanced-ensemble"></a>
<!-- <img src='https://readthedocs.org/projects/imbalanced-ensemble/badge/?version=latest'></a> -->
<a href="https://github.com/psf/black">
<img src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
<a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble/blob/master/LICENSE">
<img src="https://img.shields.io/github/license/ZhiningLiu1998/imbalanced-ensemble"></a>
<a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble/issues">
<img src="https://img.shields.io/github/issues/ZhiningLiu1998/imbalanced-ensemble?logo=github"></a>
</td>
</tr>
<tr>
<td>PyPI</td>
<td>
<a href="https://pypi.org/project/imbalanced-ensemble/">
<img src="https://img.shields.io/badge/PyPi-imbalanced--ensemble-3775A9?logo=pypi&labelColor=white"></a>
<a href="https://pypi.org/project/imbalanced-ensemble/">
<img src="https://img.shields.io/pypi/v/imbalanced-ensemble?logo=pypi&label=version&labelColor=white&color=3775A9"></a>
<a href="https://www.python.org/">
<img src="https://img.shields.io/pypi/pyversions/imbalanced-ensemble.svg?logo=python&labelColor=white"></a>
</td>
</tr>
<tr>
<td>Traffic</td>
<td>
<a href="https://pepy.tech/project/imbalanced-ensemble">
<img src="https://img.shields.io/github/stars/ZhiningLiu1998/imbalanced-ensemble"></a>
<a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble/network/members">
<img src="https://img.shields.io/github/forks/ZhiningLiu1998/imbalanced-ensemble"></a>
<a href="https://pepy.tech/project/imbalanced-ensemble">
<img src="https://pepy.tech/badge/imbalanced-ensemble"></a>
<a href="https://pepy.tech/project/imbalanced-ensemble">
<img src="https://pepy.tech/badge/imbalanced-ensemble/month"></a>
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
<a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble#contributors-"><img src="https://img.shields.io/badge/all_contributors-5-orange.svg"></a>
<!-- ALL-CONTRIBUTORS-BADGE:END -->
</td>
</tr>
<tr>
<td>Documentation</td>
<td>
<a href="https://imbalanced-ensemble.readthedocs.io/en/latest/">
<img src="https://img.shields.io/badge/ReadTheDoc-Latest-green?logo=readthedocs&labelColor=376681"></a>
<a href="https://imbalanced-ensemble.readthedocs.io/en/latest/release_history.html">
<img src="https://img.shields.io/badge/Doc-Changelog-blue?logo=readthedocs"></a>
<a href="https://imbalanced-ensemble.readthedocs.io/en/latest/auto_examples/index.html#">
<img src="https://img.shields.io/badge/Doc-Examples & Gallery-blue?logo=readthedocs"></a>
<a href="https://imbalanced-ensemble.readthedocs.io/en/latest/api/ensemble/api.html">
<img src="https://img.shields.io/badge/Doc-API Reference-blue?logo=readthedocs"></a>
</td>
</tr>
<tr>
<td>Paper & Citation</td>
<td>
<a href="https://arxiv.org/abs/2111.12776">
<img src="https://img.shields.io/badge/arXiv-2111.12776-B31B1B?logo=arXiv"></a>
<a href="https://arxiv.org/pdf/2111.12776">
<img src="https://img.shields.io/badge/arXiv-PDF-B31B1B?logo=arXiv"></a>
<a href="https://zhuanlan.zhihu.com/p/376572330">
<img src="https://img.shields.io/badge/Blog-知乎/Zhihu-0084ff?logo=Zhihu&labelColor=white"></a>
<a href="https://scholar.google.com/scholar?q=IMBENS%3A+Ensemble+class-imbalanced+learning+in+Python">
<img src="https://img.shields.io/badge/Citation-Bibtex-4285F4?logo=googlescholar&labelColor=white"></a>
</td>
</tr>
<tr>
<td>Language</td>
<td>
<a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble">
<img src="https://img.shields.io/badge/README-English-blue?logo=github&labelColor=black"></a>
<a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble/blob/main/docs/README_CN.md">
<img src="https://img.shields.io/badge/README-中文-blue?logo=github&labelColor=black"></a>
</td>
</tr>
</table>
<h3 align="center">
⏳Quick Start with our <a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble#5-min-quick-start-with-imbens">5-minute Guide</a> & <a href="https://imbalanced-ensemble.readthedocs.io/en/latest/auto_examples/index.html#">Detailed Examples</a>
</h3>
IMBENS (imported as imbens) is a Python library for quick implementation, modification, evaluation, and visualization of ensemble learning from class-imbalanced data.
Currently, IMBENS includes over 15 ensemble imbalanced learning algorithms (SMOTEBoost, SMOTEBagging, RUSBoost, EasyEnsemble, SelfPacedEnsemble, etc) and 19 over-/under-sampling methods (SMOTE, ADASYN, TomekLinks, etc) from imbalance-learn.
<h2 align="left">🌈 IMBENS Highlights</h2>
- 🧑💻 Ease-of-use: Unified, easy-to-use APIs with documentation and examples.
- 🚀 Performance: Optimized performance with parallelization using joblib.
- 📊 Benchmarking: Running & comparing multiple models with our visualizer.
- 📺 Monitoring: Powerful, customizable, interactive training logging.
- 🪐 Versatility: Full compatibility with scikit-learn and imbalanced-learn.
- 📈 Functionality: Extending existing techniques from binary to multi-class setting.
✂️ Use IMBENS for class-imbalanced classification with <5 lines of code:
# Train an SPE classifier
from imbens.ensemble import SelfPacedEnsembleClassifier
clf = SelfPacedEnsembleClassifier(random_state=42)
clf.fit(X_train, y_train)
# Predict with an SPE classifier
y_pred = clf.predict(X_test)
🤗 Citing IMBENS
🍻 We appreciate your citation if you find our work helpful! The BibTeX entry:
@article{liu2023imbens,
title={IMBENS: Ensemble Class-imbalanced Learning in Python},
author={Liu, Zhining and Kang, Jian and Tong, Hanghang and Chang, Yi},
journal={arXiv preprint arXiv:2111.12776},
year={2023}
}
👯♂️ Contribute to IMBENS
Join us and become a contributor!
Please refer to the contributing guidelines.
<h2 align="left">📚 Table of Contents</h2>
Installation
It is recommended to use pip for installation.
Please make sure the latest version is installed to avoid potential problems:
$ pip install imbalanced-ensemble # normal install
$ pip install --upgrade imbalanced-ensemble # update if needed
Or you can install imbalanced-ensemble by clone this repository:
$ git clone https://github.com/ZhiningLiu1998/imbalanced-ensemble.git
$ cd imbalanced-ensemble
$ pip install .
imbalanced-ensemble requires following dependencies:
<!-- ## Highlights
- 🍎 ***Unified, easy-to-use API design.***
All ensemble learning methods implemented in IMBENS share a unified API design.
Similar to sklearn, all methods have functions (e.g., `fit()`, `predict()`, `predict_proba()`) that allow users to deploy them with only a few lines of code.
- 🍎 ***Extended functionalities, wider application scenarios.***
*All methods in IMBENS are ready for **multi-class imbalanced classification**.* We extend binary ensemble imbalanced learning methods to get them to work under the multi-class scenario. Additionally, for supported methods, we provide more training options like class-wise resampling control, balancing scheduler during the ensemble training process, etc.
- 🍎 ***Detailed training log, quick intuitive visualization.***
We provide additional parameters (e.g., `eval_datasets`, `eval_metrics`, `training_verbose`) in `fit()` for users to control the information they want to monitor during the ensemble training. We also implement an [`EnsembleVisualizer`](https://imbalanced-ensemble.readthedocs.io/en/latest/api/visualizer/_autosummary/imbens.visualizer.ImbalancedEnsembleVisualizer.html) to quickly visualize the ensemble estimator(s) for providing further information/conducting comparison. See an example [here](https://imbalanced-ensemble.readthedocs.io/en/latest/auto_examples/basic/plot_basic_example.html#sphx-glr-auto-examples-basic-plot-basic-example-py).
- 🍎 ***Wide compatiblilty.***
IMBENS is designed to be compatible with [scikit-learn](https://scikit-learn.org/stable/) (sklearn) and also other compatible projects like [imbalanced-learn](https://imbalanced-learn.org/stable/). Therefore, users can take advantage of various utilities from the sklearn community for data processing/cross-validation/hyper-parameter tuning, etc. -->
<!-- ## Background
Class-imbalance (also known as the long-tail problem in multi-class) is the fact that the classes are not represented equally in a classification problem, which is quite common in practice. For instance, fraud detection, prediction of rare adverse drug reactions and prediction gene families. Failure to account for the class imbalance often causes inaccurate and decreased predictive performance of many classification algorithms.
Imbalanced learning (IL) aims to tackle the class imbalance problem to learn an unbiased model from imbalanced data. This is usually achieved by changing the training data distribution by resampling or reweighting. However, naive resampling or reweighting may introduce bias/variance to the training data, especially when the data has class-overlapping or contains noise.
Ensemble imbalanced learning (EIL) is known to effectively improve typical IL solutions by combining the outputs of multiple classifiers, thereby reducing the variance introduce by resampling/reweighting. -->
List of implemented methods
Currently (v0.1.3, 2021/06), 16 ensemble imbalanced learning methods were implemented:
(Click to jump to the document page)
