redistributor 1.0.0

A tool for automatic transformation of empirical data distributions

Redistributor

Redistributor is a Python package which forces a collection of scalar samples to follow a desired distribution. When given independent and identically distributed samples of some random variable $S$ and the continuous cumulative distribution function of some desired target $T$, it provably produces a consistent estimator of the transformation $R$ which satisfies $R(S)=T$ in distribution. As the distribution of $S$ or $T$ may be unknown, we also include algorithms for efficiently estimating these distributions from samples. This allows for various interesting use cases in image processing, where Redistributor serves as a remarkably simple and easy-to-use tool that is capable of producing visually appealing results. The package is implemented in Python and is optimized to efficiently handle large data sets, making it also suitable as a preprocessing step in machine learning.

Matching colors of a reference image – one of the use cases of Redistributor

Installation

pip install redistributor

Quick-start

from redistributor import Redistributor as R
from redistributor import LearnedDistribution as L
from scipy.stats import dgamma, norm

S = dgamma(7).rvs(size=1000)  # Samples from source distribution
target = norm(0, 1)  # In this example, target is set explicitly
r = R(source=L(S), target=target)  # Estimate the transformation
output = r.transform(S)  # Data now follows the target distribution

More in examples.ipynb. Examples for image processing are in examples-images.ipynb.

Documentation

Documentation is available in docs folder.

News & Changelog

• :hammer: Package is still under development
• 2024.07 - Preprint on ArXiv updated with new results
• 2024.07 - Package released on PyPi.org :tada:
• 2024.07 - Repository mirrored to GitHub for easier access of the community
• 2023.10 - Added code examples of image processing
• 2022.10 - Preprint published on ArXiv :tada:
• 2022.09 - Redistributor v1.0 (complete rewrite)
• 2021.10 - Redistributor v0.2 (generalization to arbitrary source & target)
• 2018.08 - Introducing Redistributor (generalization to arbitrary target)
• 2018.07 - Introducing Gaussifier package (now deprecated)

How to cite

If you use Redistributor in your research, please cite the following paper:

@article{harar2022redistributor,
  title={Redistributor: Transforming Empirical Data Distributions},
  author={Harar, P. and Elbrächter, D. and Dörfler, M. and Johnson, K.},
  eprinttype={ArXiv},
  eprint={2210.14219}
}

License

This project is licensed under the terms of the MIT license. See license.txt for details.