diff options
Diffstat (limited to 'docs/source/readme.rst')
| -rw-r--r-- | docs/source/readme.rst | 227 |
1 files changed, 143 insertions, 84 deletions
diff --git a/docs/source/readme.rst b/docs/source/readme.rst index 0871779..b8cb48c 100644 --- a/docs/source/readme.rst +++ b/docs/source/readme.rst @@ -1,57 +1,116 @@ POT: Python Optimal Transport ============================= -|PyPI version| |Anaconda Cloud| |Build Status| |Documentation Status| +|PyPI version| |Anaconda Cloud| |Build Status| |Codecov Status| |Downloads| |Anaconda downloads| |License| This open source Python library provide several solvers for optimization problems related to Optimal Transport for signal, image processing and machine learning. -It provides the following solvers: - -- 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). +Website and documentation: https://PythonOT.github.io/ + +Source Code (MIT): https://github.com/PythonOT/POT + +POT provides the following generic OT solvers (links to examples): + +- `OT Network Simplex + solver <auto_examples/plot_OT_1D.html>`__ + for the linear program/ Earth Movers Distance [1] . +- `Conditional + gradient <auto_examples/plot_optim_OTreg.html>`__ + [6] and `Generalized conditional + gradient <auto_examples/plot_optim_OTreg.html>`__ + for regularized OT [7]. +- Entropic regularization OT solver with `Sinkhorn Knopp + Algorithm <auto_examples/plot_OT_1D.html>`__ + [2] , stabilized version [9] [10], greedy Sinkhorn [22] and + `Screening Sinkhorn + [26] <auto_examples/plot_screenkhorn_1D.html>`__ + with optional GPU implementation (requires cupy). +- Bregman projections for `Wasserstein + barycenter <auto_examples/barycenters/plot_barycenter_lp_vs_entropic.html>`__ + [3], `convolutional + barycenter <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 <auto_examples/plot_OT_1D_smooth.html>`__ + (dual and semi-dual) for KL and squared L2 regularizations [17]. +- Non regularized `Wasserstein barycenters + [16] <auto_examples/barycenters/plot_barycenter_lp_vs_entropic.html>`__) + with LP solver (only small scale). +- `Gromov-Wasserstein + distances <auto_examples/gromov/plot_gromov.html>`__ + and `GW + barycenters <auto_examples/gromov/plot_gromov_barycenter.html>`__ + (exact [13] and regularized [12]) +- `Fused-Gromov-Wasserstein distances + solver <auto_examples/gromov/plot_fgw.html#sphx-glr-auto-examples-plot-fgw-py>`__ + and `FGW + barycenters <auto_examples/gromov/plot_barycenter_fgw.html>`__ + [24] +- `Stochastic + solver <auto_examples/plot_stochastic.html>`__ + for Large-scale Optimal Transport (semi-dual problem [18] and dual + problem [19]) +- Non regularized `free support Wasserstein + barycenters <auto_examples/barycenters/plot_free_support_barycenter.html>`__ + [20]. +- `Unbalanced + OT <auto_examples/unbalanced-partial/plot_UOT_1D.html>`__ + with KL relaxation and + `barycenter <auto_examples/unbalanced-partial/plot_UOT_barycenter_1D.html>`__ + [10, 25]. +- `Partial Wasserstein and + Gromov-Wasserstein <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 <auto_examples/domain-adaptation/plot_otda_classes.html>`__ + with `group lasso + regularization <auto_examples/domain-adaptation/plot_otda_classes.html>`__, + `Laplacian + regularization <auto_examples/domain-adaptation/plot_otda_laplacian.html>`__ + [5] [30] and `semi supervised + setting <auto_examples/domain-adaptation/plot_otda_semi_supervised.html>`__. +- `Linear OT + mapping <auto_examples/domain-adaptation/plot_otda_linear_mapping.html>`__ + [14] and `Joint OT mapping + estimation <auto_examples/domain-adaptation/plot_otda_mapping.html>`__ + [8]. +- `Wasserstein Discriminant + Analysis <auto_examples/others/plot_WDA.html>`__ + [11] (requires autograd + pymanopt). +- `JCPOT algorithm for multi-source domain adaptation with target + shift <auto_examples/domain-adaptation/plot_otda_jcpot.html>`__ + [27]. + +Some other examples are available in the +`documentation <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: +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} } @@ -59,10 +118,10 @@ Installation ------------ The library has been tested on Linux, MacOSX and Windows. It requires a -C++ compiler for using the EMD solver and relies on the following Python -modules: +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) @@ -83,11 +142,11 @@ 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) Anaconda installation with conda-forge ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -174,42 +233,8 @@ 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/>`__. - -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>`__ - -You can also see the notebooks with `Jupyter -nbviewer <https://nbviewer.jupyter.org/github/rflamary/POT/tree/master/notebooks/>`__. +library. The full documentation with examples and output is available on +https://PythonOT.github.io/. Acknowledgements ---------------- @@ -221,22 +246,29 @@ This toolbox has been created and is maintained by The contributors to this library are -- `Alexandre Gramfort <http://alexandre.gramfort.net/>`__ +- `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/>`__ + (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 @@ -387,21 +419,48 @@ and Statistics, (AISTATS) 21, 2018 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). +[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. + .. |PyPI version| image:: https://badge.fury.io/py/POT.svg :target: https://badge.fury.io/py/POT .. |Anaconda Cloud| image:: https://anaconda.org/conda-forge/pot/badges/version.svg :target: https://anaconda.org/conda-forge/pot -.. |Build Status| image:: https://travis-ci.org/rflamary/POT.svg?branch=master - :target: https://travis-ci.org/rflamary/POT -.. |Documentation Status| image:: https://readthedocs.org/projects/pot/badge/?version=latest - :target: http://pot.readthedocs.io/en/latest/?badge=latest +.. |Build Status| image:: https://github.com/PythonOT/POT/workflows/build/badge.svg + :target: https://github.com/PythonOT/POT/actions +.. |Codecov Status| image:: https://codecov.io/gh/PythonOT/POT/branch/master/graph/badge.svg + :target: https://codecov.io/gh/PythonOT/POT .. |Downloads| image:: https://pepy.tech/badge/pot :target: https://pepy.tech/project/pot .. |Anaconda downloads| image:: https://anaconda.org/conda-forge/pot/badges/downloads.svg :target: https://anaconda.org/conda-forge/pot .. |License| image:: https://anaconda.org/conda-forge/pot/badges/license.svg - :target: https://github.com/rflamary/POT/blob/master/LICENSE + :target: https://github.com/PythonOT/POT/blob/master/LICENSE |