Add datasets generators documentation

5 files changed, 122 insertions, 5 deletions

diff --git a/src/python/doc/datasets_generators.inc b/src/python/doc/datasets_generators.inc
new file mode 100644
index 00000000..c88115c3
--- /dev/null
+++ b/src/python/doc/datasets_generators.inc
@@ -0,0 +1,14 @@
+.. table::
+   :widths: 30 40 30
+
+   +-----------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------+
+   | | :math:`(x_1, x_2, \ldots, x_d)` | Datasets generators (points).              | :Authors: Hind Montassif                                                             |
+   |                                   |                                            |                                                                                      |
+   |                                   |                                            | :Since: GUDHI 3.5.0                                                                  |
+   |                                   |                                            |                                                                                      |
+   |                                   |                                            | :License: MIT (`LGPL v3 </licensing/>`_)                                             |
+   |                                   |                                            |                                                                                      |
+   |                                   |                                            | :Requires: `CGAL <installation.html#cgal>`_                                          |
+   +-----------------------------------+--------------------------------------------+--------------------------------------------------------------------------------------+
+   | * :doc:`datasets_generators`                                                                                                                                          |
+   +-----------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
diff --git a/src/python/doc/datasets_generators.rst b/src/python/doc/datasets_generators.rst
new file mode 100644
index 00000000..ef21c9d2
--- /dev/null
+++ b/src/python/doc/datasets_generators.rst
@@ -0,0 +1,97 @@
+
+:orphan:
+
+.. To get rid of WARNING: document isn't included in any toctree
+
+===========================
+Datasets generators manual
+===========================
+
+We provide the generation of different customizable datasets to use as inputs for Gudhi complexes and data structures.
+
+
+Points generators
+------------------
+
+Points on sphere
+^^^^^^^^^^^^^^^^
+
+The module **_points** enables the generation of random i.i.d. points uniformly on a (d-1)-sphere in :math:`R^d`.
+The user should provide the number of points to be generated on the sphere :code:`n_samples` and the ambient dimension :code:`ambient_dim`.
+The :code:`radius` of sphere is optional and is equal to **1** by default.
+Only random points generation is currently available.
+
+The generated points are given as an array of shape :math:`(n\_samples, ambient\_dim)`.
+
+Example
+"""""""
+
+.. code-block:: python
+
+   from gudhi.datasets.generators import _points
+   from gudhi import AlphaComplex
+
+   # Generate 50 points on a sphere in R^2
+   gen_points = _points.sphere(n_samples = 50, ambient_dim = 2, radius = 1, sample = "random")
+
+   # Create an alpha complex from the generated points
+   alpha_complex = AlphaComplex(points = gen_points)
+   
+.. autofunction:: gudhi.datasets.generators._points.sphere
+
+Points on torus
+^^^^^^^^^^^^^^^^
+
+You can also generate points on a torus.
+
+Two modules are available and give the same output: the first one depends on **CGAL** and the second does not and consists of full python code.
+
+On another hand, two sample types are provided : you can either generate i.i.d. points on a d-torus in :math:`R^{2d}` *randomly* or on a *grid*.
+
+First module : **_points**
+""""""""""""""""""""""""""
+
+The user should provide the number of points to be generated on the torus :code:`n_samples`, and the dimension :code:`dim` of the torus on which points would be generated in :math:`R^{2dim}`.
+The flag :code:`uniform` is optional and is set to **False** by default, meaning that the points will be generated randomly.
+In this case, the returned generated points would be an array of shape :math:`(n\_samples, 2*dim)`.
+Otherwise, if set to **True**, the points are generated as a grid and would be given as an array of shape :
+
+.. math::
+
+   ( [n\_samples^{1 \over {dim}}]^{dim}, 2*dim )
+
+Example
+"""""""
+.. code-block:: python
+
+   from gudhi.datasets.generators import _points
+
+   # Generate 50 points randomly on a torus in R^6
+   gen_points = _points.torus(n_samples = 50, dim = 3)
+   
+   # Generate 27 points on a torus as a grid in R^6
+   gen_points = _points.torus(n_samples = 50, dim = 3, uniform = True)
+
+.. autofunction:: gudhi.datasets.generators._points.torus
+
+Second module : **points**
+""""""""""""""""""""""""""
+
+The user should provide the number of points to be generated on the torus :code:`n_samples` and the dimension :code:`dim` of the torus on which points would be generated in :math:`R^{2dim}`.
+The :code:`sample` argument is optional and is set to **'random'** by default.
+The other allowed value of sample type is **'grid'** and is equivalent to :code:`uniform = True` in the first module.
+
+Example
+"""""""
+.. code-block:: python
+
+   from gudhi.datasets.generators import points
+
+   # Generate 50 points randomly on a torus in R^6
+   gen_points = points.torus(n_samples = 50, dim = 3)
+   
+   # Generate 27 points on a torus as a grid in R^6
+   gen_points = points.torus(n_samples = 50, dim = 3, sample = 'grid')
+
+
+.. autofunction:: gudhi.datasets.generators.points.torus
diff --git a/src/python/doc/examples.rst b/src/python/doc/examples.rst
index 76e5d4c7..1442f185 100644
--- a/src/python/doc/examples.rst
+++ b/src/python/doc/examples.rst
@@ -8,6 +8,7 @@ Examples
 .. only:: builder_html
 
     * :download:`alpha_complex_diagram_persistence_from_off_file_example.py <../example/alpha_complex_diagram_persistence_from_off_file_example.py>`
+    * :download:`alpha_complex_from_generated_points_on_sphere_example.py <../example/alpha_complex_from_generated_points_on_sphere_example.py>`
     * :download:`alpha_complex_from_points_example.py <../example/alpha_complex_from_points_example.py>`
     * :download:`alpha_rips_persistence_bottleneck_distance.py <../example/alpha_rips_persistence_bottleneck_distance.py>`
     * :download:`bottleneck_basic_example.py <../example/bottleneck_basic_example.py>`
diff --git a/src/python/doc/index.rst b/src/python/doc/index.rst
index 040e57a4..2d7921ae 100644
--- a/src/python/doc/index.rst
+++ b/src/python/doc/index.rst
@@ -91,3 +91,8 @@ Clustering
 **********
 
 .. include:: clustering.inc
+
+Datasets generators
+*******************
+
+.. include:: datasets_generators.inc
diff --git a/src/python/gudhi/datasets/generators/points.py b/src/python/gudhi/datasets/generators/points.py
index a8f5ad54..3870dea6 100644
--- a/src/python/gudhi/datasets/generators/points.py
+++ b/src/python/gudhi/datasets/generators/points.py
@@ -32,17 +32,17 @@ def _generate_grid_points_on_torus(n_samples, dim):
     return array_points
 
 def torus(n_samples, dim, sample='random'):
-    ''' 
+    """ 
     Generate points on a dim-torus in R^2dim either randomly or on a grid
     
     :param n_samples: The number of points to be generated.
     :param dim: The dimension of the torus on which points would be generated in R^2*dim.
     :param sample: The sample type of the generated points. Can be 'random' or 'grid'.
     :returns: numpy array containing the generated points on a torus.
-              The shape of returned numpy array is :
-                if sample is 'random' : (n_samples, 2*dim)
-                if sample is 'grid' : ((int(n_samples**(1./dim)))**dim, 2*dim)
-    '''
+        The shape of returned numpy array is :
+        if sample is 'random' : (n_samples, 2*dim).
+        if sample is 'grid' : ([n_samples**(1./dim)]**dim, 2*dim).
+    """
     if sample == 'random':
         # Generate points randomly
         print("Sample is random")