Code and doc review with IFPEN :

plot_*: c'est quoi ce paramètre alpha ?

band_boot: Renommer en 'band', sans référence au bootstrap. Ne pas
l'utiliser dans la majorité des exemples / tutos.

max_plots: mettre une valeur par défaut, pour éviter qu'on se retrouve
trop facilement coincé à attendre 1h qu'il affiche des points.
Éventuellement afficher un message indiquant que certains points n'ont pas
été affichés et comment changer ça.

barcode: trier les barres par date de naissance (le faire
tout le temps ou avoir une option et le faire par défaut).



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

Former-commit-id: cfa775e425fbf12da1758d601ccbd80a2c7d3bc9

11 files changed, 42 insertions, 35 deletions

diff --git a/src/cython/cython/persistence_graphical_tools.py b/src/cython/cython/persistence_graphical_tools.py
index fb837e29..f7dadb53 100755
--- a/src/cython/cython/persistence_graphical_tools.py
+++ b/src/cython/cython/persistence_graphical_tools.py
@@ -28,13 +28,13 @@ __author__ = "Vincent Rouvreau, Bertrand Michel"
 __copyright__ = "Copyright (C) 2016 INRIA"
 __license__ = "GPL v3"
 
-def __min_birth_max_death(persistence, band_boot=0.):
+def __min_birth_max_death(persistence, band=0.):
     """This function returns (min_birth, max_death) from the persistence.
 
     :param persistence: The persistence to plot.
     :type persistence: list of tuples(dimension, tuple(birth, death)).
-    :param band_boot: bootstrap band
-    :type band_boot: float.
+    :param band: band
+    :type band: float.
     :returns: (float, float) -- (min_birth, max_death).
     """
     # Look for minimum birth date and maximum death date for plot optimisation
@@ -48,8 +48,8 @@ def __min_birth_max_death(persistence, band_boot=0.):
             max_death = float(interval[1][0])
         if float(interval[1][0]) < min_birth:
             min_birth = float(interval[1][0])
-    if band_boot > 0.:
-        max_death += band_boot
+    if band > 0.:
+        max_death += band
     return (min_birth, max_death)
 
 """
@@ -77,16 +77,17 @@ def show_palette_values(alpha=0.6):
     plt.title('Dimension palette values')
     return plt
 
-def plot_persistence_barcode(persistence=[], persistence_file='', alpha=0.6, max_barcodes=0):
+def plot_persistence_barcode(persistence=[], persistence_file='', alpha=0.6, max_barcodes=1000):
     """This function plots the persistence bar code.
 
     :param persistence: The persistence to plot.
     :type persistence: list of tuples(dimension, tuple(birth, death)).
     :param persistence_file: A persistence file style name (reset persistence if both are set).
     :type persistence_file: string
-    :param alpha: alpha value in [0.0, 1.0] for horizontal bars (default is 0.6).
+    :param alpha: barcode transparency value (0.0 transparent through 1.0 opaque - default is 0.6).
     :type alpha: float.
-    :param max_barcodes: number of maximal barcodes to be displayed
+    :param max_barcodes: number of maximal barcodes to be displayed.
+        Set it to 0 to see all, Default value is 1000.
         (persistence will be sorted by life time if max_barcodes is set)
     :type max_barcodes: int.
     :returns: plot -- An horizontal bar plot of persistence.
@@ -107,6 +108,8 @@ def plot_persistence_barcode(persistence=[], persistence_file='', alpha=0.6, max
         # Sort by life time, then takes only the max_plots elements
         persistence = sorted(persistence, key=lambda life_time: life_time[1][1]-life_time[1][0], reverse=True)[:max_barcodes]
 
+    persistence = sorted(persistence, key=lambda birth: birth[1][0])
+
     (min_birth, max_death) = __min_birth_max_death(persistence)
     ind = 0
     delta = ((max_death - min_birth) / 10.0)
@@ -120,12 +123,14 @@ def plot_persistence_barcode(persistence=[], persistence_file='', alpha=0.6, max
             # Finite death case
             plt.barh(ind, (interval[1][1] - interval[1][0]), height=0.8,
                      left = interval[1][0], alpha=alpha,
-                     color = palette[interval[0]])
+                     color = palette[interval[0]],
+                     linewidth=0)
         else:
             # Infinite death case for diagram to be nicer
             plt.barh(ind, (infinity - interval[1][0]), height=0.8,
                      left = interval[1][0], alpha=alpha,
-                     color = palette[interval[0]])
+                     color = palette[interval[0]],
+                     linewidth=0)
         ind = ind + 1
 
     plt.title('Persistence barcode')
