Merge persistence diagram improvement branch

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

Former-commit-id: eaccfe6c60c4a05bbec173a1042db7ad490a9f37

8 files changed, 70 insertions, 15 deletions

diff --git a/src/cython/doc/_templates/layout.html b/src/cython/doc/_templates/layout.html
index b11c1236..243f33c6 100644
--- a/src/cython/doc/_templates/layout.html
+++ b/src/cython/doc/_templates/layout.html
@@ -65,6 +65,7 @@
             {#- old style sidebars: using blocks -- should be deprecated #}
             {%- block sidebartoc %}
 <h2><a href="index.html">GUDHI</a></h2>
+<h2><a href="fileformats.html">File formats</a></h2>
 <h2><a href="installation.html">GUDHI installation</a></h2>
 <h2><a href="citation.html">Acknowledging the GUDHI library</a></h2>
 <h2><a href="genindex.html">Index</a></h2>
diff --git a/src/cython/doc/fileformats.rst b/src/cython/doc/fileformats.rst
new file mode 100644
index 00000000..156ef4e4
--- /dev/null
+++ b/src/cython/doc/fileformats.rst
@@ -0,0 +1,33 @@
+File formats
+############
+
+Persistence Diagram
+*******************
+
+Such a file, whose extension is usually ``.pers``, contains a list of
+persistence intervals.
+
+Lines starting with ``#`` are ignored (comments).
+
+Other lines might contain 2, 3 or 4 values (the number of values on each line
+must be the same for all lines)::
+
+    [[field] dimension] birth death
+
+Here is a simple sample file::
+
+    # Persistence diagram example
+    2 2.7 3.7
+    2 9.6 14.
+    # Some comments
+    3 34.2 34.974
+    4 3. inf
+
+Other sample files can be found in the data/persistence_diagram folder.
+
+Such files can be generated with
+:meth:`gudhi.SimplexTree.write_persistence_diagram`, read with
+:meth:`gudhi.read_persistence_intervals_grouped_by_dimension`, or
+:meth:`gudhi.read_persistence_intervals_in_dimension` and displayed with
+:meth:`gudhi.plot_persistence_barcode` or
+:meth:`gudhi.plot_persistence_diagram`.
diff --git a/src/cython/doc/persistence_graphical_tools_user.rst b/src/cython/doc/persistence_graphical_tools_user.rst
index cae18323..13198162 100644
--- a/src/cython/doc/persistence_graphical_tools_user.rst
+++ b/src/cython/doc/persistence_graphical_tools_user.rst
@@ -14,12 +14,14 @@ This function is useful to show the color palette values of dimension:
 .. testcode::
 
     import gudhi
-    gudhi.show_palette_values(alpha=1.0)
+    plt = gudhi.show_palette_values(alpha=1.0)
+    plt.show()
 
 .. plot::
 
     import gudhi
-    gudhi.show_palette_values(alpha=1.0)
+    plt = gudhi.show_palette_values(alpha=1.0)
+    plt.show()
 
 Show persistence as a barcode
 -----------------------------
@@ -32,7 +34,8 @@ This function can display the persistence result as a barcode:
     
     periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file='3d_torus.txt')
     diag = periodic_cc.persistence()
-    gudhi.plot_persistence_barcode(diag)
+    plt = gudhi.plot_persistence_barcode(diag)
+    plt.show()
 
 .. plot::
 
@@ -40,7 +43,8 @@ This function can display the persistence result as a barcode:
 
     periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file='3d_torus.txt')
     diag = periodic_cc.persistence()
-    gudhi.plot_persistence_barcode(diag)
+    plt = gudhi.plot_persistence_barcode(diag)
+    plt.show()
 
 Show persistence as a diagram
 -----------------------------
@@ -51,16 +55,18 @@ This function can display the persistence result as a diagram:
 
     import gudhi
     
-    rips_complex = gudhi.RipsComplex(off_file='tore3D_300.off', max_edge_length=2.0)
+    rips_complex = gudhi.RipsComplex(off_file='tore3D_1307.off', max_edge_length=0.2)
     simplex_tree = rips_complex.create_simplex_tree(max_dimension=3)
     diag = simplex_tree.persistence()
