From bcc49c54943e20b117a3a83579d94f6c1b0efd04 Mon Sep 17 00:00:00 2001 From: Marc Glisse Date: Sat, 4 Jan 2020 12:50:14 +0100 Subject: Link the doc for subsampling & point file readers, some reorg --- src/python/doc/diagram_readers_ref.rst | 11 ++++++++++ src/python/doc/index.rst | 40 ++++++++++++++++------------------ src/python/doc/point_cloud.rst | 22 +++++++++++++++++++ src/python/doc/point_cloud_sum.inc | 15 +++++++++++++ src/python/doc/reader_utils_ref.rst | 15 ------------- src/python/gudhi/off_reader.pyx | 2 +- src/python/gudhi/reader_utils.pyx | 6 ++--- src/python/gudhi/subsampling.pyx | 12 +++++----- 8 files changed, 77 insertions(+), 46 deletions(-) create mode 100644 src/python/doc/diagram_readers_ref.rst create mode 100644 src/python/doc/point_cloud.rst create mode 100644 src/python/doc/point_cloud_sum.inc delete mode 100644 src/python/doc/reader_utils_ref.rst diff --git a/src/python/doc/diagram_readers_ref.rst b/src/python/doc/diagram_readers_ref.rst new file mode 100644 index 00000000..c79daf9c --- /dev/null +++ b/src/python/doc/diagram_readers_ref.rst @@ -0,0 +1,11 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + +================================ +Diagram readers reference manual +================================ + +.. autofunction:: gudhi.read_persistence_intervals_grouped_by_dimension + +.. autofunction:: gudhi.read_persistence_intervals_in_dimension diff --git a/src/python/doc/index.rst b/src/python/doc/index.rst index c36a578f..9513deb0 100644 --- a/src/python/doc/index.rst +++ b/src/python/doc/index.rst @@ -6,8 +6,8 @@ GUDHI Python modules documentation :alt: Gudhi banner :figclass: align-center -Complexes -********* +Data structures for cell complexes +********************************** Cubical complexes ================= @@ -17,18 +17,26 @@ Cubical complexes Simplicial complexes ==================== +Simplex tree +------------ + +.. include:: simplex_tree_sum.inc + +Filtrations and reconstructions +******************************* + Alpha complex -------------- +============= .. include:: alpha_complex_sum.inc Rips complex ------------- +============ .. include:: rips_complex_sum.inc Witness complex ---------------- +=============== .. include:: witness_complex_sum.inc @@ -37,16 +45,10 @@ Cover complexes .. include:: nerve_gic_complex_sum.inc -Data structures and basic operations -************************************ - -Data structures -=============== - -Simplex tree ------------- +Tangential complex +================== -.. include:: simplex_tree_sum.inc +.. include:: tangential_complex_sum.inc Topological descriptors computation *********************************** @@ -56,14 +58,10 @@ Persistence cohomology .. include:: persistent_cohomology_sum.inc -Manifold reconstruction -*********************** - -Tangential complex -================== - -.. include:: tangential_complex_sum.inc +Point cloud utilities +********************* +.. include:: point_cloud_sum.inc Topological descriptors tools ***************************** diff --git a/src/python/doc/point_cloud.rst b/src/python/doc/point_cloud.rst new file mode 100644 index 00000000..6a74d253 --- /dev/null +++ b/src/python/doc/point_cloud.rst @@ -0,0 +1,22 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + +============================ +Point cloud utilities manual +============================ + +File Readers +------------ + +.. autofunction:: gudhi.read_off + +.. autofunction:: gudhi.read_lower_triangular_matrix_from_csv_file + +Subsampling +----------- + +.. automodule:: gudhi.subsampling + :members: + :special-members: + :show-inheritance: diff --git a/src/python/doc/point_cloud_sum.inc b/src/python/doc/point_cloud_sum.inc new file mode 100644 index 00000000..cefcf1c8 --- /dev/null +++ b/src/python/doc/point_cloud_sum.inc @@ -0,0 +1,15 @@ +.. table:: + :widths: 30 50 20 + + +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | :math:`(x_1, x_2, \ldots, x_d)` | Utilities to process point clouds: read from file, subsample, etc. | :Author: Vincent Rouvreau | + | :math:`(y_1, y_2, \ldots, y_d)` | | | + | | | :Introduced in: GUDHI 2.0.0 | + | | | | + | | | :Copyright: MIT (`GPL v3 `_) | + | | Parts of this package require CGAL. | | + | | | :Requires: `Eigen `__ :math:`\geq` 3.1.0 and `CGAL `__ :math:`\geq` 4.11.0 | + | | | | + +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ + | * :doc:`point_cloud` | + +----------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/src/python/doc/reader_utils_ref.rst b/src/python/doc/reader_utils_ref.rst deleted file mode 100644 index f3ecebad..00000000 --- a/src/python/doc/reader_utils_ref.rst +++ /dev/null @@ -1,15 +0,0 @@ -:orphan: - -.. To get rid of WARNING: document isn't included in any toctree - -============================= -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 diff --git a/src/python/gudhi/off_reader.pyx b/src/python/gudhi/off_reader.pyx index 225e981c..e45356be 100644 --- a/src/python/gudhi/off_reader.pyx +++ b/src/python/gudhi/off_reader.pyx @@ -26,7 +26,7 @@ def read_off(off_file=''): :type off_file: string :returns: The point set. - :rtype: vector[vector[double]] + :rtype: list(list(float)) """ if off_file: if os.path.isfile(off_file): diff --git a/src/python/gudhi/reader_utils.pyx b/src/python/gudhi/reader_utils.pyx index 6994c4f9..5a756e4b 100644 --- a/src/python/gudhi/reader_utils.pyx +++ b/src/python/gudhi/reader_utils.pyx @@ -34,7 +34,7 @@ def read_lower_triangular_matrix_from_csv_file(csv_file='', separator=';'): :type separator: char :returns: The lower triangular matrix. - :rtype: vector[vector[double]] + :rtype: list(list(float)) """ if csv_file: if path.isfile(csv_file): @@ -45,7 +45,7 @@ def read_lower_triangular_matrix_from_csv_file(csv_file='', separator=';'): def read_persistence_intervals_grouped_by_dimension(persistence_file=''): """Reads a file containing persistence intervals. Each line might contain 2, 3 or 4 values: [[field] dimension] birth death - The return value is an `map[dim, vector[pair[birth, death]]]` + The return value is a `dict(dim, list(tuple(birth, death)))` where `dim` is an `int`, `birth` a `double`, and `death` a `double`. Note: the function does not check that birth <= death. @@ -53,7 +53,7 @@ def read_persistence_intervals_grouped_by_dimension(persistence_file=''): :type persistence_file: string :returns: The persistence pairs grouped by dimension. - :rtype: map[int, vector[pair[double, double]]] + :rtype: dict(int, list(tuple(float, float))) """ if persistence_file: if path.isfile(persistence_file): diff --git a/src/python/gudhi/subsampling.pyx b/src/python/gudhi/subsampling.pyx index e0cd1348..04f66219 100644 --- a/src/python/gudhi/subsampling.pyx +++ b/src/python/gudhi/subsampling.pyx @@ -33,7 +33,7 @@ def choose_n_farthest_points(points=None, off_file='', nb_points=0, starting_poi The iteration starts with the landmark `starting point`. :param points: The input point set. - :type points: vector[vector[double]]. + :type points: list(list(float)). Or @@ -47,7 +47,7 @@ def choose_n_farthest_points(points=None, off_file='', nb_points=0, starting_poi index is chosen randomly. :type starting_point: unsigned. :returns: The subsample point set. - :rtype: vector[vector[double]] + :rtype: list(list(float)). """ if off_file: if os.path.isfile(off_file): @@ -74,7 +74,7 @@ def pick_n_random_points(points=None, off_file='', nb_points=0): """Subsample a point set by picking random vertices. :param points: The input point set. - :type points: vector[vector[double]]. + :type points: list(list(float)). Or @@ -84,7 +84,7 @@ def pick_n_random_points(points=None, off_file='', nb_points=0): :param nb_points: Number of points of the subsample. :type nb_points: unsigned. :returns: The subsample point set. - :rtype: vector[vector[double]] + :rtype: list(list(float)) """ if off_file: if os.path.isfile(off_file): @@ -103,7 +103,7 @@ def sparsify_point_set(points=None, off_file='', min_squared_dist=0.0): between any two points is greater than or equal to min_squared_dist. :param points: The input point set. - :type points: vector[vector[double]]. + :type points: list(list(float)). Or @@ -114,7 +114,7 @@ def sparsify_point_set(points=None, off_file='', min_squared_dist=0.0): points. :type min_squared_dist: float. :returns: The subsample point set. - :rtype: vector[vector[double]] + :rtype: list(list(float)) """ if off_file: if os.path.isfile(off_file): -- cgit v1.2.3 From 18c98020adea4a7d0c53fe4e76c92bab23e7ad76 Mon Sep 17 00:00:00 2001 From: Marc Glisse Date: Thu, 9 Jan 2020 18:03:39 +0100 Subject: Spell out types as in PEP 484 but don't actually use annotations. A quick try with sphinx-autodoc-typehints failed, I didn't investigate much, it can wait. --- src/python/gudhi/off_reader.pyx | 2 +- src/python/gudhi/reader_utils.pyx | 6 +++--- src/python/gudhi/subsampling.pyx | 12 ++++++------ 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/src/python/gudhi/off_reader.pyx b/src/python/gudhi/off_reader.pyx index e45356be..3a31eba6 100644 --- a/src/python/gudhi/off_reader.pyx +++ b/src/python/gudhi/off_reader.pyx @@ -26,7 +26,7 @@ def read_off(off_file=''): :type off_file: string :returns: The point set. - :rtype: list(list(float)) + :rtype: List[List[float]] """ if off_file: if os.path.isfile(off_file): diff --git a/src/python/gudhi/reader_utils.pyx b/src/python/gudhi/reader_utils.pyx index 5a756e4b..9ced6bca 100644 --- a/src/python/gudhi/reader_utils.pyx +++ b/src/python/gudhi/reader_utils.pyx @@ -34,7 +34,7 @@ def read_lower_triangular_matrix_from_csv_file(csv_file='', separator=';'): :type separator: char :returns: The lower triangular matrix. - :rtype: list(list(float)) + :rtype: List[List[float]] """ if csv_file: if path.isfile(csv_file): @@ -46,14 +46,14 @@ def read_persistence_intervals_grouped_by_dimension(persistence_file=''): """Reads a file containing persistence intervals. Each line might contain 2, 3 or 4 values: [[field] dimension] birth death The return value is a `dict(dim, list(tuple(birth, death)))` - where `dim` is an `int`, `birth` a `double`, and `death` a `double`. + where `dim` is an `int`, `birth` a `float`, and `death` a `float`. Note: the function does not check that birth <= death. :param persistence_file: A persistence file style name. :type persistence_file: string :returns: The persistence pairs grouped by dimension. - :rtype: dict(int, list(tuple(float, float))) + :rtype: Dict[int, List[Tuple[float, float]]] """ if persistence_file: if path.isfile(persistence_file): diff --git a/src/python/gudhi/subsampling.pyx b/src/python/gudhi/subsampling.pyx index 04f66219..f50f4b0c 100644 --- a/src/python/gudhi/subsampling.pyx +++ b/src/python/gudhi/subsampling.pyx @@ -33,7 +33,7 @@ def choose_n_farthest_points(points=None, off_file='', nb_points=0, starting_poi The iteration starts with the landmark `starting point`. :param points: The input point set. - :type points: list(list(float)). + :type points: Iterable[Iterable[float]]. Or @@ -47,7 +47,7 @@ def choose_n_farthest_points(points=None, off_file='', nb_points=0, starting_poi index is chosen randomly. :type starting_point: unsigned. :returns: The subsample point set. - :rtype: list(list(float)). + :rtype: List[List[float]]. """ if off_file: if os.path.isfile(off_file): @@ -74,7 +74,7 @@ def pick_n_random_points(points=None, off_file='', nb_points=0): """Subsample a point set by picking random vertices. :param points: The input point set. - :type points: list(list(float)). + :type points: Iterable[Iterable[float]]. Or @@ -84,7 +84,7 @@ def pick_n_random_points(points=None, off_file='', nb_points=0): :param nb_points: Number of points of the subsample. :type nb_points: unsigned. :returns: The subsample point set. - :rtype: list(list(float)) + :rtype: List[List[float]] """ if off_file: if os.path.isfile(off_file): @@ -103,7 +103,7 @@ def sparsify_point_set(points=None, off_file='', min_squared_dist=0.0): between any two points is greater than or equal to min_squared_dist. :param points: The input point set. - :type points: list(list(float)). + :type points: Iterable[Iterable[float]]. Or @@ -114,7 +114,7 @@ def sparsify_point_set(points=None, off_file='', min_squared_dist=0.0): points. :type min_squared_dist: float. :returns: The subsample point set. - :rtype: list(list(float)) + :rtype: List[List[float]] """ if off_file: if os.path.isfile(off_file): -- cgit v1.2.3 From 2f7f4d84df64172c1af8b8741112c6dd9c883944 Mon Sep 17 00:00:00 2001 From: Marc Glisse Date: Thu, 9 Jan 2020 18:22:24 +0100 Subject: Move point utilities in the index they we between computing diagrams and using diagrams, it looked strange --- src/python/doc/index.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/python/doc/index.rst b/src/python/doc/index.rst index 9513deb0..3387a64f 100644 --- a/src/python/doc/index.rst +++ b/src/python/doc/index.rst @@ -58,11 +58,6 @@ Persistence cohomology .. include:: persistent_cohomology_sum.inc -Point cloud utilities -********************* - -.. include:: point_cloud_sum.inc - Topological descriptors tools ***************************** @@ -86,6 +81,11 @@ Persistence graphical tools .. include:: persistence_graphical_tools_sum.inc +Point cloud utilities +********************* + +.. include:: point_cloud_sum.inc + Bibliography ************ -- cgit v1.2.3 From 051c9760a214a11e8e4af14ae6221e34bb876350 Mon Sep 17 00:00:00 2001 From: Marc Glisse Date: Thu, 9 Jan 2020 20:56:48 +0100 Subject: align text --- src/python/doc/point_cloud_sum.inc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/python/doc/point_cloud_sum.inc b/src/python/doc/point_cloud_sum.inc index cefcf1c8..85d52de7 100644 --- a/src/python/doc/point_cloud_sum.inc +++ b/src/python/doc/point_cloud_sum.inc @@ -2,8 +2,8 @@ :widths: 30 50 20 +----------------------------------------------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------+ - | :math:`(x_1, x_2, \ldots, x_d)` | Utilities to process point clouds: read from file, subsample, etc. | :Author: Vincent Rouvreau | - | :math:`(y_1, y_2, \ldots, y_d)` | | | + | | :math:`(x_1, x_2, \ldots, x_d)` | Utilities to process point clouds: read from file, subsample, etc. | :Author: Vincent Rouvreau | + | | :math:`(y_1, y_2, \ldots, y_d)` | | | | | | :Introduced in: GUDHI 2.0.0 | | | | | | | | :Copyright: MIT (`GPL v3 `_) | -- cgit v1.2.3 From f5e49792f809b198908a67e674672a676c0877ec Mon Sep 17 00:00:00 2001 From: Marc Glisse Date: Sat, 18 Jan 2020 22:56:22 +0100 Subject: Separate optional arguments from common arguments I copy-pasted what is done in RipsComplex. Before that, sphinx was grouping nb_points with off_file, as if it couldn't be used with points. --- src/python/gudhi/subsampling.pyx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/python/gudhi/subsampling.pyx b/src/python/gudhi/subsampling.pyx index 4c84cb03..f77c6f75 100644 --- a/src/python/gudhi/subsampling.pyx +++ b/src/python/gudhi/subsampling.pyx @@ -40,6 +40,8 @@ def choose_n_farthest_points(points=None, off_file='', nb_points=0, starting_poi :param off_file: An OFF file style name. :type off_file: string + And in both cases + :param nb_points: Number of points of the subsample. :type nb_points: unsigned. :param starting_point: The iteration starts with the landmark `starting \ @@ -81,6 +83,8 @@ def pick_n_random_points(points=None, off_file='', nb_points=0): :param off_file: An OFF file style name. :type off_file: string + And in both cases + :param nb_points: Number of points of the subsample. :type nb_points: unsigned. :returns: The subsample point set. @@ -110,6 +114,8 @@ def sparsify_point_set(points=None, off_file='', min_squared_dist=0.0): :param off_file: An OFF file style name. :type off_file: string + And in both cases + :param min_squared_dist: Minimum squared distance separating the output \ points. :type min_squared_dist: float. -- cgit v1.2.3