update example with rst titles

9 files changed, 223 insertions, 105 deletions

diff --git a/examples/README.txt b/examples/README.txt
index f8643b8..c3d556d 100644
--- a/examples/README.txt
+++ b/examples/README.txt
@@ -1,2 +1,4 @@
 POT Examples
 ============
+
+This is a gallery of all the POT example files. 
diff --git a/examples/plot_OT_1D.py b/examples/plot_OT_1D.py
index a1473c4..a63f29a 100644
--- a/examples/plot_OT_1D.py
+++ b/examples/plot_OT_1D.py
@@ -4,7 +4,7 @@
 1D optimal transport
 ====================
 
-This example illustrate the computation of EMD and Sinkhorn transport plans 
+This example illustrates the computation of EMD and Sinkhorn transport plans 
 and their visualization.
 
 """
diff --git a/examples/plot_OT_2D_samples.py b/examples/plot_OT_2D_samples.py
index a913b8c..f57d631 100644
--- a/examples/plot_OT_2D_samples.py
+++ b/examples/plot_OT_2D_samples.py
@@ -4,6 +4,9 @@
 2D Optimal transport between empirical distributions
 ====================================================
 
+Illustration of 2D optimal transport between discributions that are weighted
+sum of diracs. The OT matrix is plotted with the samples.
+
 """
 
 # Author: Remi Flamary <remi.flamary@unice.fr>
diff --git a/examples/plot_OT_L1_vs_L2.py b/examples/plot_OT_L1_vs_L2.py
index dfc9462..77bde22 100644
--- a/examples/plot_OT_L1_vs_L2.py
+++ b/examples/plot_OT_L1_vs_L2.py
@@ -4,6 +4,8 @@
 2D Optimal transport for different metrics
 ==========================================
 
+2D OT on empirical distributio  with different gound metric.
+
 Stole the figure idea from Fig. 1 and 2 in
 https://arxiv.org/pdf/1706.07650.pdf
 
@@ -18,98 +20,190 @@ import numpy as np
 import matplotlib.pylab as pl
 import ot
 
