Merge remote-tracking branch 'origin/master' into doc

10 files changed, 29 insertions, 23 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/installation.rst b/src/python/doc/installation.rst
index 50a697c7..40f3f44b 100644
--- a/src/python/doc/installation.rst
+++ b/src/python/doc/installation.rst
@@ -257,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
index 6a74d253..d668428a 100644
--- a/src/python/doc/point_cloud.rst
+++ b/src/python/doc/point_cloud.rst
@@ -9,7 +9,7 @@ Point cloud utilities manual
 File Readers
 ------------
 
-.. 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/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) + \