Automatic examples documentation page generation

alpha_rips_persistence_bottleneck_distance example for python
Add intervals_in_dim function for simplex tree


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

Former-commit-id: 460fbe5db9f0c08776952106e729a21460bec36f

11 files changed, 219 insertions, 31 deletions

diff --git a/src/cython/CMakeLists.txt b/src/cython/CMakeLists.txt
index 72be7b30..8723d731 100644
--- a/src/cython/CMakeLists.txt
+++ b/src/cython/CMakeLists.txt
@@ -42,10 +42,11 @@ if(PYTHON_PATH AND CYTHON_PATH)
       set(GUDHI_CYTHON_INCLUDE_DIRS "${GUDHI_CYTHON_INCLUDE_DIRS}'${EIGEN3_INCLUDE_DIR}', ")
     endif (EIGEN3_FOUND)
     
-    # Copy recursively include, cython and test repositories before packages finding
+    # Copy recursively include, cython, example and test repositories before packages finding
     # Some tests files are removed in case some packages are not found
     file(COPY include DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
     file(COPY cython DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
+    file(COPY example DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
     file(COPY test DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
 
     if (CGAL_FOUND)
diff --git a/src/cython/cython/simplex_tree.pyx b/src/cython/cython/simplex_tree.pyx
index 8f909398..070c98ab 100644
--- a/src/cython/cython/simplex_tree.pyx
+++ b/src/cython/cython/simplex_tree.pyx
@@ -59,6 +59,7 @@ cdef extern from "Persistent_cohomology_interface.h" namespace "Gudhi":
         vector[pair[int, pair[double, double]]] get_persistence(int homology_coeff_field, double min_persistence)
         vector[int] betti_numbers()
         vector[int] persistent_betti_numbers(double from_value, double to_value)
+        vector[pair[double,double]] intervals_in_dimension(int dimension)
 
 # SimplexTree python interface
 cdef class SimplexTree:
@@ -359,3 +360,23 @@ cdef class SimplexTree:
             print("persistent_betti_numbers function requires persistence function"
                   " to be launched first.")
         return pbn_result
+
+    def intervals_in_dim(self, dimension):
+        """This function returns the persistence intervals of the simplicial
+        complex in a specific dimension.
+
+        :param dimension: The specific dimension.
+        :type from_value: int.
+        :returns: The persistence intervals.
+        :rtype:  list of pair of float
+
+        :note: betti_numbers function requires persistence function to be
+            launched first.
+        """
+        cdef vector[pair[double,double]] intervals_result
+        if self.pcohptr != NULL:
+            intervals_result = self.pcohptr.intervals_in_dimension(dimension)
+        else:
+            print("intervals_in_dim function requires persistence function"
+                  " to be launched first.")
+        return intervals_result
diff --git a/src/cython/doc/Makefile b/src/cython/doc/Makefile
index fc353a37..be3ff7c4 100644
--- a/src/cython/doc/Makefile
+++ b/src/cython/doc/Makefile
@@ -47,9 +47,13 @@ help:
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
+	rm -f examples.inc
 	rm -rf $(BUILDDIR)/*
 
+# GUDHI specific : Examples.inc is generated with generate_examples.py (and deleted on clean)
+
 html:
+	./generate_examples.py
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
diff --git a/src/cython/doc/bottleneck_distance_ref.rst b/src/cython/doc/bottleneck_distance_ref.rst
deleted file mode 100644
index 91a2ab05..00000000
--- a/src/cython/doc/bottleneck_distance_ref.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-===========================
-Bottleneck reference manual
-===========================
-
-.. autofunction:: gudhi.bottleneck_distance
diff --git a/src/cython/doc/bottleneck_distance_sum.rst b/src/cython/doc/bottleneck_distance_sum.rst
index 6fec9b7e..5c475d0d 100644
--- a/src/cython/doc/bottleneck_distance_sum.rst
+++ b/src/cython/doc/bottleneck_distance_sum.rst
@@ -11,5 +11,5 @@
 |      Bottleneck distance is the length of                       | distance at most b.                                                  |
 |      the longest edge                                           |                                                                      |
 +-----------------------------------------------------------------+----------------------------------------------------------------------+
-| :doc:`bottleneck_distance_user`                                 | :doc:`bottleneck_distance_ref`                                       |
+| :doc:`bottleneck_distance_user`                                 |                                                                      |
 +-----------------------------------------------------------------+----------------------------------------------------------------------+
diff --git a/src/cython/doc/examples.rst b/src/cython/doc/examples.rst
index 32b173c3..a89e0596 100644
--- a/src/cython/doc/examples.rst
+++ b/src/cython/doc/examples.rst
@@ -1,4 +1,4 @@
 Examples
 ########
 
-
+.. include:: examples.inc
diff --git a/src/cython/doc/generate_examples.py b/src/cython/doc/generate_examples.py
new file mode 100755
index 00000000..d64d506c
--- /dev/null
+++ b/src/cython/doc/generate_examples.py
@@ -0,0 +1,43 @@
+#!/usr/bin/env python
+
+from os import listdir
+
+"""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) 2017 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) 2017 INRIA"
+__license__ = "GPL v3"
+
+"""
+generate_examples.py generates examples.inc to be included in examples.rst.
+Refer to Makefile and make.bat to see if it is correctly launched.
+"""
+
+output_file = open('examples.inc','w')
+
+output_file.write('.. only:: builder_html\n\n')
+
+for file in listdir('../example/'):
+    output_file.write("    * :download:`" + file + " <../example/" + file + ">`\n")
+
+output_file.close()
diff --git a/src/cython/doc/installation.rst b/src/cython/doc/installation.rst
index 4359c744..12d35821 100644
--- a/src/cython/doc/installation.rst
+++ b/src/cython/doc/installation.rst
@@ -42,7 +42,9 @@ Documentation
 =============
 
 To build the documentation, `sphinx-doc <http://http://www.sphinx-doc.org>`_ is
-required. Run the following commands in a terminal:
+required. Please refer to *conf.py* file to see which
+`sphinx-doc <http://http://www.sphinx-doc.org>`_ modules are required to
+generate the documentation. Run the following commands in a terminal:
 
 .. code-block:: bash
 
@@ -56,7 +58,7 @@ CGAL
 
 The :doc:`Alpha complex </alpha_complex_user>` data structure and
 :doc:`Tangential complex </tangential_complex_user>` data structures,
-:doc:`Bottleneck distance </bottleneck_distance_user>`requires CGAL, which is a
+:doc:`Bottleneck distance </bottleneck_distance_user>` requires CGAL, which is a
 C++ library which provides easy access to efficient and reliable geometric
 algorithms.
 
@@ -66,13 +68,17 @@ install this library according to your operating system is detailed
 
 The following examples require the Computational Geometry Algorithms Library:
 
-* alpha_complex_diagram_persistence_from_off_file_example.py
-* alpha_complex_from_points_example.py
+.. 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_points_example.py <../example/alpha_complex_from_points_example.py>`
 
 The following example requires CGAL version ≥ 4.8.0:
 
-* bottleneck_basic_example.py
-* tangential_complex_plain_homology_from_off_file_example.py
+.. only:: builder_html
+
+    * :download:`bottleneck_basic_example.py <../example/bottleneck_basic_example.py>`
+    * :download:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>`
 
 Eigen3
 ======
@@ -85,9 +91,11 @@ algorithms.
 
 The following examples require the `Eigen3 <http://eigen.tuxfamily.org/>`_:
 
-* alpha_complex_diagram_persistence_from_off_file_example.py
-* alpha_complex_from_points_example.py
-* tangential_complex_plain_homology_from_off_file_example.py
+.. 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_points_example.py <../example/alpha_complex_from_points_example.py>`
+    * :download:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>`
 
 Matplotlib
 ==========
@@ -99,12 +107,14 @@ formats and interactive environments across platforms.
 
 The following examples require the `Matplotlib <http://matplotlib.org>`_:
 
-* alpha_complex_diagram_persistence_from_off_file_example.py
-* gudhi_graphical_tools_example.py
-* periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py
-* rips_complex_diagram_persistence_with_pandas_interface_example.py
-* rips_persistence_diagram.py
-* tangential_complex_plain_homology_from_off_file_example.py
+.. only:: builder_html
+
+    * :download:`alpha_complex_diagram_persistence_from_off_file_example.py <../example/alpha_complex_diagram_persistence_from_off_file_example.py>`
+    * :download:`gudhi_graphical_tools_example.py <../example/gudhi_graphical_tools_example.py>`
+    * :download:`periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py <../example/periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py>`
+    * :download:`rips_complex_diagram_persistence_with_pandas_interface_example.py <../example/rips_complex_diagram_persistence_with_pandas_interface_example.py>`
+    * :download:`rips_persistence_diagram.py <../example/rips_persistence_diagram.py>`
+    * :download:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>`
 
 Numpy
 =====
@@ -115,9 +125,11 @@ scientific computing with Python.
 
 The following examples require the `NumPy <http://numpy.org>`_:
 
-* alpha_complex_diagram_persistence_from_off_file_example.py
-* gudhi_graphical_tools_example.py
-* periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py
-* rips_complex_diagram_persistence_with_pandas_interface_example.py
-* rips_persistence_diagram.py
-* tangential_complex_plain_homology_from_off_file_example.py
+.. only:: builder_html
+
+    * :download:`alpha_complex_diagram_persistence_from_off_file_example.py <../example/alpha_complex_diagram_persistence_from_off_file_example.py>`
+    * :download:`gudhi_graphical_tools_example.py <../example/gudhi_graphical_tools_example.py>`
+    * :download:`periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py <../example/periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py>`
+    * :download:`rips_complex_diagram_persistence_with_pandas_interface_example.py <../example/rips_complex_diagram_persistence_with_pandas_interface_example.py>`
+    * :download:`rips_persistence_diagram.py <../example/rips_persistence_diagram.py>`
+    * :download:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>`
diff --git a/src/cython/doc/make.bat b/src/cython/doc/make.bat
index 656c0105..ba009a90 100644
--- a/src/cython/doc/make.bat
+++ b/src/cython/doc/make.bat
@@ -41,6 +41,7 @@ if "%1" == "help" (
 )

 

 if "%1" == "clean" (

+	del examples.inc

 	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i

 	del /q /s %BUILDDIR%\*

 	goto end

@@ -60,7 +61,10 @@ if errorlevel 9009 (
 	exit /b 1

 )

 

+:: GUDHI specific : Examples.inc is generated with generate_examples.py (and deleted on clean)

+

 if "%1" == "html" (

+	generate_examples.py

 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html

 	if errorlevel 1 exit /b 1

 	echo.

diff --git a/src/cython/doc/persistent_cohomology_user.rst b/src/cython/doc/persistent_cohomology_user.rst
index 1479fb1e..4ca4805d 100644
--- a/src/cython/doc/persistent_cohomology_user.rst
+++ b/src/cython/doc/persistent_cohomology_user.rst
@@ -97,7 +97,13 @@ Examples
 
 We provide several example files: run these examples with -h for details on their use.
 
-.. todo::
-    examples for persistence
+.. only:: builder_html
+
+    * :download:`alpha_complex_from_points_example.py <../example/alpha_complex_from_points_example.py>`
+    * :download:`periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py <../example/periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py>`
+    * :download:`rips_complex_diagram_persistence_with_pandas_interface_example.py <../example/rips_complex_diagram_persistence_with_pandas_interface_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:`tangential_complex_plain_homology_from_off_file_example.py <../example/tangential_complex_plain_homology_from_off_file_example.py>`
 
 .. include:: biblio.rst
diff --git a/src/cython/example/alpha_rips_persistence_bottleneck_distance.py b/src/cython/example/alpha_rips_persistence_bottleneck_distance.py
new file mode 100755
index 00000000..04a59b44
--- /dev/null
+++ b/src/cython/example/alpha_rips_persistence_bottleneck_distance.py
@@ -0,0 +1,102 @@
+#!/usr/bin/env python
+
+import gudhi
+import argparse
+import math
+
+"""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) 2016 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) 2016 INRIA"
+__license__ = "GPL v3"
+
+parser = argparse.ArgumentParser(description='AlphaComplex and RipsComplex '
+                                 'persistence creation from points read in '
+                                 'a OFF file. Bottleneck distance computation'
+                                 ' on each dimension',
+                                 epilog='Example: '
+                                 'example/alpha_rips_persistence_bottleneck_distance.py '
+                                 '-f ../data/points/tore3D_1307.off -t 0.15 -d 3')
+parser.add_argument("-f", "--file", type=str, required=True)
+parser.add_argument("-t", "--threshold", type=float, default=0.5)
+parser.add_argument("-d", "--max_dimension", type=int, default=1)
+
+args = parser.parse_args()
+print(repr(float('inf')))
+print(repr(math.sqrt(float('inf'))))
+with open(args.file, 'r') as f:
+    first_line = f.readline()
+    if (first_line == 'OFF\n') or (first_line == 'nOFF\n'):
+        print("#####################################################################")
+        print("RipsComplex creation from points read in a OFF file")
+
+        message = "RipsComplex with max_edge_length=" + repr(args.threshold)
+        print(message)
+
+        rips_complex = gudhi.RipsComplex(off_file=args.file,
+                                         max_edge_length=args.threshold)
+
+        rips_stree = rips_complex.create_simplex_tree(max_dimension=args.max_dimension)
+
+        message = "Number of simplices=" + repr(rips_stree.num_simplices())
+        print(message)
+
+        rips_diag = rips_stree.persistence()
+
+        print("#####################################################################")
+        print("AlphaComplex creation from points read in a OFF file")
+
+        message = "AlphaComplex with max_edge_length=" + repr(args.threshold)
+        print(message)
+
+        alpha_complex = gudhi.AlphaComplex(off_file=args.file)
+        alpha_stree = alpha_complex.create_simplex_tree(max_alpha_square=(args.threshold * args.threshold))
+
+        message = "Number of simplices=" + repr(alpha_stree.num_simplices())
+        print(message)
+
+        alpha_diag = alpha_stree.persistence()
+
+        max_b_distance = 0.0
+        for dim in range(args.max_dimension):
+            # Alpha persistence values needs to be transform because filtration
+            # values are alpha square values
+            funcs = [math.sqrt, math.sqrt]
+            alpha_intervals = []
+            for interval in alpha_stree.intervals_in_dim(dim):
+                alpha_intervals.append(map(lambda func,value: func(value), funcs, interval))
+
+            rips_intervals = rips_stree.intervals_in_dim(dim)
+            bottleneck_distance = gudhi.bottleneck_distance(rips_intervals, alpha_intervals)
+            message = "In dimension " + repr(dim) + ", bottleneck distance = " + repr(bottleneck_distance)
+            print(message)
+            max_b_distance = max(bottleneck_distance, max_b_distance)
+
+        print("================================================================================")
+        message = "Bottleneck distance is " + repr(max_b_distance)
+        print(message)
+
+    else:
+        print(args.file, "is not a valid OFF file")
+
+    f.close()