CoverComplex reference manual#

class gudhi.CoverComplex#

Bases: object

Cover complex data structure.

The data structure is a simplicial complex, representing a Graph Induced simplicial Complex (GIC) or a Nerve, and whose simplices are computed with a cover C of a point cloud P, which often comes from the preimages of intervals covering the image of a function f defined on P. These intervals are parameterized by their resolution (either their length or their number) and their gain (percentage of overlap). To compute a GIC, one also needs a graph G built on top of P, whose cliques with vertices belonging to different elements of C correspond to the simplices of the GIC.

__init__()#

CoverComplex constructor.

__new__(**kwargs)#
compute_PD()#

Computes the extended persistence diagram of the complex.

compute_confidence_level_from_distance(distance)#

Computes the confidence level of a specific bottleneck distance threshold.

Parameters:

distance (double) – Bottleneck distance.

Return type:

double

Returns:

Confidence level.

compute_distance_from_confidence_level(alpha)#

Computes the bottleneck distance threshold corresponding to a specific confidence level.

Parameters:

alpha (double) – Confidence level.

Return type:

double

Returns:

Bottleneck distance.

compute_distribution(N=100)#

Computes bootstrapped distances distribution.

Parameters:

N – Loop number (default value is 100).

compute_p_value()#

Computes the p-value, i.e. the opposite of the confidence level of the largest bottleneck distance preserving the points in the persistence diagram of the output simplicial complex.

Return type:

double

Returns:

p-value.

create_simplex_tree()#
Returns:

A simplex tree created from the Cover complex.

Return type:

SimplexTree

find_simplices()#

Computes the simplices of the simplicial complex.

plot_dot()#

Creates a .dot file called SC.dot for neato (part of the graphviz package) once the simplicial complex is computed to get a visualization of its 1-skeleton in a .pdf file.

plot_off()#

Creates a .off file called SC.off for 3D visualization, which contains the 2-skeleton of the GIC. This function assumes that the cover has been computed with Voronoi. If data points are in 1D or 2D, the remaining coordinates of the points embedded in 3D are set to 0.

read_point_cloud(off_file)#

Reads and stores the input point cloud from .(n)OFF file.

Parameters:

off_file (string) – Name of the input .OFF or .nOFF file.

Return type:

bool

Returns:

Read file status.

set_automatic_resolution()#

Computes the optimal length of intervals (i.e. the smallest interval length avoiding discretization artifacts - see [8]) for a functional cover.

Return type:

double

Returns:

reso interval length used to compute the cover.

set_color_from_coordinate(k=0)#

Computes the function used to color the nodes of the simplicial complex from the k-th coordinate.

Parameters:

k (int) – Coordinate to use (start at 0). Default value is 0.

set_color_from_file(color_file_name)#

Computes the function used to color the nodes of the simplicial complex from a file containing the function values.

Parameters:

color_file_name (string) – Name of the input color file.

set_color_from_range(color)#

Computes the function used to color the nodes of the simplicial complex from a vector stored in memory.

Parameters:

color (vector[double]) – Input vector of values.

set_cover_from_Voronoi(m=100)#

Creates the cover C from the Voronoï cells of a subsampling of the point cloud.

Parameters:

m (int) – Number of points in the subsample. Default value is 100.

set_cover_from_file(cover_file_name)#

Creates the cover C from a file containing the cover elements of each point (the order has to be the same as in the input file!).

Parameters:

cover_file_name (string) – Name of the input cover file.

set_cover_from_function()#

Creates a cover C from the preimages of the function f.

set_cover_from_range(assignments)#

Creates a cover C from a vector stored in memory.

Parameters:

assignments (List[List[int]]) – Vector containing the assignments of the points to their corresponding cover elements. For instance, if the i-th point belongs to the 1st and 3rd cover elements, then assignments[i] = [1,3].

set_distances_from_range(distance_matrix)#

Reads and stores the input distance matrix from a vector stored in memory.

Parameters:

distance_matrix (vector[vector[double]]) – Input vector containing the distance matrix.

set_function_from_coordinate(k)#

Creates the function f from the k-th coordinate of the point cloud.

Parameters:

k (int) – Coordinate to use (start at 0).

set_function_from_file(func_file_name)#

Creates the function f from a file containing the function values.

Parameters:

func_file_name (string) – Name of the input function file.

set_function_from_range(function)#

Creates the function f from a vector stored in memory.

Parameters:

function (vector[double]) – Input vector of values.

set_gain(g=0.3)#

Sets a gain from a value stored in memory.

Parameters:

g (double) – Gain (default value is 0.3).

set_graph_from_OFF()#

Creates a graph G from the triangulation given by the input OFF file.

set_graph_from_automatic_rips(N=100)#

Creates a graph G from a Rips complex whose threshold value is automatically tuned with subsampling - see [8].

Parameters:

N (int) – Number of subsampling iteration (the default reasonable value is 100, but there is no guarantee on how to choose it).

Return type:

double

Returns:

Delta threshold used for computing the Rips complex.

set_graph_from_file(graph_file_name)#

Creates a graph G from a file containing the edges.

Parameters:

graph_file_name (string) – Name of the input graph file. The graph file contains one edge per line, each edge being represented by the IDs of its two nodes.

set_graph_from_rips(threshold)#

Creates a graph G from a Rips complex.

Parameters:

threshold (double) – Threshold value for the Rips complex.

set_mask(nodemask)#

Sets the mask, which is a threshold integer such that nodes in the complex that contain a number of data points which is less than or equal to this threshold are not displayed.

Parameters:

nodemask (int) – Threshold.

set_point_cloud_from_range(cloud)#

Reads and stores the input point cloud from a vector stored in memory.

Parameters:

cloud (vector[vector[double]]) – Input vector containing the point cloud.

set_resolution_with_interval_length(resolution)#

Sets a length of intervals from a value stored in memory.

Parameters:

resolution (double) – Length of intervals.

set_resolution_with_interval_number(resolution)#

Sets a number of intervals from a value stored in memory.

Parameters:

resolution (int) – Number of intervals.

set_subsampling(constant, power)#

Sets the constants used to subsample the data set. These constants are explained in [8].

Parameters:
  • constant (double) – Constant.

  • power – Power.

set_type(type)#

Specifies whether the type of the output simplicial complex.

Parameters:

type (string) – either “GIC” or “Nerve”.

set_verbose(verbose)#

Specifies whether the program should display information or not.

Parameters:

verbose (boolean) – true = display info, false = do not display info.

subcolor(c)#

Returns the mean color value corresponding to a specific node of the created complex.

Parameters:

c (int) – ID of the node.

Return type:

float

Returns:

Mean color value of data points.

subpopulation(c)#

Returns the data subset corresponding to a specific node of the created complex.

Parameters:

c (int) – ID of the node.

Return type:

vector[int]

Returns:

Vector of IDs of data points.

write_info()#

Creates a .txt file called SC.txt describing the 1-skeleton, which can then be plotted with e.g. KeplerMapper.