Merge remote-tracking branch 'upstream/master' into optimal_matching_wasserstein

2 files changed, 28 insertions, 12 deletions

diff --git a/src/python/doc/persistence_graphical_tools_sum.inc b/src/python/doc/persistence_graphical_tools_sum.inc
index 0cdf8072..ef376802 100644
--- a/src/python/doc/persistence_graphical_tools_sum.inc
+++ b/src/python/doc/persistence_graphical_tools_sum.inc
@@ -2,11 +2,11 @@
    :widths: 30 50 20
 
    +-----------------------------------------------------------------+-----------------------------------------------------------------------+-----------------------------------------------+
-   | .. figure::                                                     | These graphical tools comes on top of persistence results and allows  | :Author: Vincent Rouvreau                     |
-   |      img/graphical_tools_representation.png                     | the user to build easily persistence barcode, diagram or density.     |                                               |
+   | .. figure::                                                     | These graphical tools comes on top of persistence results and allows  | :Author: Vincent Rouvreau, Theo Lacombe       |
+   |      img/graphical_tools_representation.png                     | the user to display easily persistence barcode, diagram or density.   |                                               |
    |                                                                 |                                                                       | :Introduced in: GUDHI 2.0.0                   |
-   |                                                                 |                                                                       |                                               |
-   |                                                                 |                                                                       | :Copyright: MIT                               |
+   |                                                                 | Note that these functions return the matplotlib axis, allowing        |                                               |
+   |                                                                 | for further modifications (title, aspect, etc.)                       | :Copyright: MIT                               |
    |                                                                 |                                                                       |                                               |
    |                                                                 |                                                                       | :Requires: matplotlib, numpy and scipy        |
    +-----------------------------------------------------------------+-----------------------------------------------------------------------+-----------------------------------------------+
diff --git a/src/python/doc/persistence_graphical_tools_user.rst b/src/python/doc/persistence_graphical_tools_user.rst
index 80002db6..91e52703 100644
--- a/src/python/doc/persistence_graphical_tools_user.rst
+++ b/src/python/doc/persistence_graphical_tools_user.rst
@@ -20,7 +20,7 @@ This function can display the persistence result as a barcode:
 .. plot::
    :include-source:
 
-    import matplotlib.pyplot as plot
+    import matplotlib.pyplot as plt
     import gudhi
 
     off_file = gudhi.__root_source_dir__ + '/data/points/tore3D_300.off'
@@ -31,7 +31,7 @@ This function can display the persistence result as a barcode:
     diag = simplex_tree.persistence(min_persistence=0.4)
 
     gudhi.plot_persistence_barcode(diag)
-    plot.show()
+    plt.show()
 
 Show persistence as a diagram
 -----------------------------
@@ -44,15 +44,31 @@ This function can display the persistence result as a diagram:
 .. plot::
    :include-source:
 
-    import matplotlib.pyplot as plot
+    import matplotlib.pyplot as plt
     import gudhi
 
     # rips_on_tore3D_1307.pers obtained from write_persistence_diagram method
     persistence_file=gudhi.__root_source_dir__ + \
         '/data/persistence_diagram/rips_on_tore3D_1307.pers'
-    gudhi.plot_persistence_diagram(persistence_file=persistence_file,
+    ax = gudhi.plot_persistence_diagram(persistence_file=persistence_file,
         legend=True)
-    plot.show()
+    # We can modify the title, aspect, etc.
+    ax.set_title("Persistence diagram of a torus")
+    ax.set_aspect("equal")  # forces to be square shaped
+    plt.show()
+
+Note that (as barcode and density) it can also take a simple `np.array` 
+of shape (N x 2) encoding a persistence diagram (in a given dimension).
+
+.. plot::
+    :include-source:
+    
+    import matplotlib.pyplot as plt
+    import gudhi
+    import numpy as np
+    d = np.array([[0, 1], [1, 2], [1, np.inf]])
+    gudhi.plot_persistence_diagram(d)
+    plt.show()
 
 Persistence density
 -------------------
@@ -65,7 +81,7 @@ If you want more information on a specific dimension, for instance:
 .. plot::
    :include-source:
 
-    import matplotlib.pyplot as plot
+    import matplotlib.pyplot as plt
     import gudhi
     # rips_on_tore3D_1307.pers obtained from write_persistence_diagram method
     persistence_file=gudhi.__root_source_dir__ + \
@@ -75,9 +91,9 @@ If you want more information on a specific dimension, for instance:
         only_this_dim=1)
     pers_diag = [(1, elt) for elt in birth_death]
     # Use subplots to display diagram and density side by side
-    fig, axes = plot.subplots(nrows=1, ncols=2, figsize=(12, 5))
+    fig, axes = plt.subplots(nrows=1, ncols=2, figsize=(12, 5))
     gudhi.plot_persistence_diagram(persistence=pers_diag,
         axes=axes[0])
     gudhi.plot_persistence_density(persistence=pers_diag,
         dimension=1, legend=True, axes=axes[1])
-    plot.show()
+    plt.show()