-#%% parameters and data generation
-
-for data in range(2):
-
-    if data:
-        n = 20  # nb samples
-        xs = np.zeros((n, 2))
-        xs[:, 0] = np.arange(n) + 1
-        xs[:, 1] = (np.arange(n) + 1) * -0.001  # to make it strictly convex...
-
-        xt = np.zeros((n, 2))
-        xt[:, 1] = np.arange(n) + 1
-    else:
-
-        n = 50  # nb samples
-        xtot = np.zeros((n + 1, 2))
-        xtot[:, 0] = np.cos(
-            (np.arange(n + 1) + 1.0) * 0.9 / (n + 2) * 2 * np.pi)
-        xtot[:, 1] = np.sin(
-            (np.arange(n + 1) + 1.0) * 0.9 / (n + 2) * 2 * np.pi)
-
-        xs = xtot[:n, :]
-        xt = xtot[1:, :]
-
-    a, b = ot.unif(n), ot.unif(n)  # uniform distribution on samples
-
-    # loss matrix
-    M1 = ot.dist(xs, xt, metric='euclidean')
-    M1 /= M1.max()
-
-    # loss matrix
-    M2 = ot.dist(xs, xt, metric='sqeuclidean')
-    M2 /= M2.max()
-
-    # loss matrix
-    Mp = np.sqrt(ot.dist(xs, xt, metric='euclidean'))
-    Mp /= Mp.max()
-
-    #%% plot samples
-
-    pl.figure(1 + 3 * data, figsize=(7, 3))
-    pl.clf()
-    pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
-    pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
-    pl.axis('equal')
-    pl.title('Source and traget distributions')
-
-    pl.figure(2 + 3 * data, figsize=(7, 3))
-
-    pl.subplot(1, 3, 1)
-    pl.imshow(M1, interpolation='nearest')
-    pl.title('Euclidean cost')
-
-    pl.subplot(1, 3, 2)
-    pl.imshow(M2, interpolation='nearest')
-    pl.title('Squared Euclidean cost')
-
-    pl.subplot(1, 3, 3)
-    pl.imshow(Mp, interpolation='nearest')
-    pl.title('Sqrt Euclidean cost')
-    pl.tight_layout()
-
-    #%% EMD
-    G1 = ot.emd(a, b, M1)
-    G2 = ot.emd(a, b, M2)
-    Gp = ot.emd(a, b, Mp)
-
-    pl.figure(3 + 3 * data, figsize=(7, 3))
-
-    pl.subplot(1, 3, 1)
-    ot.plot.plot2D_samples_mat(xs, xt, G1, c=[.5, .5, 1])
-    pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
-    pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
-    pl.axis('equal')
-    # pl.legend(loc=0)
-    pl.title('OT Euclidean')
-
-    pl.subplot(1, 3, 2)
-    ot.plot.plot2D_samples_mat(xs, xt, G2, c=[.5, .5, 1])
-    pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
-    pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
-    pl.axis('equal')
-    # pl.legend(loc=0)
-    pl.title('OT squared Euclidean')
-
-    pl.subplot(1, 3, 3)
-    ot.plot.plot2D_samples_mat(xs, xt, Gp, c=[.5, .5, 1])
-    pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
-    pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
-    pl.axis('equal')
-    # pl.legend(loc=0)
-    pl.title('OT sqrt Euclidean')
-    pl.tight_layout()
+##############################################################################
+# Dataset 1 : uniform sampling
+##############################################################################
+
+n = 20  # nb samples
+xs = np.zeros((n, 2))
+xs[:, 0] = np.arange(n) + 1
+xs[:, 1] = (np.arange(n) + 1) * -0.001  # to make it strictly convex...
+
+xt = np.zeros((n, 2))
+xt[:, 1] = np.arange(n) + 1
+
+a, b = ot.unif(n), ot.unif(n)  # uniform distribution on samples
+
+# loss matrix
+M1 = ot.dist(xs, xt, metric='euclidean')
+M1 /= M1.max()
+
+# loss matrix
+M2 = ot.dist(xs, xt, metric='sqeuclidean')
+M2 /= M2.max()
+
+# loss matrix
+Mp = np.sqrt(ot.dist(xs, xt, metric='euclidean'))
+Mp /= Mp.max()
+
+# Data
+pl.figure(1, figsize=(7, 3))
+pl.clf()
+pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
+pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
+pl.axis('equal')
+pl.title('Source and traget distributions')
+
+
+# Cost matrices
+pl.figure(2, figsize=(7, 3))
+
+pl.subplot(1, 3, 1)
+pl.imshow(M1, interpolation='nearest')
+pl.title('Euclidean cost')
+
+pl.subplot(1, 3, 2)
+pl.imshow(M2, interpolation='nearest')
+pl.title('Squared Euclidean cost')
+
+pl.subplot(1, 3, 3)
+pl.imshow(Mp, interpolation='nearest')
+pl.title('Sqrt Euclidean cost')
+pl.tight_layout()
+
+##############################################################################
+# Dataset 1 : Plot OT Matrices
+##############################################################################
+
+
+
+#%% EMD
+G1 = ot.emd(a, b, M1)
+G2 = ot.emd(a, b, M2)
+Gp = ot.emd(a, b, Mp)
+
+# OT matrices
+pl.figure(3, figsize=(7, 3))
+
+pl.subplot(1, 3, 1)
+ot.plot.plot2D_samples_mat(xs, xt, G1, c=[.5, .5, 1])
+pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
+pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
+pl.axis('equal')
+# pl.legend(loc=0)
+pl.title('OT Euclidean')
+
+pl.subplot(1, 3, 2)
+ot.plot.plot2D_samples_mat(xs, xt, G2, c=[.5, .5, 1])
+pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
+pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
+pl.axis('equal')
+# pl.legend(loc=0)
+pl.title('OT squared Euclidean')
+
+pl.subplot(1, 3, 3)
+ot.plot.plot2D_samples_mat(xs, xt, Gp, c=[.5, .5, 1])
+pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
+pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
+pl.axis('equal')
+# pl.legend(loc=0)
+pl.title('OT sqrt Euclidean')
+pl.tight_layout()
+
+pl.show()
+
+
+##############################################################################
+# Dataset 2 : Partial circle
+##############################################################################
+
+n = 50  # nb samples
+xtot = np.zeros((n + 1, 2))
+xtot[:, 0] = np.cos(
+    (np.arange(n + 1) + 1.0) * 0.9 / (n + 2) * 2 * np.pi)
+xtot[:, 1] = np.sin(
+    (np.arange(n + 1) + 1.0) * 0.9 / (n + 2) * 2 * np.pi)
+
+xs = xtot[:n, :]
+xt = xtot[1:, :]
+
+a, b = ot.unif(n), ot.unif(n)  # uniform distribution on samples
+
+# loss matrix
+M1 = ot.dist(xs, xt, metric='euclidean')
+M1 /= M1.max()
+
+# loss matrix
+M2 = ot.dist(xs, xt, metric='sqeuclidean')
+M2 /= M2.max()
+
+# loss matrix
+Mp = np.sqrt(ot.dist(xs, xt, metric='euclidean'))
+Mp /= Mp.max()
+
+
+# Data
+pl.figure(4, figsize=(7, 3))
+pl.clf()
+pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
+pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
+pl.axis('equal')
+pl.title('Source and traget distributions')
+
+
+# Cost matrices
+pl.figure(5, figsize=(7, 3))
+
+pl.subplot(1, 3, 1)
+pl.imshow(M1, interpolation='nearest')
+pl.title('Euclidean cost')
+
+pl.subplot(1, 3, 2)
+pl.imshow(M2, interpolation='nearest')
+pl.title('Squared Euclidean cost')
+
+pl.subplot(1, 3, 3)
+pl.imshow(Mp, interpolation='nearest')
+pl.title('Sqrt Euclidean cost')
+pl.tight_layout()
+
+##############################################################################
+# Dataset 2 : Plot  OT Matrices
+##############################################################################
+
+
+
+#%% EMD
+G1 = ot.emd(a, b, M1)
+G2 = ot.emd(a, b, M2)
+Gp = ot.emd(a, b, Mp)
+
+# OT matrices
+pl.figure(6, figsize=(7, 3))
+
+pl.subplot(1, 3, 1)
+ot.plot.plot2D_samples_mat(xs, xt, G1, c=[.5, .5, 1])
+pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
+pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
+pl.axis('equal')
+# pl.legend(loc=0)
+pl.title('OT Euclidean')
+
+pl.subplot(1, 3, 2)
+ot.plot.plot2D_samples_mat(xs, xt, G2, c=[.5, .5, 1])
+pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
+pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
+pl.axis('equal')
+# pl.legend(loc=0)
+pl.title('OT squared Euclidean')
+
+pl.subplot(1, 3, 3)
+ot.plot.plot2D_samples_mat(xs, xt, Gp, c=[.5, .5, 1])
+pl.plot(xs[:, 0], xs[:, 1], '+b', label='Source samples')
+pl.plot(xt[:, 0], xt[:, 1], 'xr', label='Target samples')
+pl.axis('equal')
+# pl.legend(loc=0)
+pl.title('OT sqrt Euclidean')
+pl.tight_layout()
 
 pl.show()
