Merge pull request #88 from rflamary/doc_modules

[MRG] Update documentation and add quick start guide

Author: rflamary

Makefile

@@ -42,10 +42,10 @@ pep8 :
 	flake8 examples/ ot/ test/
 
 test : FORCE pep8
-	$(PYTHON) -m pytest -v test/ --cov=ot --cov-report html:cov_html
+	$(PYTHON) -m pytest -v test/ --doctest-modules --ignore ot/gpu/  --cov=ot --cov-report html:cov_html
 
 pytest : FORCE 
-	$(PYTHON) -m pytest -v test/ --cov=ot
+	$(PYTHON) -m pytest -v test/ --doctest-modules --ignore ot/gpu/  --cov=ot
 
 uploadpypi :
 	#python setup.py register

README.md

@@ -54,6 +54,12 @@ The library has been tested on Linux, MacOSX and Windows. It requires a C++ comp
 
 #### Pip installation
 
+Note that due to a limitation of pip, `cython` and `numpy` need to be installed
+prior to installing POT. This can be done easily with
+```
+pip install numpy cython
+```
+
 You can install the toolbox through PyPI with:
 ```
 pip install POT
@@ -63,6 +69,8 @@ or get the very latest version by downloading it and then running:
 python setup.py install --user # for user install (no root)
 ```
 
