Finish the documentation and examples

git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/branches/python_nerve_gic_vincent@3299 636b058d-ea47-450e-bf9e-a15bfbe3eedb

Former-commit-id: d60f4db274962c1c6aaef3c4ab6787bda8c0640f

8 files changed, 369 insertions, 3 deletions

diff --git a/src/Nerve_GIC/example/CoordGIC.cpp b/src/Nerve_GIC/example/CoordGIC.cpp
index c92cf235..8479c369 100644
--- a/src/Nerve_GIC/example/CoordGIC.cpp
+++ b/src/Nerve_GIC/example/CoordGIC.cpp
@@ -76,10 +76,10 @@ int main(int argc, char **argv) {
     // --------------------------------------------
 
     if (verb) {
-      std::cout << "Functional GIC is of dimension " << stree.dimension() << " - " << stree.num_simplices()
+      std::cout << "Coordinate GIC is of dimension " << stree.dimension() << " - " << stree.num_simplices()
                 << " simplices - " << stree.num_vertices() << " vertices." << std::endl;
 
-      std::cout << "Iterator on functional GIC simplices" << std::endl;
+      std::cout << "Iterator on coordinate GIC simplices" << std::endl;
       for (auto f_simplex : stree.filtration_simplex_range()) {
         for (auto vertex : stree.simplex_vertex_range(f_simplex)) {
           std::cout << vertex << " ";
diff --git a/src/cython/cython/nerve_gic.pyx b/src/cython/cython/nerve_gic.pyx
index 32c3cd26..51c7cff4 100644
--- a/src/cython/cython/nerve_gic.pyx
+++ b/src/cython/cython/nerve_gic.pyx
@@ -268,7 +268,7 @@ cdef class CoverComplex:
         """
         self.thisptr.set_function_from_range(function)
 
-    def set_gain(self, g):
+    def set_gain(self, g = 0.3):
         """Sets a gain from a value stored in memory.
 
         :param g: Gain (default value is 0.3).
diff --git a/src/cython/doc/examples.rst b/src/cython/doc/examples.rst
index 1e596e18..58b25793 100644
--- a/src/cython/doc/examples.rst
+++ b/src/cython/doc/examples.rst
@@ -19,3 +19,7 @@ Examples
     * :download:`rips_complex_diagram_persistence_from_distance_matrix_file_example.py <../example/rips_complex_diagram_persistence_from_distance_matrix_file_example.py>`
     * :download:`rips_persistence_diagram.py <../example/rips_persistence_diagram.py>`
     * :download:`random_cubical_complex_persistence_example.py <../example/random_cubical_complex_persistence_example.py>`
+    * :download:`coordinate_graph_induced_complex.py <../example/coordinate_graph_induced_complex.py>`
+    * :download:`functional_graph_induced_complex.py <../example/functional_graph_induced_complex.py>`
+    * :download:`voronoi_graph_induced_complex.py <../example/voronoi_graph_induced_complex.py>`
+    * :download:`nerve_of_a_covering.py <../example/nerve_of_a_covering.py>`
diff --git a/src/cython/doc/nerve_gic_complex_user.rst b/src/cython/doc/nerve_gic_complex_user.rst
index 7edf0578..b2669303 100644
--- a/src/cython/doc/nerve_gic_complex_user.rst
+++ b/src/cython/doc/nerve_gic_complex_user.rst
@@ -220,3 +220,93 @@ one can obtain the following visualization:
     :alt: Visualization with Geomview
 
     Visualization with Geomview
+
+Functional GIC
+^^^^^^^^^^^^^^
+
+If one restricts to the cliques in G whose nodes all belong to preimages of
+consecutive intervals (assuming the cover of the height function is minimal,
+i.e. no more than two intervals can intersect at a time), the GIC is of
+dimension one, i.e. a graph.
+We call this graph the functional GIC. See :cite:`Carriere16` for more details.
+
+Example
+^^^^^^^
+
+Functional GIC comes with automatic selection of the Rips threshold,
+the resolution and the gain of the function cover. See :cite:`Carriere17c` for
+more details. In this example, we compute the functional GIC of a Klein bottle
+embedded in R^5, where the graph G comes from a Rips complex with automatic
+threshold, and the cover C comes from the preimages of intervals covering the
+first coordinate, with automatic resolution and gain. Note that automatic
+threshold, resolution and gain can be computed as well for the Nerve.
+
+.. testcode::
+
+    import gudhi
+    nerve_complex = gudhi.CoverComplex()
+
+    if (nerve_complex.read_point_cloud(gudhi.__root_source_dir__ + \
+    '/data/points/KleinBottle5D.off')):
+        nerve_complex.set_type('GIC')
+        nerve_complex.set_color_from_coordinate(0)
+        nerve_complex.set_function_from_coordinate(0)
+        nerve_complex.set_graph_from_automatic_rips()
+        nerve_complex.set_automatic_resolution()
+        nerve_complex.set_gain()
+        nerve_complex.set_cover_from_function()
+        nerve_complex.find_simplices()
+        nerve_complex.plot_dot()
+
+the program outputs SC.dot. Using e.g.
+
+.. code-block:: none
+
+    neato ../../data/points/KleinBottle5D.off_sc.dot -Tpdf -o ../../data/points/KleinBottle5D.off_sc.pdf
+
+one can obtain the following visualization:
+
+.. figure::
+    ../../doc/Nerve_GIC/coordGICvisu2.jpg
+    :figclass: align-center
+    :alt: Visualization with neato
+
+    Visualization with neato
+
+where nodes are colored by the filter function values and, for each node, the
+first number is its ID and the second is the number of data points that its
+contain.
+
+We also provide an example on a set of 72 pictures taken around the same object
+(lucky_cat.off).
+The function is now the first eigenfunction given by PCA, whose values are
+written in a file (lucky_cat_PCA1). Threshold, resolution and gain are
+automatically selected as before.
+
+.. testcode::
+
+    import gudhi
+    nerve_complex = gudhi.CoverComplex()
+
+    if (nerve_complex.read_point_cloud(gudhi.__root_source_dir__ + \
+    '/data/points/COIL_database/lucky_cat.off')):
+        nerve_complex.set_type('GIC')
+        pca_file = gudhi.__root_source_dir__ + \
+        '/data/points/COIL_database/lucky_cat_PCA1'
+        nerve_complex.set_color_from_file(pca_file)
+        nerve_complex.set_function_from_file(pca_file)
+        nerve_complex.set_graph_from_automatic_rips()
+        nerve_complex.set_automatic_resolution()
+        nerve_complex.set_gain()
+        nerve_complex.set_cover_from_function()
+        nerve_complex.find_simplices()
+        nerve_complex.plot_dot()
+
+the program outputs again SC.dot which gives the following visualization after using neato:
+
+.. figure::
+    ../../doc/Nerve_GIC/funcGICvisu.jpg
+    :figclass: align-center
+    :alt: Visualization with neato
+
+    Visualization with neato
diff --git a/src/cython/example/coordinate_graph_induced_complex.py b/src/cython/example/coordinate_graph_induced_complex.py
new file mode 100755
index 00000000..71b87f7a
--- /dev/null
+++ b/src/cython/example/coordinate_graph_induced_complex.py
@@ -0,0 +1,68 @@
+#!/usr/bin/env python
+
+import gudhi
+import argparse
+
+"""This file is part of the Gudhi Library. The Gudhi library
+   (Geometric Understanding in Higher Dimensions) is a generic C++
+   library for computational topology.
+
+   Author(s):       Vincent Rouvreau
+
+   Copyright (C) 2018 Inria
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+
+__author__ = "Vincent Rouvreau"
+__copyright__ = "Copyright (C) 2018 Inria"
+__license__ = "GPL v3"
+
+parser = argparse.ArgumentParser(description='Coordinate GIC '
+                                 'from points read in a OFF file.',
+                                 epilog='Example: '
+                                 'example/coordinate_graph_induced_complex.py '
+                                 '-f ../data/points/KleinBottle5D.off 0 -v'
+                                 '- Constructs the coordinate GIC with the '
+                                 'points from the given OFF file.')
+parser.add_argument("-f", "--file", type=str, required=True)
+parser.add_argument("-c", "--coordinate", type=int, default=0)
+parser.add_argument("-v", "--verbose", default=False, action='store_true' , help='Flag for program verbosity')
+
+args = parser.parse_args()
+
+nerve_complex = gudhi.CoverComplex()
+nerve_complex.set_verbose(args.verbose)
+
+if (nerve_complex.read_point_cloud(args.file)):
+    nerve_complex.set_type('GIC')
+    nerve_complex.set_color_from_coordinate(args.coordinate)
+    nerve_complex.set_function_from_coordinate(args.coordinate)
+    nerve_complex.set_graph_from_automatic_rips()
+    nerve_complex.set_automatic_resolution()
+    nerve_complex.set_gain()
+    nerve_complex.set_cover_from_function()
+    nerve_complex.find_simplices()
+    nerve_complex.plot_dot()
+    simplex_tree = nerve_complex.create_simplex_tree()
+    nerve_complex.compute_PD()
+    if (args.verbose):
+        print('Iterator on coordinate GIC simplices')
+        result_str = 'Coordinate GIC is of dimension ' + \
+            repr(simplex_tree.dimension()) + ' - ' + \
+            repr(simplex_tree.num_simplices()) + ' simplices - ' + \
+            repr(simplex_tree.num_vertices()) + ' vertices.'
+        print(result_str)
+        for filtered_value in simplex_tree.get_filtration():
+            print(filtered_value[0])
diff --git a/src/cython/example/functional_graph_induced_complex.py b/src/cython/example/functional_graph_induced_complex.py
new file mode 100755
index 00000000..6ad7c2ec
--- /dev/null
+++ b/src/cython/example/functional_graph_induced_complex.py
@@ -0,0 +1,69 @@
+#!/usr/bin/env python
+
+import gudhi
+import argparse
+
+"""This file is part of the Gudhi Library. The Gudhi library
+   (Geometric Understanding in Higher Dimensions) is a generic C++
+   library for computational topology.
+
+   Author(s):       Vincent Rouvreau
+
+   Copyright (C) 2018 Inria
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+
+__author__ = "Vincent Rouvreau"
+__copyright__ = "Copyright (C) 2018 Inria"
+__license__ = "GPL v3"
+
+parser = argparse.ArgumentParser(description='Functional GIC '
+                                 'from points read in a OFF file.',
+                                 epilog='Example: '
+                                 'example/functional_graph_induced_complex.py '
+                                 '-o ../data/points/COIL_database/lucky_cat.off '
+                                 '-f ../data/points/COIL_database/lucky_cat_PCA1'
+                                 '- Constructs the functional GIC with the '
+                                 'points from the given OFF and function files.')
+parser.add_argument("-o", "--off-file", type=str, required=True)
+parser.add_argument("-f", "--function-file", type=str, required=True)
+parser.add_argument("-v", "--verbose", default=False, action='store_true' , help='Flag for program verbosity')
+
+args = parser.parse_args()
+
+nerve_complex = gudhi.CoverComplex()
+nerve_complex.set_verbose(args.verbose)
+
+if (nerve_complex.read_point_cloud(args.off_file)):
+    nerve_complex.set_type('GIC')
+    nerve_complex.set_color_from_file(args.function_file)
+    nerve_complex.set_function_from_file(args.function_file)
+    nerve_complex.set_graph_from_automatic_rips()
+    nerve_complex.set_automatic_resolution()
+    nerve_complex.set_gain()
+    nerve_complex.set_cover_from_function()
+    nerve_complex.find_simplices()
+    nerve_complex.plot_dot()
+    simplex_tree = nerve_complex.create_simplex_tree()
+    nerve_complex.compute_PD()
+    if (args.verbose):
+        print('Iterator on functional GIC simplices')
+        result_str = 'Functional GIC is of dimension ' + \
+            repr(simplex_tree.dimension()) + ' - ' + \
+            repr(simplex_tree.num_simplices()) + ' simplices - ' + \
+            repr(simplex_tree.num_vertices()) + ' vertices.'
+        print(result_str)
+        for filtered_value in simplex_tree.get_filtration():
+            print(filtered_value[0])
diff --git a/src/cython/example/nerve_of_a_covering.py b/src/cython/example/nerve_of_a_covering.py
new file mode 100755
index 00000000..c5577cb1
--- /dev/null
+++ b/src/cython/example/nerve_of_a_covering.py
@@ -0,0 +1,70 @@
+#!/usr/bin/env python
+
+import gudhi
+import argparse
+
+"""This file is part of the Gudhi Library. The Gudhi library
+   (Geometric Understanding in Higher Dimensions) is a generic C++
+   library for computational topology.
+
+   Author(s):       Vincent Rouvreau
+
+   Copyright (C) 2018 Inria
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+
+__author__ = "Vincent Rouvreau"
+__copyright__ = "Copyright (C) 2018 Inria"
+__license__ = "GPL v3"
+
+parser = argparse.ArgumentParser(description='Nerve of a covering creation '
+                                 'from points read in a OFF file.',
+                                 epilog='Example: '
+                                 'example/nerve_of_a_covering.py '
+                                 '-f ../data/points/human.off -c 2 -r 10 -g 0.3'
+                                 '- Constructs Nerve of a covering with the '
+                                 'points from the given OFF file.')
+parser.add_argument("-f", "--file", type=str, required=True)
+parser.add_argument("-c", "--coordinate", type=int, default=0)
+parser.add_argument("-r", "--resolution", type=int, default=10)
+parser.add_argument("-g", "--gain", type=float, default=0.3)
+parser.add_argument("-v", "--verbose", default=False, action='store_true' , help='Flag for program verbosity')
+
+args = parser.parse_args()
+
+nerve_complex = gudhi.CoverComplex()
+nerve_complex.set_verbose(args.verbose)
+
+if (nerve_complex.read_point_cloud(args.file)):
+    nerve_complex.set_type('Nerve')
+    nerve_complex.set_color_from_coordinate(args.coordinate)
+    nerve_complex.set_function_from_coordinate(args.coordinate)
+    nerve_complex.set_graph_from_OFF()
+    nerve_complex.set_resolution_with_interval_number(args.resolution)
+    nerve_complex.set_gain(args.gain)
+    nerve_complex.set_cover_from_function()
+    nerve_complex.find_simplices()
+    nerve_complex.write_info()
+    simplex_tree = nerve_complex.create_simplex_tree()
+    nerve_complex.compute_PD()
+    if (args.verbose):
+        print('Iterator on graph induced complex simplices')
+        result_str = 'Nerve is of dimension ' + \
+            repr(simplex_tree.dimension()) + ' - ' + \
+            repr(simplex_tree.num_simplices()) + ' simplices - ' + \
+            repr(simplex_tree.num_vertices()) + ' vertices.'
+        print(result_str)
+        for filtered_value in simplex_tree.get_filtration():
+            print(filtered_value[0])
diff --git a/src/cython/example/voronoi_graph_induced_complex.py b/src/cython/example/voronoi_graph_induced_complex.py
new file mode 100755
index 00000000..8266a0e4
--- /dev/null
+++ b/src/cython/example/voronoi_graph_induced_complex.py
@@ -0,0 +1,65 @@
+#!/usr/bin/env python
+
+import gudhi
+import argparse
+
+"""This file is part of the Gudhi Library. The Gudhi library
+   (Geometric Understanding in Higher Dimensions) is a generic C++
+   library for computational topology.
+
+   Author(s):       Vincent Rouvreau
+
+   Copyright (C) 2018 Inria
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.
+"""
+
+__author__ = "Vincent Rouvreau"
+__copyright__ = "Copyright (C) 2018 Inria"
+__license__ = "GPL v3"
+
+parser = argparse.ArgumentParser(description='Voronoi GIC '
+                                 'from points read in a OFF file.',
+                                 epilog='Example: '
+                                 'example/voronoi_graph_induced_complex.py '
+                                 '-f ../data/points/human.off -n 700 -v'
+                                 '- Constructs the Voronoi GIC with the '
+                                 'points from the given OFF file.')
+parser.add_argument("-f", "--file", type=str, required=True)
+parser.add_argument("-n", "--subsample-nb-points", type=int, default=100)
+parser.add_argument("-v", "--verbose", default=False, action='store_true' , help='Flag for program verbosity')
+
+args = parser.parse_args()
+
+nerve_complex = gudhi.CoverComplex()
+nerve_complex.set_verbose(args.verbose)
+
+if (nerve_complex.read_point_cloud(args.file)):
+    nerve_complex.set_type('GIC')
+    nerve_complex.set_color_from_coordinate()
+    nerve_complex.set_graph_from_OFF()
+    nerve_complex.set_cover_from_Voronoi(args.subsample_nb_points)
+    nerve_complex.find_simplices()
+    nerve_complex.plot_off()
+    simplex_tree = nerve_complex.create_simplex_tree()
+    nerve_complex.compute_PD()
+    if (args.verbose):
+        print('Iterator on graph induced complex simplices')
+        result_str = 'Graph induced complex is of dimension ' + \
+            repr(simplex_tree.dimension()) + ' - ' + \
+            repr(simplex_tree.num_simplices()) + ' simplices - ' + \
+            repr(simplex_tree.num_vertices()) + ' vertices.'
+        print(result_str)
+        for filtered_value in simplex_tree.get_filtration():
+            print(filtered_value[0])