diff --git a/examples/plot_barycenter_1D.py b/examples/plot_barycenter_1D.py
index f3be247..142b05e 100644
--- a/examples/plot_barycenter_1D.py
+++ b/examples/plot_barycenter_1D.py
@@ -4,7 +4,7 @@
 1D Wasserstein barycenter demo
 ==============================
 
-This example illustrate the computation of regularized Wassersyein Barycenter 
+This example illustrates the computation of regularized Wassersyein Barycenter 
 as proposed in [3].
 
 
@@ -25,6 +25,9 @@ import ot
 from mpl_toolkits.mplot3d import Axes3D  # noqa
 from matplotlib.collections import PolyCollection
 
+##############################################################################
+# Generate data
+##############################################################################
 
 #%% parameters
 
@@ -45,6 +48,10 @@ n_distributions = A.shape[1]
 M = ot.utils.dist0(n)
 M /= M.max()
 
+##############################################################################
+# Plot data
+##############################################################################
+
 #%% plot the distributions
 
 pl.figure(1, figsize=(6.4, 3))
@@ -53,6 +60,10 @@ for i in range(n_distributions):
 pl.title('Distributions')
 pl.tight_layout()
 
+##############################################################################
+# Barycenter computation
+##############################################################################
+
 #%% barycenter computation
 
 alpha = 0.2  # 0<=alpha<=1