+
+
 #### Anaconda installation with conda-forge
 
 If you use the Anaconda python distribution, POT is available in [conda-forge](https://conda-forge.org). To install it and the required dependencies:
@@ -151,7 +159,12 @@ You can also see the notebooks with [Jupyter nbviewer](https://nbviewer.jupyter.
 
 ## Acknowledgements
 
-The contributors to this library are:
+This toolbox has been created and is maintained by
+
+* [Rémi Flamary](http://remi.flamary.com/)
+* [Nicolas Courty](http://people.irisa.fr/Nicolas.Courty/)
+
+The contributors to this library are 
 
 * [Rémi Flamary](http://remi.flamary.com/)
 * [Nicolas Courty](http://people.irisa.fr/Nicolas.Courty/)

docs/cache_nbrun

@@ -1 +1 @@
-{"plot_otda_mapping_colors_images.ipynb": "cc8bf9a857f52e4a159fe71dfda19018", "plot_optim_OTreg.ipynb": "481801bb0d133ef350a65179cf8f739a", "plot_otda_color_images.ipynb": "f804d5806c7ac1a0901e4542b1eaa77b", "plot_stochastic.ipynb": "e18253354c8c1d72567a4259eb1094f7", "plot_WDA.ipynb": "27f8de4c6d7db46497076523673eedfb", "plot_otda_linear_mapping.ipynb": "a472c767abe82020e0a58125a528785c", "plot_OT_1D_smooth.ipynb": "3a059103652225a0c78ea53895cf79e5", "plot_OT_L1_vs_L2.ipynb": "5d565b8aaf03be4309eba731127851dc", "plot_barycenter_1D.ipynb": "5f6fb8aebd8e2e91ebc77c923cb112b3", "plot_otda_classes.ipynb": "39087b6e98217851575f2271c22853a4", "plot_otda_d2.ipynb": "e6feae588103f2a8fab942e5f4eff483", "plot_otda_mapping.ipynb": "2f1ebbdc0f855d9e2b7adf9edec24d25", "plot_gromov.ipynb": "24f2aea489714d34779521f46d5e2c47", "plot_compute_emd.ipynb": "f5cd71cad882ec157dc8222721e9820c", "plot_OT_1D.ipynb": "b5348bdc561c07ec168a1622e5af4b93", "plot_gromov_barycenter.ipynb": "953e5047b886ec69ec621ec52f5e21d1", "plot_free_support_barycenter.ipynb": "246dd2feff4b233a4f1a553c5a202fdc", "plot_convolutional_barycenter.ipynb": "a72bb3716a1baaffd81ae267a673f9b6", "plot_otda_semi_supervised.ipynb": "f6dfb02ba2bbd939408ffcd22a3b007c", "plot_OT_2D_samples.ipynb": "07dbc14859fa019a966caa79fa0825bd", "plot_barycenter_lp_vs_entropic.ipynb": "51833e8c76aaedeba9599ac7a30eb357"}
+{"plot_otda_semi_supervised.ipynb": "f6dfb02ba2bbd939408ffcd22a3b007c", "plot_WDA.ipynb": "27f8de4c6d7db46497076523673eedfb", "plot_UOT_1D.ipynb": "fc7dd383e625597bd59fff03a8430c91", "plot_OT_L1_vs_L2.ipynb": "5d565b8aaf03be4309eba731127851dc", "plot_otda_color_images.ipynb": "f804d5806c7ac1a0901e4542b1eaa77b", "plot_fgw.ipynb": "2ba3e100e92ecf4dfbeb605de20b40ab", "plot_otda_d2.ipynb": "e6feae588103f2a8fab942e5f4eff483", "plot_compute_emd.ipynb": "f5cd71cad882ec157dc8222721e9820c", "plot_barycenter_fgw.ipynb": "e14100dd276bff3ffdfdf176f1b6b070", "plot_convolutional_barycenter.ipynb": "a72bb3716a1baaffd81ae267a673f9b6", "plot_optim_OTreg.ipynb": "481801bb0d133ef350a65179cf8f739a", "plot_barycenter_lp_vs_entropic.ipynb": "51833e8c76aaedeba9599ac7a30eb357", "plot_OT_1D_smooth.ipynb": "3a059103652225a0c78ea53895cf79e5", "plot_barycenter_1D.ipynb": "5f6fb8aebd8e2e91ebc77c923cb112b3", "plot_otda_mapping.ipynb": "2f1ebbdc0f855d9e2b7adf9edec24d25", "plot_OT_1D.ipynb": "b5348bdc561c07ec168a1622e5af4b93", "plot_gromov_barycenter.ipynb": "953e5047b886ec69ec621ec52f5e21d1", "plot_UOT_barycenter_1D.ipynb": "c72f0bfb6e1a79710dad3fef9f5c557c", "plot_otda_mapping_colors_images.ipynb": "cc8bf9a857f52e4a159fe71dfda19018", "plot_stochastic.ipynb": "e18253354c8c1d72567a4259eb1094f7", "plot_otda_linear_mapping.ipynb": "a472c767abe82020e0a58125a528785c", "plot_otda_classes.ipynb": "39087b6e98217851575f2271c22853a4", "plot_free_support_barycenter.ipynb": "246dd2feff4b233a4f1a553c5a202fdc", "plot_gromov.ipynb": "24f2aea489714d34779521f46d5e2c47", "plot_OT_2D_samples.ipynb": "912a77c5dd0fc0fafa03fac3d86f1502"}

docs/source/auto_examples/auto_examples_jupyter.zip

@@ -29,13 +29,13 @@ This is a gallery of all the POT example files.
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="Illustrates the use of the generic solver for regularized OT with user-designed regularization ...">
+    <div class="sphx-glr-thumbcontainer" tooltip="This example illustrates the computation of Unbalanced Optimal transport using a Kullback-Leibl...">
 
 .. only:: html
 
-    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_optim_OTreg_thumb.png
+    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_UOT_1D_thumb.png
 
-        :ref:`sphx_glr_auto_examples_plot_optim_OTreg.py`
+        :ref:`sphx_glr_auto_examples_plot_UOT_1D.py`
 
 .. raw:: html
 
@@ -45,17 +45,17 @@ This is a gallery of all the POT example files.
 .. toctree::
    :hidden:
 
-   /auto_examples/plot_optim_OTreg
+   /auto_examples/plot_UOT_1D
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="Illustration of 2D Wasserstein barycenters if discributions that are weighted sum of diracs.">
+    <div class="sphx-glr-thumbcontainer" tooltip="Illustrates the use of the generic solver for regularized OT with user-designed regularization ...">
 
 .. only:: html
 
-    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_free_support_barycenter_thumb.png
+    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_optim_OTreg_thumb.png
 
-        :ref:`sphx_glr_auto_examples_plot_free_support_barycenter.py`
+        :ref:`sphx_glr_auto_examples_plot_optim_OTreg.py`
 
 .. raw:: html
 
@@ -65,17 +65,17 @@ This is a gallery of all the POT example files.
 .. toctree::
    :hidden:
 
-   /auto_examples/plot_free_support_barycenter
+   /auto_examples/plot_optim_OTreg
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="This example illustrates the computation of EMD, Sinkhorn and smooth OT plans and their visuali...">
+    <div class="sphx-glr-thumbcontainer" tooltip="Illustration of 2D Wasserstein barycenters if discributions that are weighted sum of diracs.">
 
 .. only:: html
 
-    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_OT_1D_smooth_thumb.png
+    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_free_support_barycenter_thumb.png
 
-        :ref:`sphx_glr_auto_examples_plot_OT_1D_smooth.py`
+        :ref:`sphx_glr_auto_examples_plot_free_support_barycenter.py`
 
 .. raw:: html
 
@@ -85,17 +85,17 @@ This is a gallery of all the POT example files.
 .. toctree::
    :hidden:
 
-   /auto_examples/plot_OT_1D_smooth
+   /auto_examples/plot_free_support_barycenter
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="This example is designed to show how to use the Gromov-Wassertsein distance computation in POT....">
+    <div class="sphx-glr-thumbcontainer" tooltip="This example illustrates the computation of EMD, Sinkhorn and smooth OT plans and their visuali...">
 
 .. only:: html
 
-    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_gromov_thumb.png
+    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_OT_1D_smooth_thumb.png
 
-        :ref:`sphx_glr_auto_examples_plot_gromov.py`
+        :ref:`sphx_glr_auto_examples_plot_OT_1D_smooth.py`
 
 .. raw:: html
 
@@ -105,17 +105,17 @@ This is a gallery of all the POT example files.
 .. toctree::
    :hidden:
 
-   /auto_examples/plot_gromov
+   /auto_examples/plot_OT_1D_smooth
 
 .. raw:: html
 
-    <div class="sphx-glr-thumbcontainer" tooltip="Illustration of 2D optimal transport between discributions that are weighted sum of diracs. The...">
+    <div class="sphx-glr-thumbcontainer" tooltip="This example is designed to show how to use the Gromov-Wassertsein distance computation in POT....">
 
 .. only:: html
 
-    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_OT_2D_samples_thumb.png
+    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_gromov_thumb.png
 
-        :ref:`sphx_glr_auto_examples_plot_OT_2D_samples.py`
+        :ref:`sphx_glr_auto_examples_plot_gromov.py`
 
 .. raw:: html
 
@@ -125,7 +125,7 @@ This is a gallery of all the POT example files.
 .. toctree::
    :hidden:
 
-   /auto_examples/plot_OT_2D_samples
+   /auto_examples/plot_gromov
 
 .. raw:: html
 
@@ -207,6 +207,26 @@ This is a gallery of all the POT example files.
 
    /auto_examples/plot_WDA
 
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="Illustration of 2D optimal transport between discributions that are weighted sum of diracs. The...">
+
+.. only:: html
+
+    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_OT_2D_samples_thumb.png
+
+        :ref:`sphx_glr_auto_examples_plot_OT_2D_samples.py`
+
+.. raw:: html
+
+    </div>
+
+
+.. toctree::
+   :hidden:
+
+   /auto_examples/plot_OT_2D_samples
+
 .. raw:: html
 
     <div class="sphx-glr-thumbcontainer" tooltip="This example is designed to show how to use the stochatic optimization algorithms for descrete ...">
@@ -287,6 +307,26 @@ This is a gallery of all the POT example files.
 
    /auto_examples/plot_otda_mapping_colors_images
 
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="This example illustrates the computation of regularized Wassersyein Barycenter as proposed in [...">
+
+.. only:: html
+
+    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_UOT_barycenter_1D_thumb.png
+
+        :ref:`sphx_glr_auto_examples_plot_UOT_barycenter_1D.py`
+
+.. raw:: html
+
+    </div>
+
+
+.. toctree::
+   :hidden:
+
+   /auto_examples/plot_UOT_barycenter_1D
+
 .. raw:: html
 
     <div class="sphx-glr-thumbcontainer" tooltip="This example presents how to use MappingTransport to estimate at the same time both the couplin...">
@@ -327,6 +367,26 @@ This is a gallery of all the POT example files.
 
    /auto_examples/plot_otda_semi_supervised
 
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="This example illustrates the computation of FGW for 1D measures[18].">
+
+.. only:: html
+
+    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_fgw_thumb.png
+
+        :ref:`sphx_glr_auto_examples_plot_fgw.py`
+
+.. raw:: html
+
+    </div>
+
+
+.. toctree::
+   :hidden:
+
+   /auto_examples/plot_fgw
+
 .. raw:: html
 
     <div class="sphx-glr-thumbcontainer" tooltip="This example introduces a domain adaptation in a 2D setting and the 4 OTDA approaches currently...">
@@ -407,6 +467,26 @@ This is a gallery of all the POT example files.
 
    /auto_examples/plot_barycenter_lp_vs_entropic
 
+.. raw:: html
+
+    <div class="sphx-glr-thumbcontainer" tooltip="This example illustrates the computation barycenter of labeled graphs using FGW">
+
+.. only:: html
+
+    .. figure:: /auto_examples/images/thumb/sphx_glr_plot_barycenter_fgw_thumb.png
+
+        :ref:`sphx_glr_auto_examples_plot_barycenter_fgw.py`
+
+.. raw:: html
+
+    </div>
+
+
+.. toctree::
+   :hidden:
+
+   /auto_examples/plot_barycenter_fgw
+
 .. raw:: html
 
     <div class="sphx-glr-thumbcontainer" tooltip="This example is designed to show how to use the Gromov-Wasserstein distance computation in POT....">

docs/source/auto_examples/auto_examples_python.zip

@@ -26,7 +26,7 @@
       },
       "outputs": [],
       "source": [
-        "# Author: Remi Flamary <[email protected]>\n#\n# License: MIT License\n\nimport numpy as np\nimport matplotlib.pylab as pl\nimport ot\nimport ot.plot"
+        "# Author: Remi Flamary <[email protected]>\n#         Kilian Fatras <[email protected]>\n#\n# License: MIT License\n\nimport numpy as np\nimport matplotlib.pylab as pl\nimport ot\nimport ot.plot"
       ]
     },
     {
@@ -100,6 +100,24 @@
       "source": [
         "#%% sinkhorn\n\n# reg term\nlambd = 1e-3\n\nGs = ot.sinkhorn(a, b, M, lambd)\n\npl.figure(5)\npl.imshow(Gs, interpolation='nearest')\npl.title('OT matrix sinkhorn')\n\npl.figure(6)\not.plot.plot2D_samples_mat(xs, xt, Gs, color=[.5, .5, 1])\npl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')\npl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')\npl.legend(loc=0)\npl.title('OT matrix Sinkhorn with samples')\n\npl.show()"
       ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "Emprirical Sinkhorn\n----------------\n\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "collapsed": false
+      },
+      "outputs": [],
+      "source": [
+        "#%% sinkhorn\n\n# reg term\nlambd = 1e-3\n\nGes = ot.bregman.empirical_sinkhorn(xs, xt, lambd)\n\npl.figure(7)\npl.imshow(Ges, interpolation='nearest')\npl.title('OT matrix empirical sinkhorn')\n\npl.figure(8)\not.plot.plot2D_samples_mat(xs, xt, Ges, color=[.5, .5, 1])\npl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')\npl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')\npl.legend(loc=0)\npl.title('OT matrix Sinkhorn from samples')\n\npl.show()"
+      ]
     }
   ],
   "metadata": {
@@ -118,7 +136,7 @@
       "name": "python",
       "nbconvert_exporter": "python",
       "pygments_lexer": "ipython3",
-      "version": "3.6.5"
+      "version": "3.6.8"
     }
   },
   "nbformat": 4,

docs/source/auto_examples/images/sphx_glr_plot_OT_2D_samples_001.png

@@ -10,6 +10,7 @@
 """
 
 # Author: Remi Flamary <[email protected]>
+#         Kilian Fatras <[email protected]>
 #
 # License: MIT License
 
@@ -100,3 +101,28 @@
 pl.title('OT matrix Sinkhorn with samples')
 
 pl.show()
+
+
+##############################################################################
+# Emprirical Sinkhorn
+# ----------------
+
+#%% sinkhorn
+
+# reg term
+lambd = 1e-3
+
+Ges = ot.bregman.empirical_sinkhorn(xs, xt, lambd)
+
+pl.figure(7)
+pl.imshow(Ges, interpolation='nearest')
+pl.title('OT matrix empirical sinkhorn')
+
+pl.figure(8)
+ot.plot.plot2D_samples_mat(xs, xt, Ges, color=[.5, .5, 1])
+pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
+pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
+pl.legend(loc=0)
+pl.title('OT matrix Sinkhorn from samples')
+
+pl.show()