@@ -133,18 +138,20 @@ def plot_persistence_barcode(persistence=[], persistence_file='', alpha=0.6, max
     plt.axis([axis_start, infinity, 0, ind])
     return plt
 
-def plot_persistence_diagram(persistence=[], persistence_file='', alpha=0.6, band_boot=0., max_plots=0):
+def plot_persistence_diagram(persistence=[], persistence_file='', alpha=0.6, band=0., max_plots=1000):
     """This function plots the persistence diagram with an optional confidence band.
 
     :param persistence: The persistence to plot.
     :type persistence: list of tuples(dimension, tuple(birth, death)).
     :param persistence_file: A persistence file style name (reset persistence if both are set).
     :type persistence_file: string
-    :param alpha: alpha value in [0.0, 1.0] for points and horizontal infinity line (default is 0.6).
+    :param alpha: plot transparency value (0.0 transparent through 1.0 opaque - default is 0.6).
     :type alpha: float.
-    :param band_boot: bootstrap band (not displayed if :math:`\leq` 0.)
-    :type band_boot: float.
+    :param band: band (not displayed if :math:`\leq` 0. - default is 0.)
+    :type band: float.
     :param max_plots: number of maximal plots to be displayed
+        Set it to 0 to see all, Default value is 1000.
+        (persistence will be sorted by life time if max_plots is set)
     :type max_plots: int.
     :returns: plot -- A diagram plot of persistence.
     """
@@ -164,7 +171,7 @@ def plot_persistence_diagram(persistence=[], persistence_file='', alpha=0.6, ban
         # Sort by life time, then takes only the max_plots elements
         persistence = sorted(persistence, key=lambda life_time: life_time[1][1]-life_time[1][0], reverse=True)[:max_plots]
 
-    (min_birth, max_death) = __min_birth_max_death(persistence, band_boot)
+    (min_birth, max_death) = __min_birth_max_death(persistence, band)
     ind = 0
     delta = ((max_death - min_birth) / 10.0)
     # Replace infinity values with max_death + delta for diagram to be more
@@ -179,8 +186,8 @@ def plot_persistence_diagram(persistence=[], persistence_file='', alpha=0.6, ban
     plt.plot(x, [infinity] * len(x), linewidth=1.0, color='k', alpha=alpha)
     plt.text(axis_start, infinity, r'$\infty$', color='k', alpha=alpha)
     # bootstrap band
-    if band_boot > 0.:
-        plt.fill_between(x, x, x+band_boot, alpha=alpha, facecolor='red')
+    if band > 0.:
+        plt.fill_between(x, x, x+band, alpha=alpha, facecolor='red')
 
     # Draw points in loop
     for interval in reversed(persistence):
diff --git a/src/cython/doc/persistence_graphical_tools_user.rst b/src/cython/doc/persistence_graphical_tools_user.rst
index a5523d23..290b13c3 100644
--- a/src/cython/doc/persistence_graphical_tools_user.rst
+++ b/src/cython/doc/persistence_graphical_tools_user.rst
@@ -62,7 +62,7 @@ This function can display the persistence result as a diagram:
     rips_complex = gudhi.RipsComplex(points=point_cloud, 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 = gudhi.plot_persistence_diagram(diag)
     plt.show()
 
 .. plot::
@@ -73,5 +73,5 @@ This function can display the persistence result as a diagram:
     rips_complex = gudhi.RipsComplex(points=point_cloud, 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 = gudhi.plot_persistence_diagram(diag)
     plt.show()
diff --git a/src/cython/doc/pyplots/diagram_persistence.py b/src/cython/doc/pyplots/diagram_persistence.py
index ac20bf47..5abf52b9 100755
--- a/src/cython/doc/pyplots/diagram_persistence.py
+++ b/src/cython/doc/pyplots/diagram_persistence.py
@@ -5,5 +5,5 @@ point_cloud = gudhi.read_off(off_file=gudhi.__root_source_dir__ + \
 rips_complex = gudhi.RipsComplex(points=point_cloud, 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 = gudhi.plot_persistence_diagram(diag)
 plt.show()
diff --git a/src/cython/example/alpha_complex_diagram_persistence_from_off_file_example.py b/src/cython/example/alpha_complex_diagram_persistence_from_off_file_example.py
index b4487be4..10d4867a 100755
--- a/src/cython/example/alpha_complex_diagram_persistence_from_off_file_example.py
+++ b/src/cython/example/alpha_complex_diagram_persistence_from_off_file_example.py
@@ -38,7 +38,7 @@ parser = argparse.ArgumentParser(description='AlphaComplex creation from '
                                  'points from the given OFF file.')
 parser.add_argument("-f", "--file", type=str, required=True)
 parser.add_argument("-a", "--max_alpha_square", type=float, default=0.5)
-parser.add_argument("-b", "--band_boot", type=float, default=0.)
+parser.add_argument("-b", "--band", type=float, default=0.)
 parser.add_argument('--no-diagram', default=False, action='store_true' , help='Flag for not to display the diagrams')
 
 args = parser.parse_args()
@@ -64,7 +64,7 @@ with open(args.file, 'r') as f:
         print(simplex_tree.betti_numbers())
     
         if args.no_diagram == False:
-            pplot = gudhi.plot_persistence_diagram(diag, band_boot=args.band_boot)
+            pplot = gudhi.plot_persistence_diagram(diag, band=args.band)
             pplot.show()
     else:
         print(args.file, "is not a valid OFF file")
diff --git a/src/cython/example/euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py b/src/cython/example/euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py
index e3f362dc..28a8599c 100755
--- a/src/cython/example/euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py
+++ b/src/cython/example/euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py
@@ -40,7 +40,7 @@ parser.add_argument("-f", "--file", type=str, required=True)
 parser.add_argument("-a", "--max_alpha_square", type=float, required=True)
 parser.add_argument("-n", "--number_of_landmarks", type=int, required=True)
 parser.add_argument("-d", "--limit_dimension", type=int, required=True)
-parser.add_argument("-b", "--band_boot", type=float, default=0.)
+parser.add_argument("-b", "--band", type=float, default=0.)
 parser.add_argument('--no-diagram', default=False, action='store_true' , help='Flag for not to display the diagrams')
 
 args = parser.parse_args()
@@ -71,7 +71,7 @@ with open(args.file, 'r') as f:
         print(simplex_tree.betti_numbers())
 
         if args.no_diagram == False:
-            pplot = gudhi.plot_persistence_diagram(diag, band_boot=args.band_boot)
+            pplot = gudhi.plot_persistence_diagram(diag, band=args.band)
             pplot.show()
     else:
         print(args.file, "is not a valid OFF file")
diff --git a/src/cython/example/euclidean_witness_complex_diagram_persistence_from_off_file_example.py b/src/cython/example/euclidean_witness_complex_diagram_persistence_from_off_file_example.py
index c236d992..b19d7d8c 100755
--- a/src/cython/example/euclidean_witness_complex_diagram_persistence_from_off_file_example.py
+++ b/src/cython/example/euclidean_witness_complex_diagram_persistence_from_off_file_example.py
@@ -40,7 +40,7 @@ parser.add_argument("-f", "--file", type=str, required=True)
 parser.add_argument("-a", "--max_alpha_square", type=float, required=True)
 parser.add_argument("-n", "--number_of_landmarks", type=int, required=True)
 parser.add_argument("-d", "--limit_dimension", type=int, required=True)
-parser.add_argument("-b", "--band_boot", type=float, default=0.)
+parser.add_argument("-b", "--band", type=float, default=0.)
 parser.add_argument('--no-diagram', default=False, action='store_true' , help='Flag for not to display the diagrams')
 
 args = parser.parse_args()
@@ -71,7 +71,7 @@ with open(args.file, 'r') as f:
         print(simplex_tree.betti_numbers())
 
         if args.no_diagram == False:
-            pplot = gudhi.plot_persistence_diagram(diag, band_boot=args.band_boot)
+            pplot = gudhi.plot_persistence_diagram(diag, band=args.band)
             pplot.show()
     else:
         print(args.file, "is not a valid OFF file")
diff --git a/src/cython/example/gudhi_graphical_tools_example.py b/src/cython/example/gudhi_graphical_tools_example.py
index ed87806b..97983262 100755
--- a/src/cython/example/gudhi_graphical_tools_example.py
+++ b/src/cython/example/gudhi_graphical_tools_example.py
@@ -50,5 +50,5 @@ pplot.show()
 print("#####################################################################")
 print("Show diagram persistence example with a confidence band")
 
-pplot = gudhi.plot_persistence_diagram(persistence, band_boot=0.2)
+pplot = gudhi.plot_persistence_diagram(persistence, band=0.2)
 pplot.show()
diff --git a/src/cython/example/rips_complex_diagram_persistence_from_correlation_matrix_file_example.py b/src/cython/example/rips_complex_diagram_persistence_from_correlation_matrix_file_example.py
index aa82ef71..0af4397a 100755
--- a/src/cython/example/rips_complex_diagram_persistence_from_correlation_matrix_file_example.py
+++ b/src/cython/example/rips_complex_diagram_persistence_from_correlation_matrix_file_example.py
@@ -40,7 +40,7 @@ parser = argparse.ArgumentParser(description='RipsComplex creation from '
 parser.add_argument("-f", "--file", type=str, required=True)
 parser.add_argument("-c", "--min_edge_correlation", type=float, default=0.5)
 parser.add_argument("-d", "--max_dimension", type=int, default=1)
-parser.add_argument("-b", "--band_boot", type=float, default=0.)
+parser.add_argument("-b", "--band", type=float, default=0.)
 parser.add_argument('--no-diagram', default=False, action='store_true' , help='Flag for not to display the diagrams')
 
 args = parser.parse_args()
@@ -80,5 +80,5 @@ print(simplex_tree.betti_numbers())
 invert_diag = [(diag[pers][0],(1.-diag[pers][1][0], 1.-diag[pers][1][1])) for pers in range(len(diag))]
 
 if args.no_diagram == False:
-    pplot = gudhi.plot_persistence_diagram(invert_diag, band_boot=args.band_boot)
+    pplot = gudhi.plot_persistence_diagram(invert_diag, band=args.band)
     pplot.show()
diff --git a/src/cython/example/rips_complex_diagram_persistence_from_distance_matrix_file_example.py b/src/cython/example/rips_complex_diagram_persistence_from_distance_matrix_file_example.py
index c8aac240..266c09ca 100755
--- a/src/cython/example/rips_complex_diagram_persistence_from_distance_matrix_file_example.py
+++ b/src/cython/example/rips_complex_diagram_persistence_from_distance_matrix_file_example.py
@@ -39,7 +39,7 @@ parser = argparse.ArgumentParser(description='RipsComplex creation from '
 parser.add_argument("-f", "--file", type=str, required=True)
 parser.add_argument("-e", "--max_edge_length", type=float, default=0.5)
 parser.add_argument("-d", "--max_dimension", type=int, default=1)
-parser.add_argument("-b", "--band_boot", type=float, default=0.)
+parser.add_argument("-b", "--band", type=float, default=0.)
 parser.add_argument('--no-diagram', default=False, action='store_true' , help='Flag for not to display the diagrams')
 
 args = parser.parse_args()
@@ -63,5 +63,5 @@ print("betti_numbers()=")
 print(simplex_tree.betti_numbers())
 
 if args.no_diagram == False:
-    pplot = gudhi.plot_persistence_diagram(diag, band_boot=args.band_boot)
+    pplot = gudhi.plot_persistence_diagram(diag, band=args.band)
     pplot.show()
diff --git a/src/cython/example/rips_complex_diagram_persistence_from_off_file_example.py b/src/cython/example/rips_complex_diagram_persistence_from_off_file_example.py
index 544b68c9..fede920c 100755
--- a/src/cython/example/rips_complex_diagram_persistence_from_off_file_example.py
+++ b/src/cython/example/rips_complex_diagram_persistence_from_off_file_example.py
@@ -39,7 +39,7 @@ parser = argparse.ArgumentParser(description='RipsComplex creation from '
 parser.add_argument("-f", "--file", type=str, required=True)
 parser.add_argument("-e", "--max_edge_length", type=float, default=0.5)
 parser.add_argument("-d", "--max_dimension", type=int, default=1)
-parser.add_argument("-b", "--band_boot", type=float, default=0.)
+parser.add_argument("-b", "--band", type=float, default=0.)
 parser.add_argument('--no-diagram', default=False, action='store_true' , help='Flag for not to display the diagrams')
 
 args = parser.parse_args()
@@ -66,7 +66,7 @@ with open(args.file, 'r') as f:
         print(simplex_tree.betti_numbers())
     
         if args.no_diagram == False:
-            pplot = gudhi.plot_persistence_diagram(diag, band_boot=args.band_boot)
+            pplot = gudhi.plot_persistence_diagram(diag, band=args.band)
             pplot.show()
     else:
         print(args.file, "is not a valid OFF file")
diff --git a/src/cython/example/tangential_complex_plain_homology_from_off_file_example.py b/src/cython/example/tangential_complex_plain_homology_from_off_file_example.py
index 08ae5d07..1f562b5c 100755
--- a/src/cython/example/tangential_complex_plain_homology_from_off_file_example.py
+++ b/src/cython/example/tangential_complex_plain_homology_from_off_file_example.py
@@ -38,7 +38,7 @@ parser = argparse.ArgumentParser(description='TangentialComplex creation from '
                                  'points from the given OFF file')
 parser.add_argument("-f", "--file", type=str, required=True)
 parser.add_argument("-i", "--intrisic_dim", type=int, required=True)
-parser.add_argument("-b", "--band_boot", type=float, default=0.)
+parser.add_argument("-b", "--band", type=float, default=0.)
 parser.add_argument('--no-diagram', default=False, action='store_true' , help='Flag for not to display the diagrams')
 
 args = parser.parse_args()
@@ -61,7 +61,7 @@ with open(args.file, 'r') as f:
         print(st.betti_numbers())
     
         if args.no_diagram == False:
-            pplot = gudhi.plot_persistence_diagram(diag, band_boot=args.band_boot)
+            pplot = gudhi.plot_persistence_diagram(diag, band=args.band)
             pplot.show()
     else:
         print(args.file, "is not a valid OFF file")