diff options
author | Vincent Rouvreau <10407034+VincentRouvreau@users.noreply.github.com> | 2019-11-04 17:41:48 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-11-04 17:41:48 +0100 |
commit | 6e5f3f2c5ed908774c9005fa3ba07694bb2c6b0c (patch) | |
tree | 3e9242cf413e1ca63c258dd704ca04049fccf7a8 /src/python/doc | |
parent | 8e7fabec7a8b79b8f0248ec580e4cd7950f9cec1 (diff) | |
parent | ee4934750e8c9dbdee4874d56921aeb9bf7b7bb7 (diff) |
Merge pull request #95 from tlacombe/wdist-theo
wasserstein distance added on fork
Diffstat (limited to 'src/python/doc')
-rw-r--r-- | src/python/doc/index.rst | 5 | ||||
-rw-r--r-- | src/python/doc/installation.rst | 14 | ||||
-rw-r--r-- | src/python/doc/wasserstein_distance_sum.inc | 14 | ||||
-rw-r--r-- | src/python/doc/wasserstein_distance_user.rst | 40 |
4 files changed, 70 insertions, 3 deletions
diff --git a/src/python/doc/index.rst b/src/python/doc/index.rst index e379bc23..16d918bc 100644 --- a/src/python/doc/index.rst +++ b/src/python/doc/index.rst @@ -73,6 +73,11 @@ Bottleneck distance .. include:: bottleneck_distance_sum.inc +Wasserstein distance +=================== + +.. include:: wasserstein_distance_sum.inc + Persistence graphical tools =========================== diff --git a/src/python/doc/installation.rst b/src/python/doc/installation.rst index 5369efb0..7699a5bb 100644 --- a/src/python/doc/installation.rst +++ b/src/python/doc/installation.rst @@ -215,12 +215,20 @@ The following examples require the `Matplotlib <http://matplotlib.org>`_: * :download:`euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py>` * :download:`euclidean_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_witness_complex_diagram_persistence_from_off_file_example.py>` +Python Optimal Transport +======================== + +The :doc:`Wasserstein distance </wasserstein_distance_user>` +module requires `POT <https://pot.readthedocs.io/>`_, a library that provides +several solvers for optimization problems related to Optimal Transport. + SciPy ===== -The :doc:`persistence graphical tools </persistence_graphical_tools_user>` -module requires `SciPy <http://scipy.org>`_, a Python-based ecosystem of -open-source software for mathematics, science, and engineering. +The :doc:`persistence graphical tools </persistence_graphical_tools_user>` and +:doc:`Wasserstein distance </wasserstein_distance_user>` modules require `SciPy +<http://scipy.org>`_, a Python-based ecosystem of open-source software for +mathematics, science, and engineering. Threading Building Blocks ========================= diff --git a/src/python/doc/wasserstein_distance_sum.inc b/src/python/doc/wasserstein_distance_sum.inc new file mode 100644 index 00000000..ffd4d312 --- /dev/null +++ b/src/python/doc/wasserstein_distance_sum.inc @@ -0,0 +1,14 @@ +.. table:: + :widths: 30 50 20 + + +-----------------------------------------------------------------+----------------------------------------------------------------------+------------------------------------------------------------------+ + | .. figure:: | The p-Wasserstein distance measures the similarity between two | :Author: Theo Lacombe | + | ../../doc/Bottleneck_distance/perturb_pd.png | persistence diagrams. It's the minimum value c that can be achieved | | + | :figclass: align-center | by a perfect matching between the points of the two diagrams (+ all | :Introduced in: GUDHI 3.1.0 | + | | diagonal points), where the value of a matching is defined as the | | + | Wasserstein distance is the p-th root of the sum of the | p-th root of the sum of all edge lengths to the power p. Edge lengths| :Copyright: MIT | + | edge lengths to the power p. | are measured in norm q, for :math:`1 \leq q \leq \infty`. | | + | | | :Requires: Python Optimal Transport (POT) :math:`\geq` 0.5.1 | + +-----------------------------------------------------------------+----------------------------------------------------------------------+------------------------------------------------------------------+ + | * :doc:`wasserstein_distance_user` | | + +-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/src/python/doc/wasserstein_distance_user.rst b/src/python/doc/wasserstein_distance_user.rst new file mode 100644 index 00000000..bcb7f19d --- /dev/null +++ b/src/python/doc/wasserstein_distance_user.rst @@ -0,0 +1,40 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + +Wasserstein distance user manual +=============================== +Definition +---------- + +.. include:: wasserstein_distance_sum.inc + +This implementation is based on ideas from "Large Scale Computation of Means and Cluster for Persistence Diagrams via Optimal Transport". + +Function +-------- +.. autofunction:: gudhi.wasserstein_distance + + +Basic example +------------- + +This example computes the 1-Wasserstein distance from 2 persistence diagrams with euclidean ground metric. +Note that persistence diagrams must be submitted as (n x 2) numpy arrays and must not contain inf values. + +.. testcode:: + + import gudhi + import numpy as np + + diag1 = np.array([[2.7, 3.7],[9.6, 14.],[34.2, 34.974]]) + diag2 = np.array([[2.8, 4.45],[9.5, 14.1]]) + + message = "Wasserstein distance value = " + '%.2f' % gudhi.wasserstein_distance(diag1, diag2, q=2., p=1.) + print(message) + +The output is: + +.. testoutput:: + + Wasserstein distance value = 1.45 |