From f1bbbf00430133dd5720659cd7a9c1c62fbf9e7a Mon Sep 17 00:00:00 2001 From: ZhiningLiu1998 Date: Sat, 15 Jun 2024 02:02:40 -0700 Subject: [PATCH] DOC update README and doc index page --- .gitignore | 2 + README.md | 196 ++++++++++++------------- docs/source/conf.py | 16 +-- docs/source/doc_requirements.txt | 16 +++ docs/source/index.rst | 237 ++++++++++++++++++++----------- readthedocs.yml | 9 +- 6 files changed, 284 insertions(+), 192 deletions(-) create mode 100644 docs/source/doc_requirements.txt diff --git a/.gitignore b/.gitignore index 3229eff..fbcd846 100644 --- a/.gitignore +++ b/.gitignore @@ -70,6 +70,8 @@ instance/ # Sphinx documentation docs/_build/ +docs/source/auto_examples/ +docs/source/back_references/ # PyBuilder target/ diff --git a/README.md b/README.md index 6e0b803..4b44da5 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,110 @@ ![](https://raw.githubusercontent.com/ZhiningLiu1998/figures/master/imbalanced-ensemble/imbens-logo.png) - - -

IMBENS: Class-imbalanced Ensemble Learning in Python

- - -

- - - - - - - - CircleCI Status - - - Documentation Status - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - -

+ + + + + + + + + + + + + + + + + + + + + + + + + +
Status + + + + CircleCI Status + + Read the Docs + + + + + + + +
PyPI + + + + + + +
Traffic + + + + + + + + + + + +
Documentation + + + + + + + + +
Paper & Citation + + + + + + + + +
Language + + + + +

-Documentation: ReadTheDocs | -Language: English / 中文 +⏳Quick Start with our 5-minute Guide & Detailed Examples

-**Release: - PyPI | - Source | - Download | - Changelog - Links: - Getting Started | - API Reference | - Examples | - Related Projects | - 知乎/Zhihu - Paper: - "IMBENS: Ensemble Class-imbalanced Learning in Python" -
** - ***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:** - - - - - +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). - +

🌈 IMBENS Highlights

- -- 🍎 **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#).** -- 🍎 **Optimized performance with parallelization using [joblib](https://github.com/joblib/joblib).** -- 🍎 **Powerful, customizable, interactive training [logging]((#customizing-training-log)) and [visualizer](#visualize-ensemble-classifiers).** -- 🍎 **Full compatibility with [scikit-learn](https://scikit-learn.org/stable/) and [imbalanced-learn](https://imbalanced-learn.org/stable/).** -- 🍎 **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 @@ -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, @@ -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 +

📚 Table of Contents

-- [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) @@ -176,7 +178,7 @@ imbalanced-ensemble requires following dependencies: - [tqdm](https://tqdm.github.io/) (>=4.50.2) -## Highlights + + + + + + + Documentation + + + + + + + + + + + + + + + + + Paper & Citation + + + + + + + + + + + + + + + + + Language + + + + + + + + + + + +.. .. raw:: html + +..

+.. Links: +.. [Github] +.. [Gallery] +.. [PyPI] +.. [Changelog] +.. [知乎/Zhihu] +.. [中文README] +.. [arXiv] +..

.. raw:: html -

- [Github] - [Gallery] - [PyPI] - [Changelog] - [Source] - [Download] - [知乎/Zhihu] - [中文README] - [arXiv] +

+ ⏳Quick Start with our 5-minute Guide & Detailed Examples

-**Date**: |today| **Version**: |version| +**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 <#list-of-implemented-methods>`_ (SMOTEBoost, SMOTEBagging, RUSBoost, EasyEnsemble, SelfPacedEnsemble, etc) and `19 over-/under-sampling methods `_ (SMOTE, ADASYN, TomekLinks, etc) from `imbalance-learn `_. -**Paper**: `IMBENS: Ensemble Class-imbalanced Learning in Python `_ +🌈 **IMBENS Highlights** -**Citing US** +- 🧑‍💻 **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 <#visualize-ensemble-classifiers>`_. +- 📺 **Monitoring:** Powerful, customizable, interactive training `logging <#customizing-training-log>`_. +- 🪐 **Versatility:** Full compatibility with `scikit-learn `_ and `imbalanced-learn `_. +- 📈 **Functionality:** Extending existing techniques from binary to **multi-class** setting. -If you find IMBENS helpful in your work or research, we would greatly appreciate citations to the following paper [`PDF <(https://arxiv.org/pdf/2111.12776.pdf>`_]:: - - @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} - } +✂️ **Use IMBENS for class-imbalanced classification with <5 lines of code:** + +.. code-block:: python + # Train an SPE classifier + from imbens.ensemble import SelfPacedEnsembleClassifier + clf = SelfPacedEnsembleClassifier(random_state=42) + clf.fit(X_train, y_train) -**imbalanced-ensemble** (IMBENS, imported as ``imbens``) is a Python toolbox -for quick implementation, modification, evaluation, and visualization of ensemble learning -algorithms for class-imbalanced data. -It was built on the basis of `scikit-learn `__ -and `imbalanced-learn `__. -IMBENS includes more than 15 ensemble imbalanced learning (EIL) algorithms, from the -classical SMOTEBoost (2003) and RUSBoost (2010) to recent SPE (2020), from resampling-based -methods to cost-sensitive ensemble learning. - -**IMBENS is featured for:** - -- Unified, easy-to-use APIs, detailed `documentation `_ and `examples `_. -- Capable for out-of-the-box *multi-class* imbalanced (long-tailed) learning. -- Optimized performance with parallelization when possible using - `joblib `__. -- Powerful, customizable, interactive training logging and visualizer. -- Full compatibility with other popular packages like - `scikit-learn `__ and - `imbalanced-learn `__. + # 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: + +.. code-block:: bibtex + + @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} + } **API Demo:** diff --git a/readthedocs.yml b/readthedocs.yml index 774ea5f..cf4c10c 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -3,10 +3,15 @@ version: 2 +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + sphinx: configuration: docs/source/conf.py python: - version: 3.8 install: - - requirements: docs/requirements.txt + - requirements: docs/source/doc_requirements.txt