diff options
Diffstat (limited to 'src/python/doc')
| -rw-r--r-- | src/python/doc/_templates/layout.html | 16 | ||||
| -rw-r--r-- | src/python/doc/alpha_complex_sum.inc | 6 | ||||
| -rw-r--r-- | src/python/doc/alpha_complex_user.rst | 34 | ||||
| -rwxr-xr-x | src/python/doc/conf.py | 2 | ||||
| -rw-r--r-- | src/python/doc/cubical_complex_user.rst | 3 | ||||
| -rw-r--r-- | src/python/doc/examples.rst | 3 | ||||
| -rw-r--r-- | src/python/doc/img/sklearn-tda.png | bin | 0 -> 388075 bytes | |||
| -rw-r--r-- | src/python/doc/index.rst | 16 | ||||
| -rw-r--r-- | src/python/doc/installation.rst | 64 | ||||
| -rw-r--r-- | src/python/doc/persistence_graphical_tools_user.rst | 26 | ||||
| -rw-r--r-- | src/python/doc/reader_utils_ref.rst | 2 | ||||
| -rw-r--r-- | src/python/doc/representations.rst | 72 | ||||
| -rw-r--r-- | src/python/doc/representations_sum.inc | 14 | ||||
| -rw-r--r-- | src/python/doc/rips_complex_user.rst | 26 | ||||
| -rw-r--r-- | src/python/doc/simplex_tree_user.rst | 10 | ||||
| -rw-r--r-- | src/python/doc/tangential_complex_user.rst | 6 | ||||
| -rw-r--r-- | src/python/doc/wasserstein_distance_sum.inc | 14 | ||||
| -rw-r--r-- | src/python/doc/wasserstein_distance_user.rst | 40 | ||||
| -rw-r--r-- | src/python/doc/witness_complex_user.rst | 6 |
19 files changed, 288 insertions, 72 deletions
diff --git a/src/python/doc/_templates/layout.html b/src/python/doc/_templates/layout.html index fe64fb3d..2f2d9c72 100644 --- a/src/python/doc/_templates/layout.html +++ b/src/python/doc/_templates/layout.html @@ -56,12 +56,16 @@ </a></p> {%- endif %} {%- endblock %} - <h2><a href="index.html">GUDHI</a></h2> - <h2><a href="fileformats.html">File formats</a></h2> - <h2><a href="installation.html">GUDHI installation</a></h2> - <h2><a href="citation.html">Acknowledging the GUDHI library</a></h2> - <h2><a href="genindex.html">Index</a></h2> - <h2><a href="examples.html">Examples</a></h2> + <b> + <ul style="list-style-type:circle;"> + <li><a href="index.html">Modules</a></li> + <li><a href="installation.html">Installation</a></li> + <li><a href="examples.html">Examples</a></li> + <li><a href="fileformats.html">File formats</a></li> + <li><a href="citation.html">Acknowledging</a></li> + <li><a href="genindex.html">Index</a></li> + </ul> + </b> {%- if sidebars != None %} {#- new style sidebar: explicitly include/exclude templates #} {%- for sidebartemplate in sidebars %} diff --git a/src/python/doc/alpha_complex_sum.inc b/src/python/doc/alpha_complex_sum.inc index c5ba9dc7..a1184663 100644 --- a/src/python/doc/alpha_complex_sum.inc +++ b/src/python/doc/alpha_complex_sum.inc @@ -9,9 +9,9 @@ | | circumradius of the simplex if the circumsphere is empty (the simplex | :Copyright: MIT (`GPL v3 </licensing/>`_) | | | is then said to be Gabriel), and as the minimum of the filtration | | | | values of the codimension 1 cofaces that make it not Gabriel | :Requires: `Eigen <installation.html#eigen>`__ :math:`\geq` 3.1.0 and `CGAL <installation.html#cgal>`__ :math:`\geq` 4.11.0 | - | | otherwise. All simplices that have a filtration value strictly | | - | | greater than a given alpha squared value are not inserted into the | | - | | complex. | | + | | otherwise. All simplices that have a filtration value | | + | | :math:`> \alpha^2` are removed from the Delaunay complex | | + | | when creating the simplicial complex if it is specified. | | | | | | | | This package requires having CGAL version 4.7 or higher (4.8.1 is | | | | advised for better performance). | | diff --git a/src/python/doc/alpha_complex_user.rst b/src/python/doc/alpha_complex_user.rst index f9662a6d..60319e84 100644 --- a/src/python/doc/alpha_complex_user.rst +++ b/src/python/doc/alpha_complex_user.rst @@ -9,19 +9,20 @@ Definition .. include:: alpha_complex_sum.inc -Alpha_complex is constructing a :doc:`Simplex_tree <simplex_tree_ref>` using +`AlphaComplex` is constructing a :doc:`SimplexTree <simplex_tree_ref>` using `Delaunay Triangulation <http://doc.cgal.org/latest/Triangulation/index.html#Chapter_Triangulations>`_ -:cite:`cgal:hdj-t-15b` from `CGAL <http://www.cgal.org/>`_ (the Computational Geometry Algorithms Library -:cite:`cgal:eb-15b`). +:cite:`cgal:hdj-t-19b` from `CGAL <http://www.cgal.org/>`_ (the Computational Geometry Algorithms Library +:cite:`cgal:eb-19b`). Remarks ^^^^^^^ -When Alpha_complex is constructed with an infinite value of :math:`\alpha`, the complex is a Delaunay complex. +When an :math:`\alpha`-complex is constructed with an infinite value of :math:`\alpha^2`, +the complex is a Delaunay complex (with special filtration values). Example from points ------------------- -This example builds the Delaunay triangulation from the given points, and initializes the alpha complex with it: +This example builds the alpha-complex from the given points: .. testcode:: @@ -137,18 +138,20 @@ sets the filtration value (0 in case of a vertex - propagation will have no effe Non decreasing filtration values ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -As the squared radii computed by CGAL are an approximation, it might happen that these alpha squared values do not -quite define a proper filtration (i.e. non-decreasing with respect to inclusion). -We fix that up by calling `Simplex_tree::make_filtration_non_decreasing()` (cf. +As the squared radii computed by CGAL are an approximation, it might happen that these +:math:`\alpha^2` values do not quite define a proper filtration (i.e. non-decreasing with +respect to inclusion). +We fix that up by calling :func:`~gudhi.SimplexTree.make_filtration_non_decreasing` (cf. `C++ version <http://gudhi.gforge.inria.fr/doc/latest/index.html>`_). Prune above given filtration value ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The simplex tree is pruned from the given maximum alpha squared value (cf. `Simplex_tree::prune_above_filtration()` -in the `C++ version <http://gudhi.gforge.inria.fr/doc/latest/index.html>`_). Note that this does not provide any kind -of speed-up, since we always first build the full filtered complex, so it is recommended not to use `max_alpha_square`. -In the following example, a threshold of 59 is used. +The simplex tree is pruned from the given maximum :math:`\alpha^2` value (cf. +:func:`~gudhi.SimplexTree.prune_above_filtration`). Note that this does not provide any kind +of speed-up, since we always first build the full filtered complex, so it is recommended not to use +:paramref:`~gudhi.AlphaComplex.create_simplex_tree.max_alpha_square`. +In the following example, a threshold of :math:`\alpha^2 = 32.0` is used. Example from OFF file @@ -165,7 +168,7 @@ Then, it is asked to display information about the alpha complex: import gudhi alpha_complex = gudhi.AlphaComplex(off_file=gudhi.__root_source_dir__ + \ '/data/points/alphacomplexdoc.off') - simplex_tree = alpha_complex.create_simplex_tree(max_alpha_square=59.0) + simplex_tree = alpha_complex.create_simplex_tree(max_alpha_square=32.0) result_str = 'Alpha complex is of dimension ' + repr(simplex_tree.dimension()) + ' - ' + \ repr(simplex_tree.num_simplices()) + ' simplices - ' + \ repr(simplex_tree.num_vertices()) + ' vertices.' @@ -178,7 +181,7 @@ the program output is: .. testoutput:: - Alpha complex is of dimension 2 - 23 simplices - 7 vertices. + Alpha complex is of dimension 2 - 20 simplices - 7 vertices. [0] -> 0.00 [1] -> 0.00 [2] -> 0.00 @@ -199,9 +202,6 @@ the program output is: [4, 6] -> 22.74 [4, 5, 6] -> 22.74 [3, 6] -> 30.25 - [2, 6] -> 36.50 - [2, 3, 6] -> 36.50 - [2, 4, 6] -> 37.24 CGAL citations ============== diff --git a/src/python/doc/conf.py b/src/python/doc/conf.py index e4c718c3..3cc5d1d6 100755 --- a/src/python/doc/conf.py +++ b/src/python/doc/conf.py @@ -39,7 +39,9 @@ extensions = [ 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', + 'sphinx.ext.napoleon', 'sphinxcontrib.bibtex', + 'sphinx_paramlinks', ] todo_include_todos = True diff --git a/src/python/doc/cubical_complex_user.rst b/src/python/doc/cubical_complex_user.rst index b13b500e..56cf0170 100644 --- a/src/python/doc/cubical_complex_user.rst +++ b/src/python/doc/cubical_complex_user.rst @@ -142,8 +142,7 @@ Or it can be defined as follows: .. testcode:: from gudhi import PeriodicCubicalComplex as pcc - periodic_cc = pcc(dimensions=[3,3], - top_dimensional_cells= [0, 0, 0, 0, 1, 0, 0, 0, 0], + periodic_cc = pcc(top_dimensional_cells = [[0, 0, 0], [0, 1, 0], [0, 0, 0]], periodic_dimensions=[True, False]) result_str = 'Periodic cubical complex is of dimension ' + repr(periodic_cc.dimension()) + ' - ' + \ repr(periodic_cc.num_simplices()) + ' simplices.' diff --git a/src/python/doc/examples.rst b/src/python/doc/examples.rst index edbc2f72..a42227e3 100644 --- a/src/python/doc/examples.rst +++ b/src/python/doc/examples.rst @@ -16,6 +16,9 @@ Examples * :download:`periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py <../example/periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py>` * :download:`bottleneck_basic_example.py <../example/bottleneck_basic_example.py>` * :download:`gudhi_graphical_tools_example.py <../example/gudhi_graphical_tools_example.py>` + * :download:`plot_simplex_tree_dim012.py <../example/plot_simplex_tree_dim012.py>` + * :download:`plot_rips_complex.py <../example/plot_rips_complex.py>` + * :download:`plot_alpha_complex.py <../example/plot_alpha_complex.py>` * :download:`witness_complex_from_nearest_landmark_table.py <../example/witness_complex_from_nearest_landmark_table.py>` * :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>` diff --git a/src/python/doc/img/sklearn-tda.png b/src/python/doc/img/sklearn-tda.png Binary files differnew file mode 100644 index 00000000..f0ff07f4 --- /dev/null +++ b/src/python/doc/img/sklearn-tda.png diff --git a/src/python/doc/index.rst b/src/python/doc/index.rst index e379bc23..c36a578f 100644 --- a/src/python/doc/index.rst +++ b/src/python/doc/index.rst @@ -1,5 +1,5 @@ -GUDHI Python module documentation -################################# +GUDHI Python modules documentation +################################## .. figure:: ../../doc/common/Gudhi_banner.png @@ -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..40f3f44b 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 ********* @@ -40,6 +40,20 @@ To build the GUDHI Python module, run the following commands in a terminal: cd python make +.. note:: + + :code:`make python` (or :code:`make` in python directory) is only a + `CMake custom targets <https://cmake.org/cmake/help/latest/command/add_custom_target.html>`_ + to shortcut :code:`python setup.py build_ext --inplace` command. + No specific other options (:code:`-j8` for parallel, or even :code:`make clean`, ...) are + available. + But one can use :code:`python setup.py ...` specific options in the python directory: + +.. code-block:: bash + + python setup.py clean --all # Clean former compilation + python setup.py build_ext -j 8 --inplace # Build in parallel + GUDHI Python module installation ================================ @@ -59,19 +73,40 @@ Or install it definitely in your Python packages folder: # May require sudo or administrator privileges make install +.. note:: + + :code:`make install` is only a + `CMake custom targets <https://cmake.org/cmake/help/latest/command/add_custom_target.html>`_ + to shortcut :code:`python setup.py install` command. + It does not take into account :code:`CMAKE_INSTALL_PREFIX`. + But one can use :code:`python setup.py install ...` specific options in the python directory: + +.. code-block:: bash + + python setup.py install --prefix /home/gudhi # Install in /home/gudhi directory Test suites =========== -To test your build, `py.test <http://doc.pytest.org>`_ is optional. Run the -following command in a terminal: +To test your build, `py.test <http://doc.pytest.org>`_ is required. Run the +following `Ctest <https://cmake.org/cmake/help/latest/manual/ctest.1.html>`_ +(CMake test driver program) command in a terminal: .. code-block:: bash cd /path-to-gudhi/build/python # For windows, you have to set PYTHONPATH environment variable export PYTHONPATH='$PYTHONPATH:/path-to-gudhi/build/python' - make test + ctest + +.. note:: + + One can use :code:`ctest` specific options in the python directory: + +.. code-block:: bash + + # Launch tests in parallel on 8 cores and set failing tests in verbose mode + ctest -j 8 --output-on-failure Debugging issues ================ @@ -215,12 +250,27 @@ 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. + +Scikit-learn +============ + +The :doc:`persistence representations </representations>` module require +`scikit-learn <https://scikit-learn.org/>`_, a Python-based ecosystem of +open-source software for machine learning. + 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/persistence_graphical_tools_user.rst b/src/python/doc/persistence_graphical_tools_user.rst index b2124fdd..80002db6 100644 --- a/src/python/doc/persistence_graphical_tools_user.rst +++ b/src/python/doc/persistence_graphical_tools_user.rst @@ -20,16 +20,17 @@ This function can display the persistence result as a barcode: .. plot:: :include-source: + import matplotlib.pyplot as plot import gudhi off_file = gudhi.__root_source_dir__ + '/data/points/tore3D_300.off' - point_cloud = gudhi.read_off(off_file=off_file) + point_cloud = gudhi.read_points_from_off_file(off_file=off_file) rips_complex = gudhi.RipsComplex(points=point_cloud, max_edge_length=0.7) simplex_tree = rips_complex.create_simplex_tree(max_dimension=3) diag = simplex_tree.persistence(min_persistence=0.4) - plot = gudhi.plot_persistence_barcode(diag) + gudhi.plot_persistence_barcode(diag) plot.show() Show persistence as a diagram @@ -43,14 +44,15 @@ This function can display the persistence result as a diagram: .. plot:: :include-source: + import matplotlib.pyplot as plot import gudhi # rips_on_tore3D_1307.pers obtained from write_persistence_diagram method persistence_file=gudhi.__root_source_dir__ + \ '/data/persistence_diagram/rips_on_tore3D_1307.pers' - plt = gudhi.plot_persistence_diagram(persistence_file=persistence_file, + gudhi.plot_persistence_diagram(persistence_file=persistence_file, legend=True) - plt.show() + plot.show() Persistence density ------------------- @@ -63,11 +65,19 @@ If you want more information on a specific dimension, for instance: .. plot:: :include-source: + import matplotlib.pyplot as plot import gudhi - # rips_on_tore3D_1307.pers obtained from write_persistence_diagram method persistence_file=gudhi.__root_source_dir__ + \ '/data/persistence_diagram/rips_on_tore3D_1307.pers' - plt = gudhi.plot_persistence_density(persistence_file=persistence_file, - max_intervals=0, dimension=1, legend=True) - plt.show() + birth_death = gudhi.read_persistence_intervals_in_dimension( + persistence_file=persistence_file, + only_this_dim=1) + pers_diag = [(1, elt) for elt in birth_death] + # Use subplots to display diagram and density side by side + fig, axes = plot.subplots(nrows=1, ncols=2, figsize=(12, 5)) + gudhi.plot_persistence_diagram(persistence=pers_diag, + axes=axes[0]) + gudhi.plot_persistence_density(persistence=pers_diag, + dimension=1, legend=True, axes=axes[1]) + plot.show() diff --git a/src/python/doc/reader_utils_ref.rst b/src/python/doc/reader_utils_ref.rst index f3ecebad..b8977a5a 100644 --- a/src/python/doc/reader_utils_ref.rst +++ b/src/python/doc/reader_utils_ref.rst @@ -6,7 +6,7 @@ Reader utils reference manual ============================= -.. autofunction:: gudhi.read_off +.. autofunction:: gudhi.read_points_from_off_file .. autofunction:: gudhi.read_lower_triangular_matrix_from_csv_file diff --git a/src/python/doc/representations.rst b/src/python/doc/representations.rst new file mode 100644 index 00000000..11dcbcf9 --- /dev/null +++ b/src/python/doc/representations.rst @@ -0,0 +1,72 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + +====================== +Representations manual +====================== + +.. include:: representations_sum.inc + +This module, originally available at https://github.com/MathieuCarriere/sklearn-tda and named sklearn_tda, aims at bridging the gap between persistence diagrams and machine learning, by providing implementations of most of the vector representations for persistence diagrams in the literature, in a scikit-learn format. More specifically, it provides tools, using the scikit-learn standard interface, to compute distances and kernels on persistence diagrams, and to convert these diagrams into vectors in Euclidean space. + +A diagram is represented as a numpy array of shape (n,2), as can be obtained from :func:`~gudhi.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: + +Basic example +------------- + +This example computes the first two Landscapes associated to a persistence diagram with four points. The landscapes are evaluated on ten samples, leading to two vectors with ten coordinates each, that are eventually concatenated in order to produce a single vector representation. + +.. testcode:: + + import numpy as np + from gudhi.representations import Landscape + # A single diagram with 4 points + D = np.array([[0.,4.],[1.,2.],[3.,8.],[6.,8.]]) + diags = [D] + l=Landscape(num_landscapes=2,resolution=10).fit_transform(diags) + print(l) + +The output is: + +.. testoutput:: + + [[1.02851895 2.05703791 2.57129739 1.54277843 0.89995409 1.92847304 + 2.95699199 3.08555686 2.05703791 1.02851895 0. 0.64282435 + 0. 0. 0.51425948 0. 0. 0. + 0.77138922 1.02851895]] diff --git a/src/python/doc/representations_sum.inc b/src/python/doc/representations_sum.inc new file mode 100644 index 00000000..700828f1 --- /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 | + | img/sklearn-tda.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/rips_complex_user.rst b/src/python/doc/rips_complex_user.rst index 3f6b960d..a27573e8 100644 --- a/src/python/doc/rips_complex_user.rst +++ b/src/python/doc/rips_complex_user.rst @@ -40,12 +40,12 @@ A vertex name corresponds to the index of the point in the given range (aka. the On this example, as edges (4,5), (4,6) and (5,6) are in the complex, simplex (4,5,6) is added with the filtration value set with :math:`max(filtration(4,5), filtration(4,6), filtration(5,6))`. And so on for simplex (0,1,2,3). -If the `RipsComplex` interfaces are not detailed enough for your need, please refer to rips_persistence_step_by_step.cpp -C++ example, where the graph construction over the Simplex_tree is more detailed. +If the :doc:`RipsComplex <rips_complex_ref>` interfaces are not detailed enough for your need, please refer to +rips_persistence_step_by_step.cpp C++ example, where the graph construction over the Simplex_tree is more detailed. A Rips complex can easily become huge, even if we limit the length of the edges and the dimension of the simplices. One easy trick, before building a Rips -complex on a point cloud, is to call `sparsify_point_set` which removes points +complex on a point cloud, is to call :func:`~gudhi.sparsify_point_set` which removes points that are too close to each other. This does not change its persistence diagram by more than the length used to define "too close". @@ -57,7 +57,7 @@ a :math:`\frac{1}{1-\varepsilon}`-interleaving, although in practice the error is usually smaller. A more intuitive presentation of the idea is available in :cite:`cavanna15geometric`, and in a video :cite:`cavanna15visualizing`. Passing an extra argument `sparse=0.3` at the -construction of a `RipsComplex` object asks it to build a sparse Rips with +construction of a :class:`~gudhi.RipsComplex` object asks it to build a sparse Rips with parameter :math:`\varepsilon=0.3`, while the default `sparse=None` builds the regular Rips complex. @@ -69,7 +69,7 @@ Example from a point cloud ^^^^^^^^^^^^^^^^^^^^^^^^^^ This example builds the neighborhood graph from the given points, up to max_edge_length. -Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it. +Then it creates a :doc:`SimplexTree <simplex_tree_ref>` with it. Finally, it is asked to display information about the simplicial complex. @@ -128,7 +128,7 @@ Example from OFF file This example builds the :doc:`RipsComplex <rips_complex_ref>` from the given points in an OFF file, and max_edge_length value. -Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it. +Then it creates a :doc:`SimplexTree <simplex_tree_ref>` with it. Finally, it is asked to display information about the Rips complex. @@ -136,7 +136,8 @@ Finally, it is asked to display information about the Rips complex. .. testcode:: import gudhi - point_cloud = gudhi.read_off(off_file=gudhi.__root_source_dir__ + '/data/points/alphacomplexdoc.off') + off_file = gudhi.__root_source_dir__ + '/data/points/alphacomplexdoc.off' + point_cloud = gudhi.read_points_from_off_file(off_file = off_file) rips_complex = gudhi.RipsComplex(points=point_cloud, max_edge_length=12.0) simplex_tree = rips_complex.create_simplex_tree(max_dimension=1) result_str = 'Rips complex is of dimension ' + repr(simplex_tree.dimension()) + ' - ' + \ @@ -178,7 +179,7 @@ Example from a distance matrix ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This example builds the one skeleton graph from the given distance matrix, and max_edge_length value. -Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it. +Then it creates a :doc:`SimplexTree <simplex_tree_ref>` with it. Finally, it is asked to display information about the simplicial complex. @@ -233,7 +234,7 @@ Example from csv file This example builds the :doc:`RipsComplex <rips_complex_ref>` from the given distance matrix in a csv file, and max_edge_length value. -Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it. +Then it creates a :doc:`SimplexTree <simplex_tree_ref>` with it. Finally, it is asked to display information about the Rips complex. @@ -286,7 +287,7 @@ Example from a correlation matrix Analogously to the case of distance matrix, Rips complexes can be also constructed based on correlation matrix. Given a correlation matrix M, comportment-wise 1-M is a distance matrix. This example builds the one skeleton graph from the given corelation matrix and threshold value. -Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it. +Then it creates a :doc:`SimplexTree <simplex_tree_ref>` with it. Finally, it is asked to display information about the simplicial complex. @@ -307,7 +308,7 @@ Finally, it is asked to display information about the simplicial complex. [0.01, 0.01, 0.72, 1., 0.7], [0.89, 0.61, 0.03, 0.7, 1.]], float) - distance_matrix = np.ones((correlation_matrix.shape),float) - correlation_matrix + distance_matrix = 1 - correlation_matrix rips_complex = gudhi.RipsComplex(distance_matrix=distance_matrix, max_edge_length=1.0) simplex_tree = rips_complex.create_simplex_tree(max_dimension=1) @@ -342,6 +343,7 @@ until dimension 1 - one skeleton graph in other words), the output is: [1, 3] -> 0.99 .. note:: - As persistence diagrams points will be under the diagonal, + If you compute the persistence diagram and convert distances back to correlation values, + points in the persistence diagram will be under the diagonal, and bottleneck distance and persistence graphical tool will not work properly, this is a known issue. diff --git a/src/python/doc/simplex_tree_user.rst b/src/python/doc/simplex_tree_user.rst index aebeb29f..3df7617f 100644 --- a/src/python/doc/simplex_tree_user.rst +++ b/src/python/doc/simplex_tree_user.rst @@ -23,13 +23,9 @@ scheme. Implementation -------------- -There are two implementation of complexes. The first on is the Simplex_tree data structure. -The simplex tree is an efficient and flexible data structure for representing general (filtered) simplicial complexes. -The data structure is described in :cite`boissonnatmariasimplextreealgorithmica`. - -The second one is the Hasse_complex. The Hasse complex is a data structure representing explicitly all co-dimension 1 -incidence relations in a complex. It is consequently faster when accessing the boundary of a simplex, but is less -compact and harder to construct from scratch. +The :class:`simplex tree<gudhi.SimplexTree>` is an efficient and flexible data structure for representing general +(filtered) simplicial complexes. +The data structure is described in :cite:`boissonnatmariasimplextreealgorithmica`. Example ------- diff --git a/src/python/doc/tangential_complex_user.rst b/src/python/doc/tangential_complex_user.rst index ebfe1e29..852cf5b6 100644 --- a/src/python/doc/tangential_complex_user.rst +++ b/src/python/doc/tangential_complex_user.rst @@ -107,12 +107,12 @@ inconsistencies, but is not guaranteed to succeed. Output ^^^^^^ -The result of the computation is exported as a Simplex_tree. It is the union of +The result of the computation is exported as a :class:`~gudhi.SimplexTree`. It is the union of the stars of all the input points. A vertex in the Simplex Tree is the index of the point in the range provided by the user. The point corresponding to a -vertex can also be obtained through the Tangential_complex::get_point function. +vertex can also be obtained through the :func:`gudhi.TangentialComplex.get_point` function. Note that even if the positions of the points are perturbed, their original -positions are kept (e.g. Tangential_complex::get_point returns the original +positions are kept (e.g. :func:`~gudhi.TangentialComplex.get_point` returns the original position of the point). The result can be obtained after the computation of the Tangential complex diff --git a/src/python/doc/wasserstein_distance_sum.inc b/src/python/doc/wasserstein_distance_sum.inc new file mode 100644 index 00000000..a97f428d --- /dev/null +++ b/src/python/doc/wasserstein_distance_sum.inc @@ -0,0 +1,14 @@ +.. table:: + :widths: 30 50 20 + + +-----------------------------------------------------------------+----------------------------------------------------------------------+------------------------------------------------------------------+ + | .. figure:: | The q-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 q-th root of the sum of the | q-th root of the sum of all edge lengths to the power q. Edge lengths| :Copyright: MIT | + | edge lengths to the power q. | are measured in norm p, for :math:`1 \leq p \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..32999a0c --- /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, order=1., internal_p=2.) + print(message) + +The output is: + +.. testoutput:: + + Wasserstein distance value = 1.45 diff --git a/src/python/doc/witness_complex_user.rst b/src/python/doc/witness_complex_user.rst index 40e94134..7087fa98 100644 --- a/src/python/doc/witness_complex_user.rst +++ b/src/python/doc/witness_complex_user.rst @@ -47,7 +47,7 @@ which leads to definitions of **weak relaxed witness complex** (or just relaxed In particular case of 0-relaxation, weak complex corresponds to **witness complex** introduced in :cite:`de2004topological`, whereas 0-relaxed strong witness complex consists of just vertices and is not very interesting. Hence for small relaxation weak version is preferable. -However, to capture the homotopy type (for example using Gudhi::persistent_cohomology::Persistent_cohomology) it is +However, to capture the homotopy type (for example using :func:`gudhi.SimplexTree.persistence`) it is often necessary to work with higher filtration values. In this case strong relaxed witness complex is faster to compute and offers similar results. @@ -69,7 +69,7 @@ The construction of the Euclidean versions of complexes follow the same scheme: In the non-Euclidean classes, the lists of nearest landmarks are supposed to be given as input. -The constructors take on the steps 1 and 2, while the function 'create_complex' executes the step 3. +The constructors take on the steps 1 and 2, while the function :func:`!create_complex` executes the step 3. Constructing weak relaxed witness complex from an off file ---------------------------------------------------------- @@ -101,7 +101,7 @@ Let's start with a simple example, which reads an off point file and computes a print("#####################################################################") print("EuclideanWitnessComplex creation from points read in a OFF file") - witnesses = gudhi.read_off(off_file=args.file) + witnesses = gudhi.read_points_from_off_file(off_file=args.file) landmarks = gudhi.pick_n_random_points(points=witnesses, nb_points=args.number_of_landmarks) message = "EuclideanWitnessComplex with max_edge_length=" + repr(args.max_alpha_square) + \ |
