diff options
Diffstat (limited to 'src/python/doc')
| -rw-r--r-- | src/python/doc/alpha_complex_sum.inc | 6 | ||||
| -rw-r--r-- | src/python/doc/alpha_complex_user.rst | 19 | ||||
| -rw-r--r-- | src/python/doc/cubical_complex_user.rst | 3 | ||||
| -rw-r--r-- | src/python/doc/diagram_readers_ref.rst (renamed from src/python/doc/reader_utils_ref.rst) | 10 | ||||
| -rw-r--r-- | src/python/doc/img/sklearn-tda.png | bin | 0 -> 388075 bytes | |||
| -rw-r--r-- | src/python/doc/index.rst | 44 | ||||
| -rw-r--r-- | src/python/doc/installation.rst | 25 | ||||
| -rw-r--r-- | src/python/doc/persistence_graphical_tools_user.rst | 2 | ||||
| -rw-r--r-- | src/python/doc/point_cloud.rst | 22 | ||||
| -rw-r--r-- | src/python/doc/point_cloud_sum.inc | 15 | ||||
| -rw-r--r-- | src/python/doc/representations.rst | 26 | ||||
| -rw-r--r-- | src/python/doc/representations_sum.inc | 2 | ||||
| -rw-r--r-- | src/python/doc/rips_complex_user.rst | 3 | ||||
| -rw-r--r-- | src/python/doc/wasserstein_distance_sum.inc | 6 | ||||
| -rw-r--r-- | src/python/doc/wasserstein_distance_user.rst | 2 | ||||
| -rw-r--r-- | src/python/doc/witness_complex_user.rst | 2 |
16 files changed, 129 insertions, 58 deletions
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 b7e69e12..60319e84 100644 --- a/src/python/doc/alpha_complex_user.rst +++ b/src/python/doc/alpha_complex_user.rst @@ -16,7 +16,8 @@ Definition Remarks ^^^^^^^ -When an :math:`\alpha`-complex is constructed with an infinite value of :math:`\alpha`, the complex is a Delaunay complex (with special filtration values). +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 ------------------- @@ -137,19 +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). +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. +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 59 is used. +In the following example, a threshold of :math:`\alpha^2 = 32.0` is used. Example from OFF file @@ -166,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.' @@ -179,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 @@ -200,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/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/reader_utils_ref.rst b/src/python/doc/diagram_readers_ref.rst index f3ecebad..c79daf9c 100644 --- a/src/python/doc/reader_utils_ref.rst +++ b/src/python/doc/diagram_readers_ref.rst @@ -2,13 +2,9 @@ .. To get rid of WARNING: document isn't included in any toctree -============================= -Reader utils reference manual -============================= - -.. autofunction:: gudhi.read_off - -.. autofunction:: gudhi.read_lower_triangular_matrix_from_csv_file +================================ +Diagram readers reference manual +================================ .. autofunction:: gudhi.read_persistence_intervals_grouped_by_dimension 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 c36a578f..3387a64f 100644 --- a/src/python/doc/index.rst +++ b/src/python/doc/index.rst @@ -6,8 +6,8 @@ GUDHI Python modules documentation :alt: Gudhi banner :figclass: align-center -Complexes -********* +Data structures for cell complexes +********************************** Cubical complexes ================= @@ -17,18 +17,26 @@ Cubical complexes Simplicial complexes ==================== +Simplex tree +------------ + +.. include:: simplex_tree_sum.inc + +Filtrations and reconstructions +******************************* + Alpha complex -------------- +============= .. include:: alpha_complex_sum.inc Rips complex ------------- +============ .. include:: rips_complex_sum.inc Witness complex ---------------- +=============== .. include:: witness_complex_sum.inc @@ -37,16 +45,10 @@ Cover complexes .. include:: nerve_gic_complex_sum.inc -Data structures and basic operations -************************************ - -Data structures -=============== - -Simplex tree ------------- +Tangential complex +================== -.. include:: simplex_tree_sum.inc +.. include:: tangential_complex_sum.inc Topological descriptors computation *********************************** @@ -56,15 +58,6 @@ Persistence cohomology .. include:: persistent_cohomology_sum.inc -Manifold reconstruction -*********************** - -Tangential complex -================== - -.. include:: tangential_complex_sum.inc - - Topological descriptors tools ***************************** @@ -88,6 +81,11 @@ Persistence graphical tools .. include:: persistence_graphical_tools_sum.inc +Point cloud utilities +********************* + +.. include:: point_cloud_sum.inc + Bibliography ************ diff --git a/src/python/doc/installation.rst b/src/python/doc/installation.rst index 54504413..40f3f44b 100644 --- a/src/python/doc/installation.rst +++ b/src/python/doc/installation.rst @@ -83,20 +83,30 @@ Or install it definitely in your Python packages folder: .. code-block:: bash - python setup.py install --prefix /home/gudhi # Install in /home/gudhi directory + 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 ================ @@ -247,6 +257,13 @@ 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 ===== diff --git a/src/python/doc/persistence_graphical_tools_user.rst b/src/python/doc/persistence_graphical_tools_user.rst index f41a926b..80002db6 100644 --- a/src/python/doc/persistence_graphical_tools_user.rst +++ b/src/python/doc/persistence_graphical_tools_user.rst @@ -24,7 +24,7 @@ This function can display the persistence result as a barcode: 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) diff --git a/src/python/doc/point_cloud.rst b/src/python/doc/point_cloud.rst new file mode 100644 index 00000000..d668428a --- /dev/null +++ b/src/python/doc/point_cloud.rst @@ -0,0 +1,22 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + +============================ +Point cloud utilities manual +============================ + +File Readers +------------ + +.. autofunction:: gudhi.read_points_from_off_file + +.. autofunction:: gudhi.read_lower_triangular_matrix_from_csv_file + +Subsampling +----------- + +.. automodule:: gudhi.subsampling + :members: + :special-members: + :show-inheritance: diff --git a/src/python/doc/point_cloud_sum.inc b/src/python/doc/point_cloud_sum.inc new file mode 100644 index 00000000..85d52de7 --- /dev/null +++ b/src/python/doc/point_cloud_sum.inc @@ -0,0 +1,15 @@ +.. table:: + :widths: 30 50 20 + + +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | | :math:`(x_1, x_2, \ldots, x_d)` | Utilities to process point clouds: read from file, subsample, etc. | :Author: Vincent Rouvreau | + | | :math:`(y_1, y_2, \ldots, y_d)` | | | + | | | :Introduced in: GUDHI 2.0.0 | + | | | | + | | | :Copyright: MIT (`GPL v3 </licensing/>`_) | + | | Parts of this package require CGAL. | | + | | | :Requires: `Eigen <installation.html#eigen>`__ :math:`\geq` 3.1.0 and `CGAL <installation.html#cgal>`__ :math:`\geq` 4.11.0 | + | | | | + +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | * :doc:`point_cloud` | + +----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/src/python/doc/representations.rst b/src/python/doc/representations.rst index b3131a25..11dcbcf9 100644 --- a/src/python/doc/representations.rst +++ b/src/python/doc/representations.rst @@ -8,7 +8,7 @@ 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. +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. @@ -46,3 +46,27 @@ 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 index 7b167a17..700828f1 100644 --- a/src/python/doc/representations_sum.inc +++ b/src/python/doc/representations_sum.inc @@ -3,7 +3,7 @@ +------------------------------------------------------------------+----------------------------------------------------------------+-----------------------------------------------+ | .. figure:: | Vectorizations, distances and kernels that work on persistence | :Author: Mathieu Carrière | - | ../../doc/Persistence_representations/average_landscape.png | diagrams, compatible with scikit-learn. | | + | img/sklearn-tda.png | diagrams, compatible with scikit-learn. | | | | | :Introduced in: GUDHI 3.1.0 | | | | | | | | :Copyright: MIT | diff --git a/src/python/doc/rips_complex_user.rst b/src/python/doc/rips_complex_user.rst index a8659542..a27573e8 100644 --- a/src/python/doc/rips_complex_user.rst +++ b/src/python/doc/rips_complex_user.rst @@ -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()) + ' - ' + \ diff --git a/src/python/doc/wasserstein_distance_sum.inc b/src/python/doc/wasserstein_distance_sum.inc index ffd4d312..a97f428d 100644 --- a/src/python/doc/wasserstein_distance_sum.inc +++ b/src/python/doc/wasserstein_distance_sum.inc @@ -2,12 +2,12 @@ :widths: 30 50 20 +-----------------------------------------------------------------+----------------------------------------------------------------------+------------------------------------------------------------------+ - | .. figure:: | The p-Wasserstein distance measures the similarity between two | :Author: Theo Lacombe | + | .. 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 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`. | | + | 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 index a049cfb5..32999a0c 100644 --- a/src/python/doc/wasserstein_distance_user.rst +++ b/src/python/doc/wasserstein_distance_user.rst @@ -30,7 +30,7 @@ Note that persistence diagrams must be submitted as (n x 2) numpy arrays and mus 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.) + message = "Wasserstein distance value = " + '%.2f' % gudhi.wasserstein.wasserstein_distance(diag1, diag2, order=1., internal_p=2.) print(message) The output is: diff --git a/src/python/doc/witness_complex_user.rst b/src/python/doc/witness_complex_user.rst index 45ba5b3b..7087fa98 100644 --- a/src/python/doc/witness_complex_user.rst +++ b/src/python/doc/witness_complex_user.rst @@ -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) + \ |
