diff options
Diffstat (limited to 'src/cython/doc')
45 files changed, 798 insertions, 187 deletions
diff --git a/src/cython/doc/_templates/layout.html b/src/cython/doc/_templates/layout.html index 243f33c6..bc0e9658 100644 --- a/src/cython/doc/_templates/layout.html +++ b/src/cython/doc/_templates/layout.html @@ -56,6 +56,12 @@ </a></p> {%- endif %} {%- endblock %} + <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> + <h2><a href="examples.html">Examples</a></h2> {%- if sidebars != None %} {#- new style sidebar: explicitly include/exclude templates #} {%- for sidebartemplate in sidebars %} @@ -64,13 +70,6 @@ {%- else %} {#- 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> -<h2><a href="examples.html">Examples</a></h2> - {%- include "localtoc.html" %} {%- endblock %} {%- block sidebarrel %} @@ -108,7 +107,7 @@ {%- macro css() %} <!-- GUDHI website css for header BEGIN --> -<link rel="stylesheet" type="text/css" href="http://gudhi.gforge.inria.fr/assets/css/styles_feeling_responsive.css" /> +<link rel="stylesheet" type="text/css" href="https://gudhi.inria.fr/assets/css/styles_feeling_responsive.css" /> <!-- GUDHI website css for header END --> <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" /> <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" /> @@ -166,56 +165,61 @@ <body role="document"> <!-- GUDHI website header BEGIN --> <div id="navigation" class="sticky"> - <nav class="top-bar" role="navigation" data-topbar> - <ul class="title-area"> - <li class="name"> - <h1 class="show-for-small-only"><a href="http://gudhi.gforge.inria.fr" class="icon-tree"> GUDHI C++ library</a></h1> - </li> - <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone --> - <li class="toggle-topbar menu-icon"><a href="#"><span>Navigation</span></a></li> - </ul> - <section class="top-bar-section"> - <ul class="right"> - <li class="divider"></li> - <li><a href="http://gudhi.gforge.inria.fr/contact/">Contact</a></li> - </ul> - <ul class="left"> - <li><a href="http://gudhi.gforge.inria.fr/"> <img src="http://gudhi.gforge.inria.fr/assets/img/home.png" alt=" GUDHI"> GUDHI </a></li> - <li class="divider"></li> - <li class="has-dropdown"> - <a href="#">Project</a> - <ul class="dropdown"> - <li><a href="http://gudhi.gforge.inria.fr/people/">People</a></li> - <li><a href="http://gudhi.gforge.inria.fr/keepintouch/">Keep in touch</a></li> - <li><a href="http://gudhi.gforge.inria.fr/partners/">Partners and Funding</a></li> - <li><a href="http://gudhi.gforge.inria.fr/relatedprojects/">Related projects</a></li> - <li><a href="http://gudhi.gforge.inria.fr/theyaretalkingaboutus/">They are talking about us</a></li> - </ul> - </li> - <li class="divider"></li> - <li class="has-dropdown"> - <a href="#">Download</a> - <ul class="dropdown"> - <li><a href="http://gudhi.gforge.inria.fr/licensing/">Licensing</a></li> - <li><a href="https://gforge.inria.fr/frs/?group_id=3865" target="_blank">Get the sources</a></li> - </ul> - </li> - <li class="divider"></li> - <li class="has-dropdown"> - <a href="#">Documentation</a> - <ul class="dropdown"> - <li><a href="http://gudhi.gforge.inria.fr/doc/latest/">C++ documentation</a></li> - <li><a href="http://gudhi.gforge.inria.fr/doc/latest/installation.html">C++ installation manual</a></li> - <li><a href="http://gudhi.gforge.inria.fr/python/latest/">Python documentation</a></li> - <li><a href="http://gudhi.gforge.inria.fr/python/latest/installation.html">Python installation manual</a></li> - </ul> - </li> - <li class="divider"></li> - <li><a href="http://gudhi.gforge.inria.fr/interfaces/">Interfaces</a></li> - <li class="divider"></li> - </ul> - </section> - </nav> + <nav class="top-bar" role="navigation" data-topbar> + <ul class="title-area"> + <li class="name"> + <h1 class="show-for-small-only"><a href="" class="icon-tree"> GUDHI C++ library</a></h1> + </li> + <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone --> + <li class="toggle-topbar menu-icon"><a href="#"><span>Navigation</span></a></li> + </ul> + <section class="top-bar-section"> + <ul class="right"> + <li class="divider"></li> + <li><a href="/contact/">Contact</a></li> + </ul> + <ul class="left"> + <li><a href="/"> <img src="/assets/img/home.png" alt=" GUDHI"> GUDHI </a></li> + <li class="divider"></li> + <li class="has-dropdown"> + <a href="#">Project</a> + <ul class="dropdown"> + <li><a href="/people/">People</a></li> + <li><a href="/keepintouch/">Keep in touch</a></li> + <li><a href="/partners/">Partners and Funding</a></li> + <li><a href="/relatedprojects/">Related projects</a></li> + <li><a href="/theyaretalkingaboutus/">They are talking about us</a></li> + </ul> + </li> + <li class="divider"></li> + <li class="has-dropdown"> + <a href="#">Download</a> + <ul class="dropdown"> + <li><a href="/licensing/">Licensing</a></li> + <li><a href="https://gforge.inria.fr/frs/download.php/latestzip/5253/library-latest.zip" target="_blank">Get the latest sources</a></li> + <li><a href="https://gforge.inria.fr/frs/download.php/latestzip/5280/utils_osx-latest.zip" target="_blank">Utils for Mac OSx</a></li> + <li><a href="https://gforge.inria.fr/frs/download.php/latestzip/5279/utils_win64-latest.zip" target="_blank">Utils for Win x64</a></li> + </ul> + </li> + <li class="divider"></li> + <li class="has-dropdown"> + <a href="#">Documentation</a> + <ul class="dropdown"> + <li><a href="/doc/latest/">C++ documentation</a></li> + <li><a href="/doc/latest/installation.html">C++ installation manual</a></li> + <li><a href="/python/latest/">Python documentation</a></li> + <li><a href="/python/latest/installation.html">Python installation manual</a></li> + <li><a href="/utils/">Utilities</a></li> + <li><a href="/tutorials/">Tutorials</a></li> + <li><a href="/dockerfile/">Dockerfile</a></li> + </ul> + </li> + <li class="divider"></li> + <li><a href="/interfaces/">Interfaces</a></li> + <li class="divider"></li> + </ul> + </section> + </nav> </div><!-- /#navigation --> <!-- GUDHI website header BEGIN --> @@ -255,7 +259,7 @@ {%- if hasdoc('copyright') %} {% trans path=pathto('copyright'), copyright=copyright|e %}© <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %} {%- else %} - {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {% trans copyright=copyright|e %} {{ copyright }}.{% endtrans %} {%- endif %} {%- endif %} {%- if last_updated %} diff --git a/src/cython/doc/alpha_complex_ref.rst b/src/cython/doc/alpha_complex_ref.rst index 6a122b09..7da79543 100644 --- a/src/cython/doc/alpha_complex_ref.rst +++ b/src/cython/doc/alpha_complex_ref.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + ============================== Alpha complex reference manual ============================== diff --git a/src/cython/doc/alpha_complex_sum.rst b/src/cython/doc/alpha_complex_sum.inc index 1680a712..1680a712 100644 --- a/src/cython/doc/alpha_complex_sum.rst +++ b/src/cython/doc/alpha_complex_sum.inc diff --git a/src/cython/doc/alpha_complex_user.rst b/src/cython/doc/alpha_complex_user.rst index db7edd6f..d1e9c7cd 100644 --- a/src/cython/doc/alpha_complex_user.rst +++ b/src/cython/doc/alpha_complex_user.rst @@ -1,11 +1,15 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Alpha complex user manual ========================= Definition ---------- -.. include:: alpha_complex_sum.rst +.. include:: alpha_complex_sum.inc -Alpha_complex is constructing a :doc:`Simplex_tree <simplex_tree_sum>` using +Alpha_complex is constructing a :doc:`Simplex_tree <simplex_tree_ref>` using `Delaunay Triangulation <http://doc.cgal.org/latest/Triangulation/index.html#Chapter_Triangulations>`_ :cite:`cgal:hdj-t-15b` from `CGAL <http://www.cgal.org/>`_ (the Computational Geometry Algorithms Library :cite:`cgal:eb-15b`). @@ -99,9 +103,9 @@ Filtration value computation algorithm **end for** **end for** **end for** - + make_filtration_non_decreasing() - + prune_above_filtration() Dimension 2 diff --git a/src/cython/doc/bottleneck_distance_sum.rst b/src/cython/doc/bottleneck_distance_sum.inc index 030fad9e..030fad9e 100644 --- a/src/cython/doc/bottleneck_distance_sum.rst +++ b/src/cython/doc/bottleneck_distance_sum.inc diff --git a/src/cython/doc/bottleneck_distance_user.rst b/src/cython/doc/bottleneck_distance_user.rst index 7692dce2..605db022 100644 --- a/src/cython/doc/bottleneck_distance_user.rst +++ b/src/cython/doc/bottleneck_distance_user.rst @@ -1,9 +1,13 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Bottleneck distance user manual =============================== Definition ---------- -.. include:: bottleneck_distance_sum.rst +.. include:: bottleneck_distance_sum.inc Function -------- diff --git a/src/cython/doc/citation.rst b/src/cython/doc/citation.rst index f4fdf83b..117eb9dd 100644 --- a/src/cython/doc/citation.rst +++ b/src/cython/doc/citation.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Acknowledging the GUDHI library ############################### diff --git a/src/cython/doc/conf.py b/src/cython/doc/conf.py index 19a880d4..4a54d4fd 100755 --- a/src/cython/doc/conf.py +++ b/src/cython/doc/conf.py @@ -62,7 +62,7 @@ import gudhi # General information about the project. project = gudhi.__name__ -copyright = gudhi.__copyright__ +copyright = gudhi.__copyright__ + ' - ' + gudhi.__license__ # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -85,7 +85,7 @@ version = gudhi.__version__ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build'] +exclude_patterns = ['_build', '*.inc'] # The reST default role (used for this markup: `text`) to use for all # documents. @@ -125,6 +125,7 @@ html_theme_options = { "sidebarbgcolor": "#A1ADCD", "sidebartextcolor": "black", "sidebarlinkcolor": "#334D5C", + "body_max_width": "1200px", } # Add any paths that contain custom themes here, relative to this directory. @@ -158,7 +159,7 @@ html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. diff --git a/src/cython/doc/cubical_complex_ref.rst b/src/cython/doc/cubical_complex_ref.rst index 84aa4223..1fe9d5fb 100644 --- a/src/cython/doc/cubical_complex_ref.rst +++ b/src/cython/doc/cubical_complex_ref.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Cubical complex reference manual ################################ diff --git a/src/cython/doc/cubical_complex_sum.rst b/src/cython/doc/cubical_complex_sum.inc index 280ad0e0..280ad0e0 100644 --- a/src/cython/doc/cubical_complex_sum.rst +++ b/src/cython/doc/cubical_complex_sum.inc diff --git a/src/cython/doc/cubical_complex_user.rst b/src/cython/doc/cubical_complex_user.rst index 2bfac62a..320bd79b 100644 --- a/src/cython/doc/cubical_complex_user.rst +++ b/src/cython/doc/cubical_complex_user.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Cubical complex user manual =========================== Definition @@ -81,23 +85,7 @@ filtration to all cubes. There are a number of constructors that can be used to who want to use the code directly. They can be found in the :doc:`cubical_complex_ref`. Currently one input from a text file is used. It uses a format used already in `Perseus software <http://www.sas.upenn.edu/~vnanda/perseus/>`_ by Vidit Nanda. -Below we are providing a description of the format. The first line contains a number d begin the dimension of the -bitmap (2 in the example below). Next d lines are the numbers of top dimensional cubes in each dimensions (3 and 3 -in the example below). Next, in lexicographical order, the filtration of top dimensional cubes is given (1 4 6 8 -20 4 7 6 5 in the example below). - -.. figure:: - ../../doc/Bitmap_cubical_complex/exampleBitmap.png - :alt: Example of a input data. - :figclass: align-center - - Example of a input data. - -The input file for the following complex is: - -.. literalinclude:: ../../data/bitmap/cubicalcomplexdoc.txt - -.. centered:: ../../data/bitmap/cubicalcomplexdoc.txt +The file format is described here: :doc:`Perseus <fileformats>`. .. testcode:: @@ -124,15 +112,9 @@ Imposing periodic boundary conditions in the direction i, means that the left an :math:`\mathcal{K}` are considered the same. In particular, if for a bitmap :math:`\mathcal{K}` periodic boundary conditions are imposed in all directions, then complex :math:`\mathcal{K}` became n-dimensional torus. One can use various constructors from the file Bitmap_cubical_complex_periodic_boundary_conditions_base.h to construct cubical -complex with periodic boundary conditions. One can also use Perseus style input files. To indicate periodic boundary -conditions in a given direction, then number of top dimensional cells in this direction have to be multiplied by -1. -For instance: +complex with periodic boundary conditions. -.. literalinclude:: ../../data/bitmap/periodiccubicalcomplexdoc.txt - -.. centered:: ../../data/bitmap/periodiccubicalcomplexdoc.txt - -Indicate that we have imposed periodic boundary conditions in the direction x, but not in the direction y. +One can also use Perseus style input files (see :doc:`Perseus <fileformats>`) for the specific periodic case: .. testcode:: @@ -149,6 +131,24 @@ the program output is: Periodic cubical complex is of dimension 2 - 42 simplices. +Or it can be defined as follows: + +.. testcode:: + + from gudhi import PeriodicCubicalComplex as pcc + periodic_cc = pcc(dimensions=[3,3], + top_dimensional_cells= [0, 0, 0, 0, 1, 0, 0, 0, 0], + periodic_dimensions=[True, False]) + result_str = 'Periodic cubical complex is of dimension ' + repr(periodic_cc.dimension()) + ' - ' + \ + repr(periodic_cc.num_simplices()) + ' simplices.' + print(result_str) + +the program output is: + +.. testoutput:: + + Periodic cubical complex is of dimension 2 - 42 simplices. + Examples. --------- @@ -157,6 +157,6 @@ End user programs are available in cython/example/ folder. Bibliography ============ -.. bibliography:: ../../bibliography.bib +.. bibliography:: ../../biblio/bibliography.bib :filter: docnames :style: unsrt diff --git a/src/cython/doc/euclidean_strong_witness_complex_ref.rst b/src/cython/doc/euclidean_strong_witness_complex_ref.rst index bebf0f9a..1a602cd5 100644 --- a/src/cython/doc/euclidean_strong_witness_complex_ref.rst +++ b/src/cython/doc/euclidean_strong_witness_complex_ref.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + ================================================= Euclidean strong witness complex reference manual ================================================= diff --git a/src/cython/doc/euclidean_witness_complex_ref.rst b/src/cython/doc/euclidean_witness_complex_ref.rst index 29b8806f..28daf965 100644 --- a/src/cython/doc/euclidean_witness_complex_ref.rst +++ b/src/cython/doc/euclidean_witness_complex_ref.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + ========================================== Euclidean witness complex reference manual ========================================== diff --git a/src/cython/doc/examples.rst b/src/cython/doc/examples.rst index 1e596e18..1f02f8a2 100644 --- a/src/cython/doc/examples.rst +++ b/src/cython/doc/examples.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Examples ######## @@ -19,3 +23,7 @@ Examples * :download:`rips_complex_diagram_persistence_from_distance_matrix_file_example.py <../example/rips_complex_diagram_persistence_from_distance_matrix_file_example.py>` * :download:`rips_persistence_diagram.py <../example/rips_persistence_diagram.py>` * :download:`random_cubical_complex_persistence_example.py <../example/random_cubical_complex_persistence_example.py>` + * :download:`coordinate_graph_induced_complex.py <../example/coordinate_graph_induced_complex.py>` + * :download:`functional_graph_induced_complex.py <../example/functional_graph_induced_complex.py>` + * :download:`voronoi_graph_induced_complex.py <../example/voronoi_graph_induced_complex.py>` + * :download:`nerve_of_a_covering.py <../example/nerve_of_a_covering.py>` diff --git a/src/cython/doc/fileformats.rst b/src/cython/doc/fileformats.rst index 156ef4e4..ff20f26e 100644 --- a/src/cython/doc/fileformats.rst +++ b/src/cython/doc/fileformats.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + File formats ############ @@ -23,7 +27,7 @@ Here is a simple sample file:: 3 34.2 34.974 4 3. inf -Other sample files can be found in the data/persistence_diagram folder. +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 @@ -31,3 +35,56 @@ Such files can be generated with :meth:`gudhi.read_persistence_intervals_in_dimension` and displayed with :meth:`gudhi.plot_persistence_barcode` or :meth:`gudhi.plot_persistence_diagram`. + +Iso-cuboid +********** + +Such a file describes an iso-oriented cuboid with diagonal opposite vertices +(min_x, min_y, min_z,...) and (max_x, max_y, max_z, ...). The format is:: + + min_x min_y [min_z ...] + max_x max_y [max_z ...] + +Here is a simple sample file in the 3D case:: + + -1. -1. -1. + 1. 1. 1. + + +Perseus +******* + +This file format is the format used by the +`Perseus software <http://www.sas.upenn.edu/~vnanda/perseus/>`_ by Vidit Nanda. +The first line contains a number d begin the dimension of the bitmap (2 in the +example below). Next d lines are the numbers of top dimensional cubes in each +dimensions (3 and 3 in the example below). Next, in lexicographical order, the +filtration of top dimensional cubes is given (1 4 6 8 20 4 7 6 5 in the example +below). + +.. figure:: + ../../doc/Bitmap_cubical_complex/exampleBitmap.png + :alt: Example of a input data. + :figclass: align-center + + Example of a input data. + +The input file for the following complex is: + +.. literalinclude:: ../../data/bitmap/cubicalcomplexdoc.txt + +.. centered:: ../../data/bitmap/cubicalcomplexdoc.txt + +To indicate periodic boundary conditions in a given direction, then number of +top dimensional cells in this direction have to be multiplied by -1. For +instance: + +.. literalinclude:: ../../data/bitmap/periodiccubicalcomplexdoc.txt + +.. centered:: ../../data/bitmap/periodiccubicalcomplexdoc.txt + + +Indicate that we have imposed periodic boundary conditions in the direction x, +but not in the direction y. + +Other sample files can be found in the `data/bitmap` folder. diff --git a/src/cython/doc/index.rst b/src/cython/doc/index.rst index 3945d72a..15cbe267 100644 --- a/src/cython/doc/index.rst +++ b/src/cython/doc/index.rst @@ -34,32 +34,37 @@ Data structures Alpha complex ============= -.. include:: alpha_complex_sum.rst +.. include:: alpha_complex_sum.inc + +Cover complexes +=============== + +.. include:: nerve_gic_complex_sum.rst Cubical complex =============== -.. include:: cubical_complex_sum.rst +.. include:: cubical_complex_sum.inc Rips complex ============ -.. include:: rips_complex_sum.rst +.. include:: rips_complex_sum.inc Simplex tree ============ -.. include:: simplex_tree_sum.rst +.. include:: simplex_tree_sum.inc Tangential complex ================== -.. include:: tangential_complex_sum.rst +.. include:: tangential_complex_sum.inc Witness complex =============== -.. include:: witness_complex_sum.rst +.. include:: witness_complex_sum.inc Toolbox @@ -68,17 +73,17 @@ Toolbox Bottleneck distance =================== -.. include:: bottleneck_distance_sum.rst +.. include:: bottleneck_distance_sum.inc Persistence cohomology ====================== -.. include:: persistent_cohomology_sum.rst +.. include:: persistent_cohomology_sum.inc Persistence graphical tools =========================== -.. include:: persistence_graphical_tools_sum.rst +.. include:: persistence_graphical_tools_sum.inc Bibliography ************ diff --git a/src/cython/doc/installation.rst b/src/cython/doc/installation.rst index c182f176..ef2f7af2 100644 --- a/src/cython/doc/installation.rst +++ b/src/cython/doc/installation.rst @@ -1,12 +1,16 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Installation ############ Compiling ********* - -The library uses c++11 and requires `Boost <http://www.boost.org/>`_ with -version 1.48.0 or more recent. It is a multi-platform library and compiles on -Linux, Mac OSX and Visual Studio 2015. +The library uses c++11 and requires `Boost <https://www.boost.org/>`_ ≥ 1.48.0 +and `CMake <https://www.cmake.org/>`_ ≥ 3.1. +It is a multi-platform library and compiles on Linux, Mac OSX and Visual +Studio 2015. It also requires cmake to generate makefiles, and cython to compile the library. @@ -43,6 +47,61 @@ following command in a terminal: export PYTHONPATH='$PYTHONPATH:/path-to-gudhi/build/cython' ctest -R py_test +Debugging issues +================ + +If tests fail, please check your PYTHONPATH and try to :code:`import gudhi` +and check the errors. +The problem can come from a third-party library bad link or installation. + +If :code:`import gudhi` succeeds, please have a look to debug informations: + +.. code-block:: python + + import gudhi + print(gudhi.__debug_info__) + +You shall have something like: + +.. code-block:: none + + Python version 2.7.15 + Cython version 0.26.1 + Eigen3 version 3.1.1 + Installed modules are: off_reader;simplex_tree;rips_complex;cubical_complex;periodic_cubical_complex; + persistence_graphical_tools;reader_utils;witness_complex;strong_witness_complex;alpha_complex; + euclidean_witness_complex;euclidean_strong_witness_complex; + Missing modules are: bottleneck_distance;nerve_gic;subsampling;tangential_complex;persistence_graphical_tools; + CGAL version 4.7.1000 + GMP_LIBRARIES = /usr/lib/x86_64-linux-gnu/libgmp.so + GMPXX_LIBRARIES = /usr/lib/x86_64-linux-gnu/libgmpxx.so + TBB version 9107 found and used + +Here, you can see that bottleneck_distance, nerve_gic, subsampling and +tangential_complex are missing because of the CGAL version. +persistence_graphical_tools is not available as numpy and matplotlib are not +available. +Unitary tests cannot be run as pytest is missing. + +A complete configuration would be : + +.. code-block:: none + + Python version 3.6.5 + Cython version 0.28.2 + Pytest version 3.3.2 + Matplotlib version 2.2.2 + Numpy version 1.14.5 + Eigen3 version 3.3.4 + Installed modules are: off_reader;simplex_tree;rips_complex;cubical_complex;periodic_cubical_complex; + persistence_graphical_tools;reader_utils;witness_complex;strong_witness_complex;persistence_graphical_tools; + bottleneck_distance;nerve_gic;subsampling;tangential_complex;alpha_complex;euclidean_witness_complex; + euclidean_strong_witness_complex; + CGAL header only version 4.11.0 + GMP_LIBRARIES = /usr/lib/x86_64-linux-gnu/libgmp.so + GMPXX_LIBRARIES = /usr/lib/x86_64-linux-gnu/libgmpxx.so + TBB version 9107 found and used + Documentation ============= @@ -136,7 +195,7 @@ The following examples require the `Matplotlib <http://matplotlib.org>`_: * :download:`euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py>` * :download:`euclidean_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_witness_complex_diagram_persistence_from_off_file_example.py>` -Numpy +NumPy ===== The :doc:`persistence graphical tools </persistence_graphical_tools_user>` @@ -157,6 +216,13 @@ The following examples require the `NumPy <http://numpy.org>`_: * :download:`euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py>` * :download:`euclidean_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_witness_complex_diagram_persistence_from_off_file_example.py>` +SciPy +===== + +The :doc:`persistence graphical tools </persistence_graphical_tools_user>` +module requires `SciPy <http://scipy.org>`_, a Python-based ecosystem of +open-source software for mathematics, science, and engineering. + Threading Building Blocks ========================= diff --git a/src/cython/doc/nerve_gic_complex_ref.rst b/src/cython/doc/nerve_gic_complex_ref.rst new file mode 100644 index 00000000..e24e01fc --- /dev/null +++ b/src/cython/doc/nerve_gic_complex_ref.rst @@ -0,0 +1,10 @@ +================================ +Cover complexes reference manual +================================ + +.. autoclass:: gudhi.CoverComplex + :members: + :undoc-members: + :show-inheritance: + + .. automethod:: gudhi.CoverComplex.__init__ diff --git a/src/cython/doc/nerve_gic_complex_sum.rst b/src/cython/doc/nerve_gic_complex_sum.rst new file mode 100644 index 00000000..523c119f --- /dev/null +++ b/src/cython/doc/nerve_gic_complex_sum.rst @@ -0,0 +1,15 @@ +================================================================= =================================== =================================== +:Author: Mathieu Carrière :Introduced in: GUDHI 2.3.0 :Copyright: GPL v3 +:Requires: CGAL :math:`\geq` 4.8.1 +================================================================= =================================== =================================== + ++----------------------------------------------------------------+------------------------------------------------------------------------+ +| .. figure:: | Nerves and Graph Induced Complexes are cover complexes, i.e. | +| ../../doc/Nerve_GIC/gicvisu.jpg | simplicial complexes that provably contain topological information | +| :alt: Graph Induced Complex of a point cloud. | about the input data. They can be computed with a cover of the data, | +| :figclass: align-center | that comes i.e. from the preimage of a family of intervals covering | +| | the image of a scalar-valued function defined on the data. | +| Graph Induced Complex of a point cloud. | | ++----------------------------------------------------------------+------------------------------------------------------------------------+ +| :doc:`nerve_gic_complex_user` | :doc:`nerve_gic_complex_ref` | ++----------------------------------------------------------------+------------------------------------------------------------------------+ diff --git a/src/cython/doc/nerve_gic_complex_user.rst b/src/cython/doc/nerve_gic_complex_user.rst new file mode 100644 index 00000000..d774827e --- /dev/null +++ b/src/cython/doc/nerve_gic_complex_user.rst @@ -0,0 +1,312 @@ +Cover complexes user manual +=========================== +Definition +---------- + +.. include:: nerve_gic_complex_sum.rst + +Visualizations of the simplicial complexes can be done with either +neato (from `graphviz <http://www.graphviz.org/>`_), +`geomview <http://www.geomview.org/>`_, +`KeplerMapper <https://github.com/MLWave/kepler-mapper>`_. +Input point clouds are assumed to be +`OFF files <http://www.geomview.org/docs/html/OFF.html>`_. + +Covers +------ + +Nerves and Graph Induced Complexes require a cover C of the input point cloud P, +that is a set of subsets of P whose union is P itself. +Very often, this cover is obtained from the preimage of a family of intervals covering +the image of some scalar-valued function f defined on P. This family is parameterized +by its resolution, which can be either the number or the length of the intervals, +and its gain, which is the overlap percentage between consecutive intervals (ordered by their first values). + +Nerves +------ + +Nerve definition +^^^^^^^^^^^^^^^^ + +Assume you are given a cover C of your point cloud P. Then, the Nerve of this cover +is the simplicial complex that has one k-simplex per k-fold intersection of cover elements. +See also `Wikipedia <https://en.wikipedia.org/wiki/Nerve_of_a_covering>`_. + +.. figure:: + ../../doc/Nerve_GIC/nerve.png + :figclass: align-center + :alt: Nerve of a double torus + + Nerve of a double torus + +Example +^^^^^^^ + +This example builds the Nerve of a point cloud sampled on a 3D human shape (human.off). +The cover C comes from the preimages of intervals (10 intervals with gain 0.3) +covering the height function (coordinate 2), +which are then refined into their connected components using the triangulation of the .OFF file. + +.. testcode:: + + import gudhi + nerve_complex = gudhi.CoverComplex() + nerve_complex.set_verbose(True) + + if (nerve_complex.read_point_cloud(gudhi.__root_source_dir__ + \ + '/data/points/human.off')): + nerve_complex.set_type('Nerve') + nerve_complex.set_color_from_coordinate(2) + nerve_complex.set_function_from_coordinate(2) + nerve_complex.set_graph_from_OFF() + nerve_complex.set_resolution_with_interval_number(10) + nerve_complex.set_gain(0.3) + nerve_complex.set_cover_from_function() + nerve_complex.find_simplices() + nerve_complex.write_info() + simplex_tree = nerve_complex.create_simplex_tree() + nerve_complex.compute_PD() + result_str = 'Nerve is of dimension ' + repr(simplex_tree.dimension()) + ' - ' + \ + repr(simplex_tree.num_simplices()) + ' simplices - ' + \ + repr(simplex_tree.num_vertices()) + ' vertices.' + print(result_str) + for filtered_value in simplex_tree.get_filtration(): + print(filtered_value[0]) + +the program output is: + +.. code-block:: none + + Min function value = -0.979672 and Max function value = 0.816414 + Interval 0 = [-0.979672, -0.761576] + Interval 1 = [-0.838551, -0.581967] + Interval 2 = [-0.658942, -0.402359] + Interval 3 = [-0.479334, -0.22275] + Interval 4 = [-0.299725, -0.0431414] + Interval 5 = [-0.120117, 0.136467] + Interval 6 = [0.059492, 0.316076] + Interval 7 = [0.239101, 0.495684] + Interval 8 = [0.418709, 0.675293] + Interval 9 = [0.598318, 0.816414] + Computing preimages... + Computing connected components... + 5 interval(s) in dimension 0: + [-0.909111, 0.0081753] + [-0.171433, 0.367393] + [-0.171433, 0.367393] + [-0.909111, 0.745853] + 0 interval(s) in dimension 1: + +.. testoutput:: + + Nerve is of dimension 1 - 41 simplices - 21 vertices. + [0] + [1] + [4] + [1, 4] + [2] + [0, 2] + [8] + [2, 8] + [5] + [4, 5] + [9] + [8, 9] + [13] + [5, 13] + [14] + [9, 14] + [19] + [13, 19] + [25] + [32] + [20] + [20, 32] + [33] + [25, 33] + [26] + [14, 26] + [19, 26] + [42] + [26, 42] + [34] + [33, 34] + [27] + [20, 27] + [35] + [27, 35] + [34, 35] + [35, 42] + [44] + [35, 44] + [54] + [44, 54] + + +The program also writes a file ../../data/points/human.off_sc.txt. The first +three lines in this file are the location of the input point cloud and the +function used to compute the cover. +The fourth line contains the number of vertices nv and edges ne of the Nerve. +The next nv lines represent the vertices. Each line contains the vertex ID, +the number of data points it contains, and their average color function value. +Finally, the next ne lines represent the edges, characterized by the ID of +their vertices. + +Using KeplerMapper, one can obtain the following visualization: + +.. figure:: + ../../doc/Nerve_GIC/nervevisu.jpg + :figclass: align-center + :alt: Visualization with KeplerMapper + + Visualization with KeplerMapper + +Graph Induced Complexes (GIC) +----------------------------- + +GIC definition +^^^^^^^^^^^^^^ + +Again, assume you are given a cover C of your point cloud P. Moreover, assume +you are also given a graph G built on top of P. Then, for any clique in G +whose nodes all belong to different elements of C, the GIC includes a +corresponding simplex, whose dimension is the number of nodes in the clique +minus one. +See :cite:`Dey13` for more details. + +.. figure:: + ../../doc/Nerve_GIC/GIC.jpg + :figclass: align-center + :alt: GIC of a point cloud + + GIC of a point cloud + +Example with cover from Voronoï +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This example builds the GIC of a point cloud sampled on a 3D human shape +(human.off). +We randomly subsampled 100 points in the point cloud, which act as seeds of +a geodesic Voronoï diagram. Each cell of the diagram is then an element of C. +The graph G (used to compute both the geodesics for Voronoï and the GIC) +comes from the triangulation of the human shape. Note that the resulting +simplicial complex is in dimension 3 in this example. + +.. testcode:: + + import gudhi + nerve_complex = gudhi.CoverComplex() + + if (nerve_complex.read_point_cloud(gudhi.__root_source_dir__ + \ + '/data/points/human.off')): + nerve_complex.set_type('GIC') + nerve_complex.set_color_from_coordinate() + nerve_complex.set_graph_from_OFF() + nerve_complex.set_cover_from_Voronoi(700) + nerve_complex.find_simplices() + nerve_complex.plot_off() + +the program outputs SC.off. Using e.g. + +.. code-block:: none + + geomview ../../data/points/human.off_sc.off + +one can obtain the following visualization: + +.. figure:: + ../../doc/Nerve_GIC/gicvoronoivisu.jpg + :figclass: align-center + :alt: Visualization with Geomview + + Visualization with Geomview + +Functional GIC +^^^^^^^^^^^^^^ + +If one restricts to the cliques in G whose nodes all belong to preimages of +consecutive intervals (assuming the cover of the height function is minimal, +i.e. no more than two intervals can intersect at a time), the GIC is of +dimension one, i.e. a graph. +We call this graph the functional GIC. See :cite:`Carriere16` for more details. + +Example +^^^^^^^ + +Functional GIC comes with automatic selection of the Rips threshold, +the resolution and the gain of the function cover. See :cite:`Carriere17c` for +more details. In this example, we compute the functional GIC of a Klein bottle +embedded in R^5, where the graph G comes from a Rips complex with automatic +threshold, and the cover C comes from the preimages of intervals covering the +first coordinate, with automatic resolution and gain. Note that automatic +threshold, resolution and gain can be computed as well for the Nerve. + +.. testcode:: + + import gudhi + nerve_complex = gudhi.CoverComplex() + + if (nerve_complex.read_point_cloud(gudhi.__root_source_dir__ + \ + '/data/points/KleinBottle5D.off')): + nerve_complex.set_type('GIC') + nerve_complex.set_color_from_coordinate(0) + nerve_complex.set_function_from_coordinate(0) + nerve_complex.set_graph_from_automatic_rips() + nerve_complex.set_automatic_resolution() + nerve_complex.set_gain() + nerve_complex.set_cover_from_function() + nerve_complex.find_simplices() + nerve_complex.plot_dot() + +the program outputs SC.dot. Using e.g. + +.. code-block:: none + + neato ../../data/points/KleinBottle5D.off_sc.dot -Tpdf -o ../../data/points/KleinBottle5D.off_sc.pdf + +one can obtain the following visualization: + +.. figure:: + ../../doc/Nerve_GIC/coordGICvisu2.jpg + :figclass: align-center + :alt: Visualization with neato + + Visualization with neato + +where nodes are colored by the filter function values and, for each node, the +first number is its ID and the second is the number of data points that its +contain. + +We also provide an example on a set of 72 pictures taken around the same object +(lucky_cat.off). +The function is now the first eigenfunction given by PCA, whose values are +written in a file (lucky_cat_PCA1). Threshold, resolution and gain are +automatically selected as before. + +.. testcode:: + + import gudhi + nerve_complex = gudhi.CoverComplex() + + if (nerve_complex.read_point_cloud(gudhi.__root_source_dir__ + \ + '/data/points/COIL_database/lucky_cat.off')): + nerve_complex.set_type('GIC') + pca_file = gudhi.__root_source_dir__ + \ + '/data/points/COIL_database/lucky_cat_PCA1' + nerve_complex.set_color_from_file(pca_file) + nerve_complex.set_function_from_file(pca_file) + nerve_complex.set_graph_from_automatic_rips() + nerve_complex.set_automatic_resolution() + nerve_complex.set_gain() + nerve_complex.set_cover_from_function() + nerve_complex.find_simplices() + nerve_complex.plot_dot() + +the program outputs again SC.dot which gives the following visualization after using neato: + +.. figure:: + ../../doc/Nerve_GIC/funcGICvisu.jpg + :figclass: align-center + :alt: Visualization with neato + + Visualization with neato diff --git a/src/cython/doc/periodic_cubical_complex_ref.rst b/src/cython/doc/periodic_cubical_complex_ref.rst index c6190a1b..4b831647 100644 --- a/src/cython/doc/periodic_cubical_complex_ref.rst +++ b/src/cython/doc/periodic_cubical_complex_ref.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Periodic cubical complex reference manual ######################################### diff --git a/src/cython/doc/persistence_graphical_tools_ref.rst b/src/cython/doc/persistence_graphical_tools_ref.rst index 27c2f68a..54aff4bc 100644 --- a/src/cython/doc/persistence_graphical_tools_ref.rst +++ b/src/cython/doc/persistence_graphical_tools_ref.rst @@ -1,8 +1,12 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + ============================================ Persistence graphical tools reference manual ============================================ .. autofunction:: gudhi.__min_birth_max_death -.. autofunction:: gudhi.show_palette_values .. autofunction:: gudhi.plot_persistence_barcode .. autofunction:: gudhi.plot_persistence_diagram +.. autofunction:: gudhi.plot_persistence_density diff --git a/src/cython/doc/persistence_graphical_tools_sum.rst b/src/cython/doc/persistence_graphical_tools_sum.inc index d602daa7..5577cf99 100644 --- a/src/cython/doc/persistence_graphical_tools_sum.rst +++ b/src/cython/doc/persistence_graphical_tools_sum.inc @@ -1,11 +1,11 @@ ================================================================= =================================== =================================== :Author: Vincent Rouvreau :Introduced in: GUDHI 2.0.0 :Copyright: GPL v3 -:Requires: Matplotlib Numpy +:Requires: matplotlib numpy scipy ================================================================= =================================== =================================== +-----------------------------------------------------------------+-----------------------------------------------------------------------+ | .. figure:: | These graphical tools comes on top of persistence results and allows | -| img/graphical_tools_representation.png | the user to build easily barcode and persistence diagram. | +| img/graphical_tools_representation.png | the user to build easily persistence barcode, diagram or density. | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------------+ | :doc:`persistence_graphical_tools_user` | :doc:`persistence_graphical_tools_ref` | diff --git a/src/cython/doc/persistence_graphical_tools_user.rst b/src/cython/doc/persistence_graphical_tools_user.rst index 9033331f..b2124fdd 100644 --- a/src/cython/doc/persistence_graphical_tools_user.rst +++ b/src/cython/doc/persistence_graphical_tools_user.rst @@ -1,77 +1,73 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Persistence graphical tools user manual ======================================= Definition ---------- -.. include:: persistence_graphical_tools_sum.rst +.. include:: persistence_graphical_tools_sum.inc -Show palette values -------------------- +Show persistence as a barcode +----------------------------- -This function is useful to show the color palette values of dimension: +.. note:: + this function requires matplotlib and numpy to be available +This function can display the persistence result as a barcode: -.. testcode:: +.. plot:: + :include-source: import gudhi - plt = gudhi.show_palette_values(alpha=1.0) - plt.show() -.. plot:: + off_file = gudhi.__root_source_dir__ + '/data/points/tore3D_300.off' + point_cloud = gudhi.read_off(off_file=off_file) - import gudhi - plt = gudhi.show_palette_values(alpha=1.0) - plt.show() + rips_complex = gudhi.RipsComplex(points=point_cloud, max_edge_length=0.7) + simplex_tree = rips_complex.create_simplex_tree(max_dimension=3) + diag = simplex_tree.persistence(min_persistence=0.4) -Show persistence as a barcode ------------------------------ + plot = gudhi.plot_persistence_barcode(diag) + plot.show() -This function can display the persistence result as a barcode: +Show persistence as a diagram +----------------------------- -.. testcode:: +.. note:: + this function requires matplotlib and numpy to be available - import gudhi - - periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file=gudhi.__root_source_dir__ + \ - '/data/bitmap/3d_torus.txt') - diag = periodic_cc.persistence() - plt = gudhi.plot_persistence_barcode(diag) - plt.show() +This function can display the persistence result as a diagram: .. plot:: + :include-source: import gudhi - periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file=gudhi.__root_source_dir__ + \ - '/data/bitmap/3d_torus.txt') - diag = periodic_cc.persistence() - print("diag = ", diag) - plt = gudhi.plot_persistence_barcode(diag) + # 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' + plt = gudhi.plot_persistence_diagram(persistence_file=persistence_file, + legend=True) plt.show() -Show persistence as a diagram ------------------------------ - -This function can display the persistence result as a diagram: +Persistence density +------------------- -.. testcode:: +.. note:: + this function requires matplotlib, numpy and scipy to be available - import gudhi - - rips_complex = gudhi.RipsComplex(off_file=gudhi.__root_source_dir__ + \ - '/data/points/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() +If you want more information on a specific dimension, for instance: .. plot:: + :include-source: import gudhi - rips_complex = gudhi.RipsComplex(off_file=gudhi.__root_source_dir__ + \ - '/data/points/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) + # 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' + plt = gudhi.plot_persistence_density(persistence_file=persistence_file, + max_intervals=0, dimension=1, legend=True) plt.show() diff --git a/src/cython/doc/persistent_cohomology_sum.rst b/src/cython/doc/persistent_cohomology_sum.inc index a26df1dc..a26df1dc 100644 --- a/src/cython/doc/persistent_cohomology_sum.rst +++ b/src/cython/doc/persistent_cohomology_sum.inc diff --git a/src/cython/doc/persistent_cohomology_user.rst b/src/cython/doc/persistent_cohomology_user.rst index bf90c163..ce7fc685 100644 --- a/src/cython/doc/persistent_cohomology_user.rst +++ b/src/cython/doc/persistent_cohomology_user.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Persistent cohomology user manual ================================= Definition diff --git a/src/cython/doc/pyplots/barcode_persistence.py b/src/cython/doc/pyplots/barcode_persistence.py deleted file mode 100755 index de33d506..00000000 --- a/src/cython/doc/pyplots/barcode_persistence.py +++ /dev/null @@ -1,7 +0,0 @@ -import gudhi - -periodic_cc = gudhi.PeriodicCubicalComplex(perseus_file=gudhi.__root_source_dir__ + \ - '/data/bitmap/3d_torus.txt') -diag = periodic_cc.persistence() -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 deleted file mode 100755 index c2fbf801..00000000 --- a/src/cython/doc/pyplots/diagram_persistence.py +++ /dev/null @@ -1,8 +0,0 @@ -import gudhi - -rips_complex = gudhi.RipsComplex(off_file=gudhi.__root_source_dir__ + \ - '/data/points/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 deleted file mode 100755 index fdf9645f..00000000 --- a/src/cython/doc/pyplots/show_palette_values.py +++ /dev/null @@ -1,3 +0,0 @@ -import gudhi -plt = gudhi.show_palette_values(alpha=1.0) -plt.show() diff --git a/src/cython/doc/python3-sphinx-build.py b/src/cython/doc/python3-sphinx-build.py index 44b94169..84d158cf 100755 --- a/src/cython/doc/python3-sphinx-build.py +++ b/src/cython/doc/python3-sphinx-build.py @@ -1,4 +1,4 @@ -#!/usr/bin/python3 +#!/usr/bin/env python3 """ Emulate sphinx-build for python3 diff --git a/src/cython/doc/reader_utils_ref.rst b/src/cython/doc/reader_utils_ref.rst index 9c1ea6fc..f3ecebad 100644 --- a/src/cython/doc/reader_utils_ref.rst +++ b/src/cython/doc/reader_utils_ref.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + ============================= Reader utils reference manual ============================= diff --git a/src/cython/doc/rips_complex_ref.rst b/src/cython/doc/rips_complex_ref.rst index b17dc4e0..22b5616c 100644 --- a/src/cython/doc/rips_complex_ref.rst +++ b/src/cython/doc/rips_complex_ref.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + ============================= Rips complex reference manual ============================= diff --git a/src/cython/doc/rips_complex_sum.rst b/src/cython/doc/rips_complex_sum.inc index 5616bfa9..5616bfa9 100644 --- a/src/cython/doc/rips_complex_sum.rst +++ b/src/cython/doc/rips_complex_sum.inc diff --git a/src/cython/doc/rips_complex_user.rst b/src/cython/doc/rips_complex_user.rst index 96ba9944..a8c06cf9 100644 --- a/src/cython/doc/rips_complex_user.rst +++ b/src/cython/doc/rips_complex_user.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Rips complex user manual ========================= Definition @@ -101,8 +105,8 @@ Finally, it is asked to display information about the Rips complex. .. testcode:: import gudhi - rips_complex = gudhi.RipsComplex(off_file=gudhi.__root_source_dir__ + \ - '/data/points/alphacomplexdoc.off', max_edge_length=12.0) + point_cloud = gudhi.read_off(off_file=gudhi.__root_source_dir__ + '/data/points/alphacomplexdoc.off') + rips_complex = gudhi.RipsComplex(points=point_cloud, max_edge_length=12.0) simplex_tree = rips_complex.create_simplex_tree(max_dimension=1) result_str = 'Rips complex is of dimension ' + repr(simplex_tree.dimension()) + ' - ' + \ repr(simplex_tree.num_simplices()) + ' simplices - ' + \ @@ -197,7 +201,7 @@ Example from csv file ^^^^^^^^^^^^^^^^^^^^^ This example builds the :doc:`Rips_complex <rips_complex_ref>` from the given -points in an OFF file, and max_edge_length value. +distance matrix in a csv file, and max_edge_length value. Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it. Finally, it is asked to display information about the Rips complex. @@ -206,8 +210,9 @@ Finally, it is asked to display information about the Rips complex. .. testcode:: import gudhi - rips_complex = gudhi.RipsComplex(csv_file=gudhi.__root_source_dir__ + \ - '/data/distance_matrix/full_square_distance_matrix.csv', max_edge_length=12.0) + distance_matrix = gudhi.read_lower_triangular_matrix_from_csv_file(csv_file=gudhi.__root_source_dir__ + \ + '/data/distance_matrix/full_square_distance_matrix.csv') + rips_complex = gudhi.RipsComplex(distance_matrix=distance_matrix, max_edge_length=12.0) simplex_tree = rips_complex.create_simplex_tree(max_dimension=1) result_str = 'Rips complex is of dimension ' + repr(simplex_tree.dimension()) + ' - ' + \ repr(simplex_tree.num_simplices()) + ' simplices - ' + \ @@ -240,3 +245,72 @@ the program output is: [0, 3] -> 9.43 [4, 6] -> 9.49 [3, 6] -> 11.00 + +Correlation matrix +------------------ + +Example from a correlation matrix +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Analogously to the case of distance matrix, Rips complexes can be also constructed based on correlation matrix. +Given a correlation matrix M, comportment-wise 1-M is a distance matrix. +This example builds the one skeleton graph from the given corelation matrix and threshold value. +Then it creates a :doc:`Simplex_tree <simplex_tree_ref>` with it. + +Finally, it is asked to display information about the simplicial complex. + +.. testcode:: + + import gudhi + import numpy as np + + # User defined correlation matrix is: + # |1 0.06 0.23 0.01 0.89| + # |0.06 1 0.74 0.01 0.61| + # |0.23 0.74 1 0.72 0.03| + # |0.01 0.01 0.72 1 0.7 | + # |0.89 0.61 0.03 0.7 1 | + correlation_matrix=np.array([[1., 0.06, 0.23, 0.01, 0.89], + [0.06, 1., 0.74, 0.01, 0.61], + [0.23, 0.74, 1., 0.72, 0.03], + [0.01, 0.01, 0.72, 1., 0.7], + [0.89, 0.61, 0.03, 0.7, 1.]], float) + + distance_matrix = np.ones((correlation_matrix.shape),float) - correlation_matrix + rips_complex = gudhi.RipsComplex(distance_matrix=distance_matrix, max_edge_length=1.0) + + simplex_tree = rips_complex.create_simplex_tree(max_dimension=1) + result_str = 'Rips complex is of dimension ' + repr(simplex_tree.dimension()) + ' - ' + \ + repr(simplex_tree.num_simplices()) + ' simplices - ' + \ + repr(simplex_tree.num_vertices()) + ' vertices.' + print(result_str) + fmt = '%s -> %.2f' + for filtered_value in simplex_tree.get_filtration(): + print(fmt % tuple(filtered_value)) + +When launching (Rips maximal distance between 2 points is 12.0, is expanded +until dimension 1 - one skeleton graph in other words), the output is: + +.. testoutput:: + + Rips complex is of dimension 1 - 15 simplices - 5 vertices. + [0] -> 0.00 + [1] -> 0.00 + [2] -> 0.00 + [3] -> 0.00 + [4] -> 0.00 + [0, 4] -> 0.11 + [1, 2] -> 0.26 + [2, 3] -> 0.28 + [3, 4] -> 0.30 + [1, 4] -> 0.39 + [0, 2] -> 0.77 + [0, 1] -> 0.94 + [2, 4] -> 0.97 + [0, 3] -> 0.99 + [1, 3] -> 0.99 + +.. note:: + As persistence diagrams points will be under the diagonal, + bottleneck distance and persistence graphical tool will not work properly, + this is a known issue. diff --git a/src/cython/doc/simplex_tree_ref.rst b/src/cython/doc/simplex_tree_ref.rst index 6d196843..9eb8c199 100644 --- a/src/cython/doc/simplex_tree_ref.rst +++ b/src/cython/doc/simplex_tree_ref.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + ============================= Simplex tree reference manual ============================= diff --git a/src/cython/doc/simplex_tree_sum.rst b/src/cython/doc/simplex_tree_sum.inc index fb0e54c1..fb0e54c1 100644 --- a/src/cython/doc/simplex_tree_sum.rst +++ b/src/cython/doc/simplex_tree_sum.inc diff --git a/src/cython/doc/simplex_tree_user.rst b/src/cython/doc/simplex_tree_user.rst index 4b1dde19..aebeb29f 100644 --- a/src/cython/doc/simplex_tree_user.rst +++ b/src/cython/doc/simplex_tree_user.rst @@ -1,9 +1,13 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Simplex tree user manual ======================== Definition ---------- -.. include:: simplex_tree_sum.rst +.. include:: simplex_tree_sum.inc A simplicial complex :math:`\mathbf{K}` on a set of vertices :math:`V = \{1, \cdots ,|V|\}` is a collection of simplices :math:`\{\sigma\}`, :math:`\sigma \subseteq V` such that diff --git a/src/cython/doc/strong_witness_complex_ref.rst b/src/cython/doc/strong_witness_complex_ref.rst index 4ed4fe46..d624d711 100644 --- a/src/cython/doc/strong_witness_complex_ref.rst +++ b/src/cython/doc/strong_witness_complex_ref.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + ======================================= Strong witness complex reference manual ======================================= diff --git a/src/cython/doc/tangential_complex_ref.rst b/src/cython/doc/tangential_complex_ref.rst index 35589475..cdfda082 100644 --- a/src/cython/doc/tangential_complex_ref.rst +++ b/src/cython/doc/tangential_complex_ref.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + =================================== Tangential complex reference manual =================================== diff --git a/src/cython/doc/tangential_complex_sum.rst b/src/cython/doc/tangential_complex_sum.inc index 72b4d7ba..72b4d7ba 100644 --- a/src/cython/doc/tangential_complex_sum.rst +++ b/src/cython/doc/tangential_complex_sum.inc diff --git a/src/cython/doc/tangential_complex_user.rst b/src/cython/doc/tangential_complex_user.rst index efa6d7ce..5ce69e86 100644 --- a/src/cython/doc/tangential_complex_user.rst +++ b/src/cython/doc/tangential_complex_user.rst @@ -1,6 +1,10 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Tangential complex user manual ============================== -.. include:: tangential_complex_sum.rst +.. include:: tangential_complex_sum.inc Definition ---------- @@ -122,8 +126,8 @@ This example builds the Tangential complex of point set read in an OFF file. .. testcode:: import gudhi - tc = gudhi.TangentialComplex(off_file=gudhi.__root_source_dir__ + \ - '/data/points/alphacomplexdoc.off') + tc = gudhi.TangentialComplex(intrisic_dim = 1, + off_file=gudhi.__root_source_dir__ + '/data/points/alphacomplexdoc.off') result_str = 'Tangential contains ' + repr(tc.num_simplices()) + \ ' simplices - ' + repr(tc.num_vertices()) + ' vertices.' print(result_str) @@ -169,7 +173,8 @@ simplices. .. testcode:: import gudhi - tc = gudhi.TangentialComplex(points=[[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [1.0, 1.0]]) + tc = gudhi.TangentialComplex(intrisic_dim = 1, + points=[[0.0, 0.0], [1.0, 0.0], [0.0, 1.0], [1.0, 1.0]]) result_str = 'Tangential contains ' + repr(tc.num_vertices()) + ' vertices.' print(result_str) diff --git a/src/cython/doc/todos.rst b/src/cython/doc/todos.rst index 78972a4c..ca274ced 100644 --- a/src/cython/doc/todos.rst +++ b/src/cython/doc/todos.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + ========== To be done ========== diff --git a/src/cython/doc/witness_complex_ref.rst b/src/cython/doc/witness_complex_ref.rst index c78760cb..9987d3fd 100644 --- a/src/cython/doc/witness_complex_ref.rst +++ b/src/cython/doc/witness_complex_ref.rst @@ -1,3 +1,7 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + ================================ Witness complex reference manual ================================ diff --git a/src/cython/doc/witness_complex_sum.rst b/src/cython/doc/witness_complex_sum.inc index a8a126a0..a8a126a0 100644 --- a/src/cython/doc/witness_complex_sum.rst +++ b/src/cython/doc/witness_complex_sum.inc diff --git a/src/cython/doc/witness_complex_user.rst b/src/cython/doc/witness_complex_user.rst index 29413269..40e94134 100644 --- a/src/cython/doc/witness_complex_user.rst +++ b/src/cython/doc/witness_complex_user.rst @@ -1,7 +1,11 @@ +:orphan: + +.. To get rid of WARNING: document isn't included in any toctree + Witness complex user manual =========================== -.. include:: witness_complex_sum.rst +.. include:: witness_complex_sum.inc Definitions ----------- @@ -121,7 +125,7 @@ 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>` +* :download:`euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py <../example/euclidean_strong_witness_complex_diagram_persistence_from_off_file_example.py>` Bibliography ============ |