diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 126 |
1 files changed, 68 insertions, 58 deletions
@@ -2,43 +2,65 @@ [](https://badge.fury.io/py/POT) [](https://anaconda.org/conda-forge/pot) -[](https://travis-ci.org/rflamary/POT) -[](http://pot.readthedocs.io/en/latest/?badge=latest) +[](https://github.com/PythonOT/POT/actions) +[](https://codecov.io/gh/PythonOT/POT) [](https://pepy.tech/project/pot) [](https://anaconda.org/conda-forge/pot) -[](https://github.com/rflamary/POT/blob/master/LICENSE) +[](https://github.com/PythonOT/POT/blob/master/LICENSE) +This open source Python library provide several solvers for optimization +problems related to Optimal Transport for signal, image processing and machine +learning. -This open source Python library provide several solvers for optimization problems related to Optimal Transport for signal, image processing and machine learning. +Website and documentation: [https://PythonOT.github.io/](https://PythonOT.github.io/) -It provides the following solvers: +Source Code (MIT): [https://github.com/PythonOT/POT](https://github.com/PythonOT/POT) -* OT Network Flow solver for the linear program/ Earth Movers Distance [1]. -* Entropic regularization OT solver with Sinkhorn Knopp Algorithm [2], stabilized version [9][10] and greedy Sinkhorn [22] with optional GPU implementation (requires cupy). +POT provides the following generic OT solvers (links to examples): + +* [OT Network Simplex solver](https://pythonot.github.io/auto_examples/plot_OT_1D.html) for the linear program/ Earth Movers Distance [1] . +* [Conditional gradient](https://pythonot.github.io/auto_examples/plot_optim_OTreg.html) [6] and [Generalized conditional gradient](https://pythonot.github.io/auto_examples/plot_optim_OTreg.html) for regularized OT [7]. +* Entropic regularization OT solver with [Sinkhorn Knopp Algorithm](https://pythonot.github.io/auto_examples/plot_OT_1D.html) [2] , stabilized version [9] [10], greedy Sinkhorn [22] and [Screening Sinkhorn [26] ](https://pythonot.github.io/auto_examples/plot_screenkhorn_1D.html) with optional GPU implementation (requires cupy). +* Bregman projections for [Wasserstein barycenter](https://pythonot.github.io/auto_examples/barycenters/plot_barycenter_lp_vs_entropic.html) [3], [convolutional barycenter](https://pythonot.github.io/auto_examples/barycenters/plot_convolutional_barycenter.html) [21] and unmixing [4]. * Sinkhorn divergence [23] and entropic regularization OT from empirical data. -* Smooth optimal transport solvers (dual and semi-dual) for KL and squared L2 regularizations [17]. -* Non regularized Wasserstein barycenters [16] with LP solver (only small scale). -* Bregman projections for Wasserstein barycenter [3], convolutional barycenter [21] and unmixing [4]. -* Optimal transport for domain adaptation with group lasso regularization [5] -* Conditional gradient [6] and Generalized conditional gradient for regularized OT [7]. -* Linear OT [14] and Joint OT matrix and mapping estimation [8]. -* Wasserstein Discriminant Analysis [11] (requires autograd + pymanopt). -* Gromov-Wasserstein distances and barycenters ([13] and regularized [12]) -* Stochastic Optimization for Large-scale Optimal Transport (semi-dual problem [18] and dual problem [19]) -* Non regularized free support Wasserstein barycenters [20]. -* Unbalanced OT with KL relaxation distance and barycenter [10, 25]. - -Some demonstrations (both in Python and Jupyter Notebook format) are available in the examples folder. +* [Smooth optimal transport solvers](https://pythonot.github.io/auto_examples/plot_OT_1D_smooth.html) (dual and semi-dual) for KL and squared L2 regularizations [17]. +* Non regularized [Wasserstein barycenters [16] ](https://pythonot.github.io/auto_examples/barycenters/plot_barycenter_lp_vs_entropic.html)) with LP solver (only small scale). +* [Gromov-Wasserstein distances](https://pythonot.github.io/auto_examples/gromov/plot_gromov.html) and [GW barycenters](https://pythonot.github.io/auto_examples/gromov/plot_gromov_barycenter.html) (exact [13] and regularized [12]) + * [Fused-Gromov-Wasserstein distances solver](https://pythonot.github.io/auto_examples/gromov/plot_fgw.html#sphx-glr-auto-examples-plot-fgw-py) and [FGW barycenters](https://pythonot.github.io/auto_examples/gromov/plot_barycenter_fgw.html) [24] +* [Stochastic solver](https://pythonot.github.io/auto_examples/plot_stochastic.html) for Large-scale Optimal Transport (semi-dual problem [18] and dual problem [19]) +* Non regularized [free support Wasserstein barycenters](https://pythonot.github.io/auto_examples/barycenters/plot_free_support_barycenter.html) [20]. +* [Unbalanced OT](https://pythonot.github.io/auto_examples/unbalanced-partial/plot_UOT_1D.html) with KL relaxation and [barycenter](https://pythonot.github.io/auto_examples/unbalanced-partial/plot_UOT_barycenter_1D.html) [10, 25]. +* [Partial Wasserstein and Gromov-Wasserstein](https://pythonot.github.io/auto_examples/unbalanced-partial/plot_partial_wass_and_gromov.html) (exact [29] and entropic [3] + formulations). + +POT provides the following Machine Learning related solvers: + +* [Optimal transport for domain + adaptation](https://pythonot.github.io/auto_examples/domain-adaptation/plot_otda_classes.html) + with [group lasso regularization](https://pythonot.github.io/auto_examples/domain-adaptation/plot_otda_classes.html), [Laplacian regularization](https://pythonot.github.io/auto_examples/domain-adaptation/plot_otda_laplacian.html) [5] [30] and [semi + supervised setting](https://pythonot.github.io/auto_examples/domain-adaptation/plot_otda_semi_supervised.html). +* [Linear OT mapping](https://pythonot.github.io/auto_examples/domain-adaptation/plot_otda_linear_mapping.html) [14] and [Joint OT mapping estimation](https://pythonot.github.io/auto_examples/domain-adaptation/plot_otda_mapping.html) [8]. +* [Wasserstein Discriminant Analysis](https://pythonot.github.io/auto_examples/others/plot_WDA.html) [11] (requires autograd + pymanopt). +* [JCPOT algorithm for multi-source domain adaptation with target shift](https://pythonot.github.io/auto_examples/domain-adaptation/plot_otda_jcpot.html) [27]. + +Some other examples are available in the [documentation](https://pythonot.github.io/auto_examples/index.html). #### Using and citing the toolbox -If you use this toolbox in your research and find it useful, please cite POT using the following bibtex reference: +If you use this toolbox in your research and find it useful, please cite POT +using the following reference: +``` +Rémi Flamary and Nicolas Courty, POT Python Optimal Transport library, +Website: https://pythonot.github.io/, 2017 +``` + +In Bibtex format: ``` @misc{flamary2017pot, title={POT Python Optimal Transport library}, author={Flamary, R{'e}mi and Courty, Nicolas}, -url={https://github.com/rflamary/POT}, +url={https://pythonot.github.io/}, year={2017} } ``` @@ -47,7 +69,7 @@ year={2017} The library has been tested on Linux, MacOSX and Windows. It requires a C++ compiler for building/installing the EMD solver and relies on the following Python modules: -- Numpy (>=1.11) +- Numpy (>=1.16) - Scipy (>=1.0) - Cython (>=0.23) - Matplotlib (>=1.5) @@ -64,9 +86,9 @@ You can install the toolbox through PyPI with: ``` pip install POT ``` -or get the very latest version by downloading it and then running: +or get the very latest version by running: ``` -python setup.py install --user # for user install (no root) +pip install -U https://github.com/PythonOT/POT/archive/master.zip # with --user for user install (no root) ``` @@ -129,34 +151,10 @@ T_reg=ot.sinkhorn(a,b,M,reg) # entropic regularized OT ba=ot.barycenter(A,M,reg) # reg is regularization parameter ``` - - - ### Examples and Notebooks -The examples folder contain several examples and use case for the library. The full documentation is available on [Readthedocs](http://pot.readthedocs.io/). - +The examples folder contain several examples and use case for the library. The full documentation with examples and output is available on [https://PythonOT.github.io/](https://PythonOT.github.io/). -Here is a list of the Python notebooks available [here](https://github.com/rflamary/POT/blob/master/notebooks/) if you want a quick look: - -* [1D optimal transport](https://github.com/rflamary/POT/blob/master/notebooks/plot_OT_1D.ipynb) -* [OT Ground Loss](https://github.com/rflamary/POT/blob/master/notebooks/plot_OT_L1_vs_L2.ipynb) -* [Multiple EMD computation](https://github.com/rflamary/POT/blob/master/notebooks/plot_compute_emd.ipynb) -* [2D optimal transport on empirical distributions](https://github.com/rflamary/POT/blob/master/notebooks/plot_OT_2D_samples.ipynb) -* [1D Wasserstein barycenter](https://github.com/rflamary/POT/blob/master/notebooks/plot_barycenter_1D.ipynb) -* [OT with user provided regularization](https://github.com/rflamary/POT/blob/master/notebooks/plot_optim_OTreg.ipynb) -* [Domain adaptation with optimal transport](https://github.com/rflamary/POT/blob/master/notebooks/plot_otda_d2.ipynb) -* [Color transfer in images](https://github.com/rflamary/POT/blob/master/notebooks/plot_otda_color_images.ipynb) -* [OT mapping estimation for domain adaptation](https://github.com/rflamary/POT/blob/master/notebooks/plot_otda_mapping.ipynb) -* [OT mapping estimation for color transfer in images](https://github.com/rflamary/POT/blob/master/notebooks/plot_otda_mapping_colors_images.ipynb) -* [Wasserstein Discriminant Analysis](https://github.com/rflamary/POT/blob/master/notebooks/plot_WDA.ipynb) -* [Gromov Wasserstein](https://github.com/rflamary/POT/blob/master/notebooks/plot_gromov.ipynb) -* [Gromov Wasserstein Barycenter](https://github.com/rflamary/POT/blob/master/notebooks/plot_gromov_barycenter.ipynb) -* [Fused Gromov Wasserstein](https://github.com/rflamary/POT/blob/master/notebooks/plot_fgw.ipynb) -* [Fused Gromov Wasserstein Barycenter](https://github.com/rflamary/POT/blob/master/notebooks/plot_barycenter_fgw.ipynb) - - -You can also see the notebooks with [Jupyter nbviewer](https://nbviewer.jupyter.org/github/rflamary/POT/tree/master/notebooks/). ## Acknowledgements @@ -167,19 +165,21 @@ This toolbox has been created and is maintained by The contributors to this library are -* [Alexandre Gramfort](http://alexandre.gramfort.net/) -* [Laetitia Chapel](http://people.irisa.fr/Laetitia.Chapel/) +* [Alexandre Gramfort](http://alexandre.gramfort.net/) (CI, documentation) +* [Laetitia Chapel](http://people.irisa.fr/Laetitia.Chapel/) (Partial OT) * [Michael Perrot](http://perso.univ-st-etienne.fr/pem82055/) (Mapping estimation) * [Léo Gautheron](https://github.com/aje) (GPU implementation) -* [Nathalie Gayraud](https://www.linkedin.com/in/nathalie-t-h-gayraud/?ppe=1) -* [Stanislas Chambon](https://slasnista.github.io/) -* [Antoine Rolet](https://arolet.github.io/) +* [Nathalie Gayraud](https://www.linkedin.com/in/nathalie-t-h-gayraud/?ppe=1) (DA classes) +* [Stanislas Chambon](https://slasnista.github.io/) (DA classes) +* [Antoine Rolet](https://arolet.github.io/) (EMD solver debug) * Erwan Vautier (Gromov-Wasserstein) -* [Kilian Fatras](https://kilianfatras.github.io/) +* [Kilian Fatras](https://kilianfatras.github.io/) (Stochastic solvers) * [Alain Rakotomamonjy](https://sites.google.com/site/alainrakotomamonjy/home) -* [Vayer Titouan](https://tvayer.github.io/) +* [Vayer Titouan](https://tvayer.github.io/) (Gromov-Wasserstein -, Fused-Gromov-Wasserstein) * [Hicham Janati](https://hichamjanati.github.io/) (Unbalanced OT) * [Romain Tavenard](https://rtavenar.github.io/) (1d Wasserstein) +* [Mokhtar Z. Alaya](http://mzalaya.github.io/) (Screenkhorn) +* [Ievgen Redko](https://ievred.github.io/) (Laplacian DA, JCPOT) This toolbox benefit a lot from open source research and we would like to thank the following persons for providing some code (in various languages): @@ -252,4 +252,14 @@ You can also post bug reports and feature requests in Github issues. Make sure t [24] Vayer, T., Chapel, L., Flamary, R., Tavenard, R. and Courty, N. (2019). [Optimal Transport for structured data with application on graphs](http://proceedings.mlr.press/v97/titouan19a.html) Proceedings of the 36th International Conference on Machine Learning (ICML). -[25] Frogner C., Zhang C., Mobahi H., Araya-Polo M., Poggio T. (2019). [Learning with a Wasserstein Loss](http://cbcl.mit.edu/wasserstein/) Advances in Neural Information Processing Systems (NIPS). +[25] Frogner C., Zhang C., Mobahi H., Araya-Polo M., Poggio T. (2015). [Learning with a Wasserstein Loss](http://cbcl.mit.edu/wasserstein/) Advances in Neural Information Processing Systems (NIPS). + +[26] Alaya M. Z., Bérar M., Gasso G., Rakotomamonjy A. (2019). [Screening Sinkhorn Algorithm for Regularized Optimal Transport](https://papers.nips.cc/paper/9386-screening-sinkhorn-algorithm-for-regularized-optimal-transport), Advances in Neural Information Processing Systems 33 (NeurIPS). + +[27] Redko I., Courty N., Flamary R., Tuia D. (2019). [Optimal Transport for Multi-source Domain Adaptation under Target Shift](http://proceedings.mlr.press/v89/redko19a.html), Proceedings of the Twenty-Second International Conference on Artificial Intelligence and Statistics (AISTATS) 22, 2019. + +[28] Caffarelli, L. A., McCann, R. J. (2010). [Free boundaries in optimal transport and Monge-Ampere obstacle problems](http://www.math.toronto.edu/~mccann/papers/annals2010.pdf), Annals of mathematics, 673-730. + +[29] Chapel, L., Alaya, M., Gasso, G. (2019). [Partial Gromov-Wasserstein with Applications on Positive-Unlabeled Learning](https://arxiv.org/abs/2002.08276), arXiv preprint arXiv:2002.08276. + +[30] Flamary R., Courty N., Tuia D., Rakotomamonjy A. (2014). [Optimal transport with Laplacian regularization: Applications to domain adaptation and shape matching](https://remi.flamary.com/biblio/flamary2014optlaplace.pdf), NIPS Workshop on Optimal Transport and Machine Learning OTML, 2014. |