1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
POT: Python Optimal Transport
=============================
|PyPI version| |Build Status| |Documentation Status|
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 solver for the linear program/ Earth Movers Distance [1].
- Entropic regularization OT solver with Sinkhorn Knopp Algorithm [2]
and stabilized version [9][10].
- Bregman projections for Wasserstein barycenter [3] and unmixing [4].
- Optimal transport for domain adaptation with group lasso
regularization [5]
- Conditional gradient [6] and Generalized conditional gradient for
regularized OT [7].
- Joint OT matrix and mapping estimation [8].
Some demonstrations (both in Python and Jupyter Notebook format) are
available in the examples folder.
Installation
------------
The Library has been tested on Linux and MacOSX. It requires a C++
compiler for using the EMD solver and rely on the following Python
modules:
- Numpy (>=1.11)
- Scipy (>=0.17)
- Cython (>=0.23)
- Matplotlib (>=1.5)
Under debian based linux the dependencies can be installed with
::
sudo apt-get install python-numpy python-scipy python-matplotlib cython
To install the library, you can install it locally (after downloading
it) on you machine using
::
python setup.py install --user
The toolbox is also available on PyPI with a possibly slightly older
version. You can install it with:
::
pip install POT
After a correct installation, you should be able to import the module
without errors:
.. code:: python
import ot
Note that for easier access the module is name ot instead of pot.
Examples
--------
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 if you want a quick look:
- `1D optimal
transport <https://github.com/rflamary/POT/blob/master/examples/Demo_1D_OT.ipynb>`__
- `2D optimal transport on empirical
distributions <https://github.com/rflamary/POT/blob/master/examples/Demo_2D_OT_samples.ipynb>`__
- `1D Wasserstein
barycenter <https://github.com/rflamary/POT/blob/master/examples/Demo_1D_barycenter.ipynb>`__
- `OT with user provided
regularization <https://github.com/rflamary/POT/blob/master/examples/Demo_Optim_OTreg.ipynb>`__
- `Domain adaptation with optimal
transport <https://github.com/rflamary/POT/blob/master/examples/Demo_2D_OT_DomainAdaptation.ipynb>`__
- `Color transfer in
images <https://github.com/rflamary/POT/blob/master/examples/Demo_Image_ColorAdaptation.ipynb>`__
- `OT mapping estimation for domain
adaptation <https://github.com/rflamary/POT/blob/master/examples/Demo_2D_OTmapping_DomainAdaptation.ipynb>`__
- `OT mapping estimation for color transfer in
images <https://github.com/rflamary/POT/blob/master/examples/Demo_Image_ColorAdaptation_mapping.ipynb>`__
You can also see the notebooks with `Jupyter
nbviewer <https://nbviewer.jupyter.org/github/rflamary/POT/tree/master/examples/>`__.
Acknowledgements
----------------
The contributors to this library are:
- `Rémi Flamary <http://remi.flamary.com/>`__
- `Nicolas Courty <http://people.irisa.fr/Nicolas.Courty/>`__
- `Laetitia Chapel <http://people.irisa.fr/Laetitia.Chapel/>`__
- `Michael Perrot <http://perso.univ-st-etienne.fr/pem82055/>`__
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):
- `Gabriel Peyré <http://gpeyre.github.io/>`__ (Wasserstein Barycenters
in Matlab)
- `Nicolas Bonneel <http://liris.cnrs.fr/~nbonneel/>`__ ( C++ code for
EMD)
- `Antoine Rolet <https://arolet.github.io/>`__ ( Mex file for EMD )
- `Marco Cuturi <http://marcocuturi.net/>`__ (Sinkhorn Knopp in
Matlab/Cuda)
References
----------
[1] Bonneel, N., Van De Panne, M., Paris, S., & Heidrich, W. (2011,
December). Displacement interpolation using Lagrangian mass transport.
In ACM Transactions on Graphics (TOG) (Vol. 30, No. 6, p. 158). ACM.
[2] Cuturi, M. (2013). Sinkhorn distances: Lightspeed computation of
optimal transport. In Advances in Neural Information Processing Systems
(pp. 2292-2300).
[3] Benamou, J. D., Carlier, G., Cuturi, M., Nenna, L., & Peyré, G.
(2015). Iterative Bregman projections for regularized transportation
problems. SIAM Journal on Scientific Computing, 37(2), A1111-A1138.
[4] S. Nakhostin, N. Courty, R. Flamary, D. Tuia, T. Corpetti,
Supervised planetary unmixing with optimal transport, Whorkshop on
Hyperspectral Image and Signal Processing : Evolution in Remote Sensing
(WHISPERS), 2016.
[5] N. Courty; R. Flamary; D. Tuia; A. Rakotomamonjy, "Optimal Transport
for Domain Adaptation," in IEEE Transactions on Pattern Analysis and
Machine Intelligence , vol.PP, no.99, pp.1-1
[6] Ferradans, S., Papadakis, N., Peyré, G., & Aujol, J. F. (2014).
Regularized discrete optimal transport. SIAM Journal on Imaging
Sciences, 7(3), 1853-1882.
[7] Rakotomamonjy, A., Flamary, R., & Courty, N. (2015). Generalized
conditional gradient: analysis of convergence and applications. arXiv
preprint arXiv:1510.06567.
[8] M. Perrot, N. Courty, R. Flamary, A. Habrard, "Mapping estimation
for discrete optimal transport", Neural Information Processing Systems
(NIPS), 2016.
[9] Schmitzer, B. (2016). Stabilized Sparse Scaling Algorithms for
Entropy Regularized Transport Problems. arXiv preprint arXiv:1610.06519.
[10] Chizat, L., Peyré, G., Schmitzer, B., & Vialard, F. X. (2016).
Scaling algorithms for unbalanced transport problems. arXiv preprint
arXiv:1607.05816.
.. |PyPI version| image:: https://badge.fury.io/py/POT.svg
:target: https://badge.fury.io/py/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
|
