Add doc for Witness

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

Former-commit-id: b256e90ba831aaa268d42a8a390d89fbc73df10f

5 files changed, 54 insertions, 8 deletions

diff --git a/src/cython/cython/euclidean_strong_witness_complex.pyx b/src/cython/cython/euclidean_strong_witness_complex.pyx
index 73d31708..c1523892 100644
--- a/src/cython/cython/euclidean_strong_witness_complex.pyx
+++ b/src/cython/cython/euclidean_strong_witness_complex.pyx
@@ -38,8 +38,8 @@ cdef extern from "Euclidean_strong_witness_complex_interface.h" namespace "Gudhi
 
 # EuclideanStrongWitnessComplex python interface
 cdef class EuclideanStrongWitnessComplex:
-    """EuclideanStrongWitnessComplex is a simplicial complex constructed from ...
-
+    """Constructs strong witness complex for given sets of witnesses and
+    landmarks in Euclidean space.
     """
 
     cdef Euclidean_strong_witness_complex_interface * thisptr
diff --git a/src/cython/cython/euclidean_witness_complex.pyx b/src/cython/cython/euclidean_witness_complex.pyx
index 6197c322..7c443b6b 100644
--- a/src/cython/cython/euclidean_witness_complex.pyx
+++ b/src/cython/cython/euclidean_witness_complex.pyx
@@ -38,8 +38,8 @@ cdef extern from "Euclidean_witness_complex_interface.h" namespace "Gudhi":
 
 # EuclideanWitnessComplex python interface
 cdef class EuclideanWitnessComplex:
-    """EuclideanWitnessComplex is a simplicial complex constructed from ...
-
+    """Constructs (weak) witness complex for given sets of witnesses and
+    landmarks in Euclidean space.
     """
 
     cdef Euclidean_witness_complex_interface * thisptr
diff --git a/src/cython/cython/strong_witness_complex.pyx b/src/cython/cython/strong_witness_complex.pyx
index 5febffbb..770b46f5 100644
--- a/src/cython/cython/strong_witness_complex.pyx
+++ b/src/cython/cython/strong_witness_complex.pyx
@@ -37,8 +37,8 @@ cdef extern from "Strong_witness_complex_interface.h" namespace "Gudhi":
 
 # StrongWitnessComplex python interface
 cdef class StrongWitnessComplex:
-    """StrongWitnessComplex is a simplicial complex constructed from ...
-
+    """Constructs (strong) witness complex for a given table of nearest
+    landmarks with respect to witnesses.
     """
 
     cdef Strong_witness_complex_interface * thisptr
diff --git a/src/cython/cython/witness_complex.pyx b/src/cython/cython/witness_complex.pyx
index 21624fe3..96d122bb 100644
--- a/src/cython/cython/witness_complex.pyx
+++ b/src/cython/cython/witness_complex.pyx
@@ -37,8 +37,8 @@ cdef extern from "Witness_complex_interface.h" namespace "Gudhi":
 
 # WitnessComplex python interface
 cdef class WitnessComplex:
-    """WitnessComplex is a simplicial complex constructed from ...
-
+    """Constructs (weak) witness complex for a given table of nearest landmarks
+    with respect to witnesses.
     """
 
     cdef Witness_complex_interface * thisptr
diff --git a/src/cython/doc/witness_complex_user.rst b/src/cython/doc/witness_complex_user.rst
index 72b8d839..07945361 100644
--- a/src/cython/doc/witness_complex_user.rst
+++ b/src/cython/doc/witness_complex_user.rst
@@ -76,11 +76,57 @@ Constructing weak relaxed witness complex from an off file
 
 Let's start with a simple example, which reads an off point file and computes a weak witness complex.
 
+.. code-block:: python
+
+    import gudhi
+    import argparse
+
+    parser = argparse.ArgumentParser(description='EuclideanWitnessComplex creation from '
+                                     'points read in a OFF file.',
+                                     epilog='Example: '
+                                     'example/witness_complex_diagram_persistence_from_off_file_example.py '
+                                     '-f ../data/points/tore3D_300.off -a 1.0 -n 20 -d 2'
+                                     '- Constructs a alpha complex with the '
+                                     'points from the given OFF file.')
+    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)
+
+    args = parser.parse_args()
+
+    with open(args.file, 'r') as f:
+        first_line = f.readline()
+        if (first_line == 'OFF\n') or (first_line == 'nOFF\n'):
+            print("#####################################################################")
+            print("EuclideanWitnessComplex creation from points read in a OFF file")
+
+            witnesses = gudhi.read_off(off_file=args.file)
+            landmarks = gudhi.pick_n_random_points(points=witnesses, nb_points=args.number_of_landmarks)
+
+            message = "EuclideanWitnessComplex with max_edge_length=" + repr(args.max_alpha_square) + \
+                " - Number of landmarks=" + repr(args.number_of_landmarks)
+            print(message)
+
+            witness_complex = gudhi.EuclideanWitnessComplex(witnesses=witnesses, landmarks=landmarks)
+            simplex_tree = witness_complex.create_simplex_tree(max_alpha_square=args.max_alpha_square,
+                limit_dimension=args.limit_dimension)
+
+            message = "Number of simplices=" + repr(simplex_tree.num_simplices())
+            print(message)
+        else:
+            print(args.file, "is not a valid OFF file")
+
+        f.close()
+
+
 Example2: Computing persistence using strong relaxed witness complex
 --------------------------------------------------------------------
 
 Here is an example of constructing a strong witness complex filtration and computing persistence on it:
 
+* :download:`euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py <../example/periodic_cubical_complex_barcode_persistence_from_perseus_file_example.py>`
+
 Bibliography
 ************