Cubical complex reference manual#

class gudhi.CubicalComplex#

Bases: `object`

The CubicalComplex is an example of a structured complex useful in computational mathematics (specially rigorous numerics) and image analysis.

__init__()#

CubicalComplex constructor from the filtration values of either the top-dimensional cells, or the vertices.

Note that in case top_dimensional_cells or vertices is passed as a flat array, its true shape can be given in dimensions, which is considered using the fortran ordering (column-major order). However, we recommend passing directly an array of the right shape.

Parameters:

top_dimensional_cells (anything convertible to a numpy.ndarray) – A multidimensional array of top dimensional cells filtration values.

Or

Parameters:

vertices (anything convertible to a numpy.ndarray) – A multidimensional array of vertices filtration values.

Or

Parameters:
• top_dimensional_cells (Iterable[float]) – Filtration values of the top-dimensional cells.

• dimensions (Iterable[int]) – Shape of the array of top dimensional cells (Fortran order).

Or

Parameters:
• vertices (Iterable[float]) – Filtration values of the vertices.

• dimensions (Iterable[int]) – Shape of the array of vertices (Fortran order).

Or

Parameters:

perseus_file (str) – A Perseus-style file name, giving the filtration values of top-dimensional cells.

__new__(**kwargs)#
all_cells()#

Array with the filtration values of all the cells of the complex. Modifying the values is strongly discouraged.

Returns:

numpy.ndarray

betti_numbers()#

This function returns the Betti numbers of the complex.

Returns:

list of int – The Betti numbers ([B0, B1, …, Bn]).

Note:

betti_numbers function requires `compute_persistence()` function to be launched first.

Note:

betti_numbers function always returns [1, 0, 0, …] as infinity filtration cubes are not removed from the complex.

cofaces_of_persistence_pairs()#

A persistence interval is described by a pair of cells, one that creates the feature and one that kills it. The filtration values of those 2 cells give coordinates for a point in a persistence diagram, or a bar in a barcode. Structurally, in the cubical complexes provided here, the filtration value of any cell is the minimum of the filtration values of the maximal cells that contain it. Connecting persistence diagram coordinates to the corresponding value in the input (i.e. the filtration values of the top-dimensional cells) is useful for differentiation purposes.

Since the cubical complex construction from vertices is different from the top dimensional one, the former may not have an equivalent with the second construction, and vice versa. Therefore, using `cofaces_of_persistence_pairs()` with a cubical complex constructed from vertices can lead to an undefined behavior.

This function returns a list of pairs of top-dimensional cells corresponding to the persistence birth and death cells of the filtration. The cells are represented by their indices in the input list of top-dimensional cells (and not their indices in the internal datastructure that includes non-maximal cells). Note that when two adjacent top-dimensional cells have the same filtration value, we arbitrarily return one of the two when calling the function on one of their common faces.

Returns:

The top-dimensional cells/cofaces of the positive and negative cells, together with the corresponding homological dimension, in two lists of numpy arrays of integers. The first list contains the regular persistence pairs, grouped by dimension. It contains numpy arrays of shape (number_of_persistence_points, 2). The indices of the arrays in the list correspond to the homological dimensions, and the integers of each row in each array correspond to: (index of positive top-dimensional cell, index of negative top-dimensional cell). The second list contains the essential features, grouped by dimension. It contains numpy arrays of shape (number_of_persistence_points,). The indices of the arrays in the list correspond to the homological dimensions, and the integers of each row in each array correspond to: (index of positive top-dimensional cell).

compute_persistence()#

This function computes the persistence of the complex, so it can be accessed through `persistent_betti_numbers()`, `persistence_intervals_in_dimension()`, etc. This function is equivalent to `persistence()` when you do not want the list `persistence()` returns.

Parameters:
• homology_coeff_field (int.) – The homology coefficient field. Must be a prime number. Default value is 11. Max is 46337.

• min_persistence (float.) – The minimum persistence value to take into account (strictly greater than min_persistence). Default value is 0.0. Sets min_persistence to -1.0 to see all values.

Returns:

Nothing.

dimension()#

This function returns the dimension of the complex.

Returns:

int – the complex dimension.

num_simplices()#

This function returns the number of all cubes in the complex.

Returns:

int – the number of all cubes in the complex.

persistence()#

This function computes and returns the persistence of the complex.

Parameters:
• homology_coeff_field (int.) – The homology coefficient field. Must be a prime number. Default value is 11. Max is 46337.

• min_persistence (float.) – The minimum persistence value to take into account (strictly greater than min_persistence). Default value is 0.0. Sets min_persistence to -1.0 to see all values.

Returns:

list of pairs(dimension, pair(birth, death)) – the persistence of the complex.

persistence_intervals_in_dimension()#

This function returns the persistence intervals of the complex in a specific dimension.

Parameters:

dimension (int.) – The specific dimension.

Returns:

The persistence intervals.

Return type:

numpy array of dimension 2

Note:

intervals_in_dim function requires `compute_persistence()` function to be launched first.

persistent_betti_numbers()#

This function returns the persistent Betti numbers of the complex.

Parameters:
• from_value (float.) – The persistence birth limit to be added in the numbers (persistent birth <= from_value).

• to_value (float.) – The persistence death limit to be added in the numbers (persistent death > to_value).

Returns:

list of int – The persistent Betti numbers ([B0, B1, …, Bn]).

Note:

persistent_betti_numbers function requires `compute_persistence()` function to be launched first.

top_dimensional_cells()#

Array with the filtration values of the top-dimensional cells of the complex. Modifying the values is strongly discouraged.

Returns:

numpy.ndarray

vertices()#

Array with the filtration values of the vertices of the complex. Modifying the values is strongly discouraged.

Returns:

numpy.ndarray

vertices_of_persistence_pairs()#

This function returns a list of pairs of vertices corresponding to the persistence birth and death cells of the filtration. The cells are represented by their indices in the input list of vertices (and not their indices in the internal datastructure that includes non-minimal cells). Note that when two adjacent vertices have the same filtration value, we arbitrarily return one of the two when calling the function on one of their common faces.

Since the cubical complex construction from vertices is different from the top dimensional one, the former may not have an equivalent with the second construction, and vice versa. Therefore, using `vertices_of_persistence_pairs()` with a cubical complex constructed from top_dimensional_cells can lead to an undefined behavior.

Returns:

The vertices of the positive and negative cells, together with the corresponding homological dimension, in two lists of numpy arrays of integers. The first list contains the regular persistence pairs, grouped by dimension. It contains numpy arrays of shape (number_of_persistence_points, 2). The indices of the arrays in the list correspond to the homological dimensions, and the integers of each row in each array correspond to: (index of positive vertex, index of negative vertex). The second list contains the essential features, grouped by dimension. It contains numpy arrays of shape (number_of_persistence_points,). The indices of the arrays in the list correspond to the homological dimensions, and the integers of each row in each array correspond to: (index of positive vertex).