diff options
Diffstat (limited to 'src/python/doc')
| -rwxr-xr-x | src/python/doc/conf.py | 1 | ||||
| -rw-r--r-- | src/python/doc/index.rst | 12 | ||||
| -rw-r--r-- | src/python/doc/installation.rst | 16 | ||||
| -rw-r--r-- | src/python/doc/representations.rst | 48 | ||||
| -rw-r--r-- | src/python/doc/representations_sum.inc | 14 | ||||
| -rw-r--r-- | src/python/doc/wasserstein_distance_sum.inc | 14 | ||||
| -rw-r--r-- | src/python/doc/wasserstein_distance_user.rst | 40 |
7 files changed, 140 insertions, 5 deletions
diff --git a/src/python/doc/conf.py b/src/python/doc/conf.py index e4c718c3..64d9cba1 100755 --- a/src/python/doc/conf.py +++ b/src/python/doc/conf.py @@ -39,6 +39,7 @@ extensions = [ 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', + 'sphinx.ext.napoleon', 'sphinxcontrib.bibtex', ] diff --git a/src/python/doc/index.rst b/src/python/doc/index.rst index e379bc23..1ef08096 100644 --- a/src/python/doc/index.rst +++ b/src/python/doc/index.rst @@ -23,7 +23,7 @@ Alpha complex .. include:: alpha_complex_sum.inc Rips complex -------------- +------------ .. include:: rips_complex_sum.inc @@ -73,6 +73,16 @@ Bottleneck distance .. include:: bottleneck_distance_sum.inc +Wasserstein distance +==================== + +.. include:: wasserstein_distance_sum.inc + +Persistence representations +=========================== + +.. include:: representations_sum.inc + Persistence graphical tools =========================== diff --git a/src/python/doc/installation.rst b/src/python/doc/installation.rst index 77d9e8b3..7699a5bb 100644 --- a/src/python/doc/installation.rst +++ b/src/python/doc/installation.rst @@ -8,7 +8,7 @@ Installation Conda ***** The easiest way to install the Python version of GUDHI is using -`conda <https://gudhi.inria.fr/licensing/>`_. +`conda <https://gudhi.inria.fr/conda/>`_. Compiling ********* @@ -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/representations.rst b/src/python/doc/representations.rst new file mode 100644 index 00000000..a137a035 --- /dev/null +++ b/src/python/doc/representations.rst @@ -0,0 +1,48 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + +====================== +Representations manual +====================== + +.. include:: representations_sum.inc + +This module, originally named sklearn_tda, aims at bridging the gap between persistence diagrams and machine learning tools, in particular scikit-learn. It provides tools, using the scikit-learn standard interface, to compute distances and kernels on diagrams, and to convert diagrams into vectors. + +A diagram is represented as a numpy array of shape (n,2), as can be obtained from `SimplexTree.persistence_intervals_in_dimension` for instance. Points at infinity are represented as a numpy array of shape (n,1), storing only the birth time. + +A small example is provided + +.. only:: builder_html + + * :download:`diagram_vectorizations_distances_kernels.py <../example/diagram_vectorizations_distances_kernels.py>` + + +Preprocessing +------------- +.. automodule:: gudhi.representations.preprocessing + :members: + :special-members: + :show-inheritance: + +Vector methods +-------------- +.. automodule:: gudhi.representations.vector_methods + :members: + :special-members: + :show-inheritance: + +Kernel methods +-------------- +.. automodule:: gudhi.representations.kernel_methods + :members: + :special-members: + :show-inheritance: + +Metrics +------- +.. automodule:: gudhi.representations.metrics + :members: + :special-members: + :show-inheritance: diff --git a/src/python/doc/representations_sum.inc b/src/python/doc/representations_sum.inc new file mode 100644 index 00000000..7b167a17 --- /dev/null +++ b/src/python/doc/representations_sum.inc @@ -0,0 +1,14 @@ +.. table:: + :widths: 30 50 20 + + +------------------------------------------------------------------+----------------------------------------------------------------+-----------------------------------------------+ + | .. figure:: | Vectorizations, distances and kernels that work on persistence | :Author: Mathieu Carrière | + | ../../doc/Persistence_representations/average_landscape.png | diagrams, compatible with scikit-learn. | | + | | | :Introduced in: GUDHI 3.1.0 | + | | | | + | | | :Copyright: MIT | + | | | | + | | | :Requires: scikit-learn | + +------------------------------------------------------------------+----------------------------------------------------------------+-----------------------------------------------+ + | * :doc:`representations` | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+ 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..a049cfb5 --- /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.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.wasserstein + 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.wasserstein_distance(diag1, diag2, q=2., p=1.) + print(message) + +The output is: + +.. testoutput:: + + Wasserstein distance value = 1.45 |