-    gudhi.plot_persistence_diagram(diag)
+    plt = gudhi.plot_persistence_diagram(diag, band_boot=0.13)
+    plt.show()
 
 .. plot::
 
     import gudhi
 
-    rips_complex = gudhi.RipsComplex(off_file='tore3D_300.off', max_edge_length=2.0)
+    rips_complex = gudhi.RipsComplex(off_file='tore3D_1307.off', max_edge_length=0.2)
     simplex_tree = rips_complex.create_simplex_tree(max_dimension=3)
     diag = simplex_tree.persistence()
-    gudhi.plot_persistence_diagram(diag)
+    plt = gudhi.plot_persistence_diagram(diag, band_boot=0.13)
+    plt.show()
diff --git a/src/cython/doc/pyplots/barcode_persistence.py b/src/cython/doc/pyplots/barcode_persistence.py
index c06ac5a7..9cd3149d 100755
--- a/src/cython/doc/pyplots/barcode_persistence.py
+++ b/src/cython/doc/pyplots/barcode_persistence.py
@@ -1,5 +1,6 @@
 import gudhi
 
-periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file='../3d_torus.txt')
+periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file='3d_torus.txt')
 diag = periodic_cc.persistence()
-gudhi.plot_persistence_barcode(diag)
+plt = gudhi.plot_persistence_barcode(diag)
+plt.show()
diff --git a/src/cython/doc/pyplots/diagram_persistence.py b/src/cython/doc/pyplots/diagram_persistence.py
index b4714fe3..30661965 100755
--- a/src/cython/doc/pyplots/diagram_persistence.py
+++ b/src/cython/doc/pyplots/diagram_persistence.py
@@ -1,5 +1,7 @@
 import gudhi
 
-alpha_complex = gudhi.AlphaComplex(off_file='../tore3D_300.off')
-diag = alpha_complex.persistence()
-gudhi.plot_persistence_diagram(diag)
+rips_complex = gudhi.RipsComplex(off_file='tore3D_1307.off', max_edge_length=0.2)
+simplex_tree = rips_complex.create_simplex_tree(max_dimension=3)
+diag = simplex_tree.persistence()
+plt = gudhi.plot_persistence_diagram(diag, band_boot=0.13)
+plt.show()
diff --git a/src/cython/doc/pyplots/show_palette_values.py b/src/cython/doc/pyplots/show_palette_values.py
index e72a55fd..fdf9645f 100755
--- a/src/cython/doc/pyplots/show_palette_values.py
+++ b/src/cython/doc/pyplots/show_palette_values.py
@@ -1,2 +1,3 @@
 import gudhi
-gudhi.show_palette_values(alpha=1.0)
+plt = gudhi.show_palette_values(alpha=1.0)
+plt.show()
diff --git a/src/cython/doc/python3-sphinx-build b/src/cython/doc/python3-sphinx-build.in
index 44b94169..c97965f5 100755
--- a/src/cython/doc/python3-sphinx-build
+++ b/src/cython/doc/python3-sphinx-build.in
@@ -1,4 +1,4 @@
-#!/usr/bin/python3
+#!@PYTHON_EXECUTABLE@
 
 """
 Emulate sphinx-build for python3
diff --git a/src/cython/doc/reader_utils_ref.rst b/src/cython/doc/reader_utils_ref.rst
new file mode 100644
index 00000000..9c1ea6fc
--- /dev/null
+++ b/src/cython/doc/reader_utils_ref.rst
@@ -0,0 +1,11 @@
+=============================
+Reader utils reference manual
+=============================
+
+.. autofunction:: gudhi.read_off
+
+.. autofunction:: gudhi.read_lower_triangular_matrix_from_csv_file
+
+.. autofunction:: gudhi.read_persistence_intervals_grouped_by_dimension
+
+.. autofunction:: gudhi.read_persistence_intervals_in_dimension