@@ -79,6 +90,10 @@ pl.legend()
 pl.title('Barycenters')
 pl.tight_layout()
 
+##############################################################################
+# Barycentric interpolation
+##############################################################################
+
 #%% barycenter interpolation
 
 n_alpha = 11
diff --git a/examples/plot_compute_emd.py b/examples/plot_compute_emd.py
index 704da0e..b688f93 100644
--- a/examples/plot_compute_emd.py
+++ b/examples/plot_compute_emd.py
@@ -4,6 +4,10 @@
 Plot multiple EMD
 =================
 
+Shows how to compute multiple EMD and Sinkhorn with two differnt 
+ground metrics and plot their values for diffeent distributions.
+
+
 """
 
 # Author: Remi Flamary <remi.flamary@unice.fr>
diff --git a/examples/plot_optim_OTreg.py b/examples/plot_optim_OTreg.py
index 95bcdaf..b362662 100644
--- a/examples/plot_optim_OTreg.py
+++ b/examples/plot_optim_OTreg.py
@@ -4,8 +4,8 @@
 Regularized OT with generic solver
 ==================================
 
-This example illustrate the use of the generic solver for regularized OT with
-user designed regularization term. It uses Conditional gradient as in [6] and 
+Illustrates the use of the generic solver for regularized OT with
+user-designed regularization term. It uses Conditional gradient as in [6] and 
 generalized Conditional Gradient as proposed in [5][7].
 
 
diff --git a/examples/plot_otda_mapping.py b/examples/plot_otda_mapping.py
index e0da2d8..e78fef4 100644
--- a/examples/plot_otda_mapping.py
+++ b/examples/plot_otda_mapping.py
@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 """
-===============================================
-OT mapping estimation for domain adaptation [8]
-===============================================
+===========================================
+OT mapping estimation for domain adaptation
+===========================================
 
 This example presents how to use MappingTransport to estimate at the same
 time both the coupling transport and approximate the transport map with either
@@ -24,7 +24,7 @@ import ot
 
 
 ##############################################################################
-# generate data
+# Generate data
 ##############################################################################
 
 n_source_samples = 100
@@ -44,7 +44,7 @@ Xt[yt == 2] *= 3
 Xt = Xt + 4
 
 ##############################################################################
-# plot data
+# Plot data
 ##############################################################################
 
 pl.figure(1, (10, 5))
diff --git a/examples/plot_otda_mapping_colors_images.py b/examples/plot_otda_mapping_colors_images.py
index a8b2ca8..162c24b 100644
--- a/examples/plot_otda_mapping_colors_images.py
+++ b/examples/plot_otda_mapping_colors_images.py
@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 """
-===============================================
-OT for color adaptation with mapping estimation 
-===============================================
+=====================================================
+OT for image color adaptation with mapping estimation 
+=====================================================
 
 OT for domain adaptation with image color adaptation [6] with mapping 
 estimation [8].