working on the guide

Author: rflamary

docs/source/conf.py

@@ -347,7 +347,7 @@ def __getattr__(cls, name):
 }
 
 sphinx_gallery_conf = {
-    "examples_dirs": ["../../examples", "../../examples/da"],
+    "examples_dirs": ["../../examples"],
     "gallery_dirs": "auto_examples",
     "filename_pattern": "plot_",  # (?!barycenter_fgw)
     "nested_sections": False,

examples/plot_OT_2D_samples.py

@@ -65,7 +65,7 @@
 
 # %% EMD
 
-G0 = ot.emd(a, b, M)
+G0 = ot.solve(M, a, b).plan
 
 pl.figure(3)
 pl.imshow(G0, interpolation="nearest")

examples/plot_quickstart_guide.py

@@ -5,18 +5,22 @@
 =============================================
 
 
-This is a quickstart guide to the Python Optimal Transport (POT) toolbox. We use
-here the new API of POT which is more flexible and allows to solve a wider range
-of problems with just a few functions. The old API is still available (the new
-one is a convenient wrapper around the old one) and we provide pointers to the
-old API when needed.
+Quickstart guide to the POT toolbox.
+
+For better readability, only the use of POT is provided and the plotting code
+with matplotlib is hidden (but is available in the source file of the example).
+
+.. note::
+    We use here the new API of POT which is more flexible and allows to solve a wider range of problems with just a few functions. The old API is still available (the new
+    one is a convenient wrapper around the old one) and we provide pointers to the
+    old API when needed.
 
 """
 
 # Author: Remi Flamary
 #
 # License: MIT License
-# sphinx_gallery_thumbnail_number = 1
+# sphinx_gallery_thumbnail_number = 4
 
 # Import necessary libraries
 
@@ -43,18 +47,12 @@
 b = ot.utils.unif(n2)  # weights of points in the target domain
 
 x1 = np.random.randn(n1, 2)
-x1 /= (
-    np.sqrt(np.sum(x1**2, 1, keepdims=True)) / 2
-)  # project on the unit circle and scale
-x2 = np.random.randn(n2, 2)
-x2 /= (
-    np.sqrt(np.sum(x2**2, 1, keepdims=True)) / 4
-)  # project on the unit circle and scale
+x1 /= np.sqrt(np.sum(x1**2, 1, keepdims=True)) / 2
 
-# %%
-# Plot data
-# ~~~~~~~~~
+x2 = np.random.randn(n2, 2)
+x2 /= np.sqrt(np.sum(x2**2, 1, keepdims=True)) / 4
 
+# sphinx_gallery_start_ignore
 style = {"markeredgecolor": "k"}
 
 pl.figure(1, (4, 4))
@@ -63,8 +61,13 @@
 pl.legend(loc=0)
 pl.title("Source and target distributions")
 pl.show()
+# sphinx_gallery_end_ignore
 
 # %%
+# We illustrate above the simple example of two 2D distributions with 25 and 50
+# samples respectively located on circles. The weights of the samples are
+# uniform.
+#
 # Solving exact Optimal Transport
 # -------------------------------
 # Solve the Optimal Transport problem between the samples
@@ -88,31 +91,7 @@
 
 print(f"OT loss = {loss:1.3f}")
 
-# %%
-# We provide
-# the weights of the samples in the source and target domains :code:`a` and
-# :code:`b`. If not provided, the weights are assumed to be uniform.
-#
-# The :class:`ot.utils.OTResult` object contains the following attributes:
-#
-# - :code:`value`: the value of the OT problem
-# - :code:`plan`: the OT matrix
-# - :code:`potentials`: Dual potentials of the OT problem
-# - :code:`log`: log dictionary of the solver
-#
-# The OT matrix :math:`P` is a matrix of size :code:`(n1, n2)` where
-# :code:`P[i,j]` is the amount of mass
-# transported from :code:`x1[i]` to :code:`x2[j]`.
-#
-# The OT loss is the sum of the element-wise product of the OT matrix and the
-# cost matrix taken by default as the Squared Euclidean distance.
-#
-
-# %%
-# Plot the OT plan and dual potentials
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-
+# sphinx_gallery_start_ignore
 from ot.plot import plot2D_samples_mat
 
 pl.figure(1, (8, 4))
@@ -134,6 +113,32 @@
 pl.imshow(P, cmap="Greys")
 pl.title("OT plan")
 pl.show()
+# sphinx_gallery_end_ignore
+
+# %%
+# The figure above shows the Optimal Transport plan between the source and target
+# samples. The color intensity represents the amount of mass transported
+# between the samples. The dual potentials of the OT problem are also shown.
+#
+# The weights of the samples in the source and target domains :code:`a` and
+# :code:`b` are given to the function. If not provided, the weights are assumed
+# to be uniform See :func:`ot.solve_sample` for more details.
+#
+# The :class:`ot.utils.OTResult` object contains the following attributes:
+#
+# - :code:`value`: the value of the OT problem
+# - :code:`plan`: the OT matrix
+# - :code:`potentials`: Dual potentials of the OT problem
+# - :code:`log`: log dictionary of the solver
+#
+# The OT matrix :math:`P` is a matrix of size :code:`(n1, n2)` where
+# :code:`P[i,j]` is the amount of mass
+# transported from :code:`x1[i]` to :code:`x2[j]`.
+#
+# The OT loss is the sum of the element-wise product of the OT matrix and the
+# cost matrix taken by default as the Squared Euclidean distance.
+#
+
 
 # %%
 # Solve the Optimal Transport problem with a custom cost matrix
@@ -155,8 +160,21 @@
 # Compute the OT loss (equivalent to ot.solve(C).value)
 loss_city = np.sum(P_city * C)
 
+# sphinx_gallery_start_ignore
+pl.figure(1, (3, 3))
+plot2D_samples_mat(x1, x2, P)
+pl.plot(x1[:, 0], x1[:, 1], "ob", label="Source samples", **style)
+pl.plot(x2[:, 0], x2[:, 1], "or", label="Target samples", **style)
+pl.title("OT plan (Citybloc) loss={:.3f}".format(loss_city))
+
+pl.figure(2, (3, 1.7))
+pl.imshow(P_city, cmap="Greys")
+pl.title("OT plan (Citybloc)")
+pl.show()
+# sphinx_gallery_end_ignore
+
 # %%
-# Note that we show here how to sole the OT problem with a custom cost matrix
+# Note that we show here how to solve the OT problem with a custom cost matrix
 # with the more general :func:`ot.solve` function.
 # But the same can be done with the :func:`ot.solve_sample` function by passing
 # :code:`metric='cityblock'` as argument.
@@ -171,20 +189,9 @@
 #       P = ot.emd(a, b, C)
 #       loss = ot.emd2(a, b, C) # same as np.sum(P*C) but differentiable wrt a/b
 #
-# Plot the OT plan and dual potentials for other loss
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# .. minigallery:: ot.emd2 ot.emd ot.solve ot.solve_sample
 #
 
-pl.figure(1, (3, 3))
-plot2D_samples_mat(x1, x2, P)
-pl.plot(x1[:, 0], x1[:, 1], "ob", label="Source samples", **style)
-pl.plot(x2[:, 0], x2[:, 1], "or", label="Target samples", **style)
-pl.title("OT plan (Citybloc) loss={:.3f}".format(loss_city))
-
-pl.figure(2, (3, 1.7))
-pl.imshow(P_city, cmap="Greys")
-pl.title("OT plan (Citybloc)")
-pl.show()
 
 # %%
 # Sinkhorn and Regularized OT
@@ -202,25 +209,60 @@
 loss_sink = sol.value  # objective value of the Sinkhorn problem (incl. entropy)
 loss_sink_linear = sol.value_linear  # np.sum(P_sink * C) linear part of loss
 
+# sphinx_gallery_start_ignore
+pl.figure(1, (3, 3))
+plot2D_samples_mat(x1, x2, P_sink)
+pl.plot(x1[:, 0], x1[:, 1], "ob", label="Source samples", **style)
+pl.plot(x2[:, 0], x2[:, 1], "or", label="Target samples", **style)
+pl.title("Sinkhorn OT plan loss={:.3f}".format(loss_sink))
+pl.show()
+
+pl.figure(2, (3, 1.7))
+pl.imshow(P_sink, cmap="Greys")
+pl.title("Sinkhorn OT plan")
+pl.show()
+# sphinx_gallery_end_ignore
 # %%
 # The Sinkhorn algorithm solves the Entropic Regularized OT problem. The
 # regularization strength can be controlled with the :code:`reg` parameter.
 # The Sinkhorn algorithm can be faster than the exact OT solver for large
 # regularization strength but the solution is only an approximation of the
 # exact OT problem and the OT plan is not sparse.
-#
-# Plot the OT plan and dual potentials for Sinkhorn
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+# %%
+# Solve the Regularized OT problem with other regularizations
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
 
-pl.figure(1, (3, 3))
+# Use quadratic regularization
+P_quad = ot.solve_sample(x1, x2, a, b, reg=3, reg_type="L2").plan
+
+loss_quad = ot.solve_sample(x1, x2, a, b, reg=3, reg_type="L2").value
+
+# sphinx_gallery_start_ignore
+pl.figure(1, (9, 3))
+
+pl.subplot(1, 3, 1)
+plot2D_samples_mat(x1, x2, P)
+pl.plot(x1[:, 0], x1[:, 1], "ob", label="Source samples", **style)
+pl.plot(x2[:, 0], x2[:, 1], "or", label="Target samples", **style)
+pl.title("OT plan loss={:.3f}".format(loss))
+
+pl.subplot(1, 3, 2)
 plot2D_samples_mat(x1, x2, P_sink)
 pl.plot(x1[:, 0], x1[:, 1], "ob", label="Source samples", **style)
 pl.plot(x2[:, 0], x2[:, 1], "or", label="Target samples", **style)
-pl.title("Sinkhorn OT plan loss={:.3f}".format(loss_sink))
-pl.show()
+pl.title("Sinkhorn plan loss={:.3f}".format(loss_sink))
 
-pl.figure(2, (3, 1.7))
-pl.imshow(P_sink, cmap="Greys")
-pl.title("Sinkhorn OT plan")
+pl.subplot(1, 3, 3)
+plot2D_samples_mat(x1, x2, P_quad)
+pl.plot(x1[:, 0], x1[:, 1], "ob", label="Source samples", **style)
+pl.plot(x2[:, 0], x2[:, 1], "or", label="Target samples", **style)
+pl.title("Quadratic plan loss={:.3f}".format(loss_quad))
 pl.show()
+# sphinx_gallery_end_ignore
+# %%
+# We plot above the OT plans obtained with different regularizations. The
+# quadratic regularization is another common choice for regularized OT and
+# preserves the sparsity of the OT plan.
+#