Skip to content

Commit

Permalink
DOC update README and doc index page
Browse files Browse the repository at this point in the history
  • Loading branch information
@ZhiningLiu1998
ZhiningLiu1998 committed Jun 15, 2024
1 parent 4571e52 commit f1bbbf0
Show file tree
Hide file tree
Showing 6 changed files with 284 additions and 192 deletions.
2 changes: 2 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,8 @@ instance/

# Sphinx documentation
docs/_build/
docs/source/auto_examples/
docs/source/back_references/

# PyBuilder
target/
Expand Down
196 changes: 99 additions & 97 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,106 +1,110 @@
![](https://raw.githubusercontent.com/ZhiningLiu1998/figures/master/imbalanced-ensemble/imbens-logo.png)

<!-- ![](https://raw.githubusercontent.com/ZhiningLiu1998/figures/master/imbalanced-ensemble/imbens_header.png) -->

<!-- ![](https://raw.githubusercontent.com/ZhiningLiu1998/figures/master/imbalanced-ensemble/example_gallery_snapshot_horizontal.png) -->

<h1 align="center">
IMBENS: Class-imbalanced Ensemble Learning in Python
</h1>



<p align="center">
<a href="https://github.com/psf/black">
<img src="https://img.shields.io/badge/code%20style-black-000000.svg">
</a>
<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 src='https://readthedocs.org/projects/imbalanced-ensemble/badge/?version=latest' alt='Documentation Status' />
</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://www.python.org/">
<img src="https://img.shields.io/pypi/pyversions/imbalanced-ensemble.svg">
</a>
<a href="https://pypi.org/project/imbalanced-ensemble/">
<img src="https://badge.fury.io/py/imbalanced-ensemble.svg">
</a>
<br>
<a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble">
<img src="https://img.shields.io/badge/Imbalanced-Ensemble-orange">
</a>
<a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble/stargazers">
<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://github.com/ZhiningLiu1998/imbalanced-ensemble/issues">
<img src="https://img.shields.io/github/issues/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>
<!-- <a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble/graphs/traffic">
<img src="https://visitor-badge.glitch.me/badge?page_id=ZhiningLiu1998.imbalanced-ensemble">
</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 -->
</p>
<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">
Documentation: <a href="https://imbalanced-ensemble.readthedocs.io/en/latest/">ReadTheDocs</a> |
Language: <a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble">English</a> / <a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble/blob/main/docs/README_CN.md">中文</a>
⏳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>

**Release:
<a href="https://pypi.org/project/imbalanced-ensemble/">PyPI</a> |
<a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble/tree/main/imbens">Source</a> |
<a href="https://pypi.org/project/imbalanced-ensemble/#files">Download</a> |
<a href="https://imbalanced-ensemble.readthedocs.io/en/latest/release_history.html">Changelog</a>
Links:
<a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble#5-min-quick-start-with-imbens">Getting Started</a> |
<a href="https://imbalanced-ensemble.readthedocs.io/">API Reference</a> |
<a href="https://imbalanced-ensemble.readthedocs.io/en/latest/auto_examples/index.html#">Examples</a> |
<a href="https://github.com/ZhiningLiu1998/imbalanced-ensemble#related-projects">Related Projects</a> |
<a href="https://zhuanlan.zhihu.com/p/376572330">知乎/Zhihu</a>
Paper:
<a href="https://arxiv.org/pdf/2111.12776.pdf">"IMBENS: Ensemble Class-imbalanced Learning in Python"</a>
<br>**

***IMBENS* (imported as `imbens`) is a Python library for quick implementation, modification, evaluation, and visualization of ensemble [learning from class-imbalanced data](https://github.com/ZhiningLiu1998/awesome-imbalanced-learning)**.
Currently, IMBENS includes **[over 15 ensemble imbalanced learning algorithms](#list-of-implemented-methods) (SMOTEBoost, SMOTEBagging, RUSBoost, EasyEnsemble, BalanceCascade, SelfPacedEnsemble, etc)** and also **[19 resampling methods](https://imbalanced-ensemble.readthedocs.io/en/latest/api/sampler/api.html) (SMOTE, ADASYN, TomekLinks, etc)** from [imbalance-learn](https://imbalanced-learn.org/stable/references/index.html#api).

**IMBENS is featured for:**

<!-- ***IMBENS*** is developed on top of [imbalanced-learn](https://github.com/scikit-learn-contrib/imbalanced-learn) (imblearn) and follows the API design of [scikit-learn](https://github.com/scikit-learn/scikit-learn). Compared to imblearn, IMBENS provides more powerful ensemble learning algorithms with ***multi-class learning*** support and many other **advanced features**: -->

<!-- The problem of learning from imbalanced data is known as imbalanced learning or long-tail learning (under multi-class scenario). See related papers/libraries/resources [here](https://github.com/ZhiningLiu1998/awesome-imbalanced-learning). -->
<!-- More algorithms will be included in the future. We also provide detailed documentation and examples across various algorithms. See full list of implemented methods [here](#list-of-implemented-methods).** -->
Currently, IMBENS includes **[over 15 ensemble imbalanced learning algorithms](#list-of-implemented-methods) (SMOTEBoost, SMOTEBagging, RUSBoost, EasyEnsemble, SelfPacedEnsemble, etc)** and **[19 over-/under-sampling methods](https://imbalanced-ensemble.readthedocs.io/en/latest/api/sampler/api.html) (SMOTE, ADASYN, TomekLinks, etc)** from [imbalance-learn](https://imbalanced-learn.org/stable/references/index.html#api).

<!-- - ⭐ **Please leave a <font color='orange'>STAR</font> if you like this project!** ⭐
- **If you find any bugs or have any suggestions, please consider opening an issue or a PR.**
- **We would greatly appreciate your contribution, and you will appear in the [Contributors✨](#contributors-)!** -->
<h2 align="left">🌈 IMBENS Highlights</h2>

<!-- **IMBENS is featured for:** -->
- &#x1F34E; **Unified, easy-to-use APIs with [documentation](https://imbalanced-ensemble.readthedocs.io/) and [examples](https://imbalanced-ensemble.readthedocs.io/en/latest/auto_examples/index.html#).**
- &#x1F34E; **Optimized performance with parallelization using [joblib](https://github.com/joblib/joblib).**
- &#x1F34E; **Powerful, customizable, interactive training [logging]((#customizing-training-log)) and [visualizer](#visualize-ensemble-classifiers).**
- &#x1F34E; **Full compatibility with [scikit-learn](https://scikit-learn.org/stable/) and [imbalanced-learn](https://imbalanced-learn.org/stable/).**
- &#x1F34E; **Off-the-shelf *multi-class* imbalanced learning by extending existing techniques.**
- 🧑‍💻 **Ease-of-use:** Unified, easy-to-use APIs with [documentation](https://imbalanced-ensemble.readthedocs.io/) and [examples](https://imbalanced-ensemble.readthedocs.io/en/latest/auto_examples/index.html#).
- 🚀 **Performance:** Optimized performance with parallelization using [joblib](https://github.com/joblib/joblib).
- 📊 **Benchmarking:** Running & comparing multiple models with our [visualizer](#visualize-ensemble-classifiers).
- 📺 **Monitoring:** Powerful, customizable, interactive training [logging]((#customizing-training-log)).
- 🪐 **Versatility:** Full compatibility with [scikit-learn](https://scikit-learn.org/stable/) and [imbalanced-learn](https://imbalanced-learn.org/stable/).
- 📈 **Functionality:** Extending existing techniques from binary to ***multi-class*** setting.

**IMBENS for class-imbalanced classification with <5 lines of code:**
### ✂️ **Use IMBENS for class-imbalanced classification with <5 lines of code:**

```python
# Train an SPE classifier
Expand All @@ -112,10 +116,9 @@ clf.fit(X_train, y_train)
y_pred = clf.predict(X_test)
```

**Citing IMBENS**
### 🤗 Citing IMBENS

The [IMBENS paper](https://arxiv.org/pdf/2111.12776.pdf) is available on arxiv.
If you use IMBENS in a scientific publication, we would appreciate citations to the following paper:
🍻 We appreciate your citation if you find our work helpful! The BibTeX entry:

```bib
@article{liu2023imbens,
Expand All @@ -126,15 +129,14 @@ If you use IMBENS in a scientific publication, we would appreciate citations to
}
```

**Contributing to IMBENS**
### 👯‍♂️ Contribute to IMBENS

Join us and become a contributor!
Please refer to the [contributing guidelines](https://github.com/ZhiningLiu1998/imbalanced-ensemble/blob/main/CONTRIBUTING.md).

## Table of Contents
<h2 align="left">📚 Table of Contents</h2>

- [Table of Contents](#table-of-contents)
- [Installation](#installation)
- [Highlights](#highlights)
- [List of implemented methods](#list-of-implemented-methods)
- [5-min Quick Start with IMBENS](#5-min-quick-start-with-imbens)
- [A minimal working example](#a-minimal-working-example)
Expand Down Expand Up @@ -176,7 +178,7 @@ imbalanced-ensemble requires following dependencies:
- [tqdm](https://tqdm.github.io/) (>=4.50.2)


## Highlights
<!-- ## Highlights
- &#x1F34E; ***Unified, easy-to-use API design.***
All ensemble learning methods implemented in IMBENS share a unified API design.
Expand All @@ -186,7 +188,7 @@ Similar to sklearn, all methods have functions (e.g., `fit()`, `predict()`, `pre
- &#x1F34E; ***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).
- &#x1F34E; ***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.
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
Expand Down
16 changes: 8 additions & 8 deletions docs/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@

# -- Project information -----------------------------------------------------

project = 'imbalanced-ensemble'
copyright = '2021, Zhining Liu'
author = 'Zhining Liu'
project = "imbalanced-ensemble"
copyright = "2021, Zhining Liu"
author = "Zhining Liu"


from imbens import __version__
Expand All @@ -36,7 +36,7 @@
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
# "sphinx.ext.doctest",
"sphinx.ext.intersphinx",
Expand All @@ -48,7 +48,7 @@
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
templates_path = ["_templates"]

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
Expand Down Expand Up @@ -110,13 +110,13 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
html_theme = "sphinx_rtd_theme"

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_static_path = ["_static"]


def setup(app):
app.add_css_file('css/my_theme.css')
app.add_css_file("css/my_theme.css")
16 changes: 16 additions & 0 deletions docs/source/doc_requirements.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
numpy>=1.16.0
scipy>=1.9.1
pandas>=2.1.1
joblib>=0.11
scikit-learn>=1.5.0
matplotlib>=3.3.2
seaborn>=0.13.2
tqdm>=4.50.2
sphinx
sphinx-gallery
sphinx_rtd_theme
pydata-sphinx-theme
numpydoc
sphinxcontrib-bibtex
torch
pytest
Loading

0 comments on commit f1bbbf0

Please sign in to comment.