Skip to main content

Clustering-based over-sampling.

Project description

Travis Codecov CircleCI ReadTheDocs PythonVersion Pypi Conda DOI Black


Implementation of a general interface for clustering based over-sampling algorithms as described in [1], [2]. It is compatible with scikit-learn and imbalanced-learn.


Installation documentation, API documentation, and examples can be found on the documentation.


cluster-over-sampling is tested to work under Python 3.6+. The dependencies are the following:

  • numpy(>=1.1)
  • scikit-learn(>=0.21)
  • imbalanced-learn(>=0.6.2)

Optional dependencies for SOMO and Geometric SOMO are the following:

  • som-learn(>=0.1.1)
  • geometric-smote(>=0.1.3)

Additionally, to run the examples, you need matplotlib(>=2.0.0) and pandas(>=0.22).


cluster-over-sampling is currently available on the PyPi’s repository and you can install it via pip:

pip install -U cluster-over-sampling

The package is released also in Anaconda Cloud platform:

conda install -c algowit cluster-over-sampling

If you prefer, you can clone it and run the file. Use the following commands to get a copy from GitHub and install all dependencies:

git clone
cd cluster-over-sampling
pip install .

Or install using pip and GitHub:

pip install -U git+


After installation, you can use pytest to run the test suite:

make test


If you use cluster-over-sampling in a scientific publication, we would appreciate citations to any of the following papers:

  doi = {10.1016/j.eswa.2017.03.073},
  url = {},
  year = {2017},
  month = oct,
  publisher = {Elsevier {BV}},
  volume = {82},
  pages = {40--52},
  author = {Georgios Douzas and Fernando Bacao},
  title = {Self-Organizing Map Oversampling ({SOMO}) for imbalanced data set learning},
  journal = {Expert Systems with Applications}

  doi = {10.1016/j.ins.2018.06.056},
  url = {},
  year = {2018},
  month = oct,
  publisher = {Elsevier {BV}},
  volume = {465},
  pages = {1--20},
  author = {Georgios Douzas and Fernando Bacao and Felix Last},
  title = {Improving imbalanced learning through a heuristic oversampling method based on k-means and {SMOTE}},
  journal = {Information Sciences}

Learning from class-imbalanced data continues to be a common and challenging problem in supervised learning as standard classification algorithms are designed to handle balanced class distributions. While different strategies exist to tackle this problem, methods which generate artificial data to achieve a balanced class distribution are more versatile than modifications to the classification algorithm. SMOTE algorithm [3], as well as any other over-sampling method based on the SMOTE mechanism, generates synthetic samples along line segments that join minority class instances. SMOTE addresses only the issue of between-classes imbalance. On the other hand, by clustering the input space and applying any over-sampling algorithm for each resulting cluster with appropriate resampling ratio, the within-classes imbalanced issue can be addressed. SOMO [1] and KMeans-SMOTE [2] are specific realizations of this approach.


[1](1, 2) G. Douzas, F. Bacao, “Self-Organizing Map Oversampling (SOMO) for imbalanced data set learning”, Expert Systems with Applications, vol. 82, pp. 40-52, 2017.
[2](1, 2) G. Douzas, F. Bacao, F. Last, “Improving imbalanced learning through a heuristic oversampling method based on k-means and SMOTE”, Information Sciences, vol. 465, pp. 1-20, 2018.
[3]N. V. Chawla, K. W. Bowyer, L. O. Hall, W. P. Kegelmeyer, “SMOTE: synthetic minority over-sampling technique”, Journal of Artificial Intelligence Research, vol. 16, pp. 321-357, 2002.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cluster-over-sampling-0.2.6.tar.gz (11.0 MB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page