1.1. ReebGraph class

This is the Reeb graph class which is the majority of functionality of the package. This includes functionality such as assigning function values to nodes in the Reeb graph and plotting the graph.

Note that this class can be imported as:

import cereeberus
R = cereeberus.ReebGraph()

class cereeberus.reeb.reebgraph.ReebGraph(G=None, f={}, seed=None, verbose=False)[source]

A Reeb graph stored as a networkx MultiDiGraph. The function values are stored as a dictionary. The directedness of the edges follows the convention that the edge goes from the lower function value to the higher function value node.

__init__(G=None, f={}, seed=None, verbose=False)[source]

Initializes a Reeb graph object.

Parameters:

G – nx.graph, optional. If not None, a graph to initialize the Reeb graph.
f – dict, optional. If not an empty dictionary, a dictionary of function values associated with the graph nodes.
seed – int, optional. If not None, a seed to pass to the spring layout.
verbose – bool, optional. If True, will print out additional information during initialization.

summary()[source]

Summary of the Reeb graph.

Returns:

dict: A dictionary with the number of nodes and edges in the Reeb graph.

get_function_values()[source]

Get the function values of the nodes in the Reeb graph.

Returns:

list: A sorted list of function values.

min_f()[source]

Get the minimum function value in the Reeb graph.

Returns:

float: The minimum function value.

max_f()[source]

Get the maximum function value in the Reeb graph.

Returns:

float: The maximum function value.

up_degree(node)[source]

Get the up degree of a node.

Parameters:

node – int. The node to get the up degree of.

Returns:

int: The up degree of the node.

down_degree(node)[source]

Get the down degree of a node.

Parameters:

node – int The node to get the down degree of.

Returns:

int: The down degree of the node.

number_connected_components()[source]

Get the number of connected components in the Reeb graph.

Returns:

int: The number of connected components in the Reeb graph.

func_to_vertex_dict()[source]

Get a dictionary mapping function values to all vertices at that height.

Returns:

dict: A dictionary mapping function values to vertices.

sorted_vertices()[source]

Get a list of vertices sorted by function value. Same order as passed by the func_to_vertex_dict method.

Returns:

list: A list of vertices sorted by function value.

func_to_edge_dict()[source]

Get a dictionary mapping function values to all edges with lower endpoint at that height.

Returns:

dict: A dictionary mapping function values to edges.

sorted_edges()[source]

Get a list of edges sorted by function value. Same order as passed by the func_to_edge_dict method.

Returns:

list: A list of edges sorted by function value.

relabel_nodes(mapping)[source]

Relabel the nodes of the Reeb graph using a mapping. The mapping should be a dictionary with keys as old node names and values as new node names.

Parameters:: mapping – dict. A dictionary mapping old node names to new node names.

inv_image(f_val)[source]

Get the set of vertices and/or edges at a given function value. This will return $v$ for which $f(v) = $`f_val`, as well as edges $e = (u,v)$ for which $f(u) < $`f_val` and $f(v) > $`f_val`.

Parameters:

f_val – float. The function value to get the objects for.

Returns:

(set, set): The set of vertices and the set of edges at the function value f_val.

Return type:

tuple

thickening_distance(u, v)[source]

Get the thickening distance between two vertices in the Reeb graph. This is the amount of thickening needed before the two vertices map to the same connected component. Note that u and v need to be at the same function value, so f(u) = f(v).

Parameters:

u – int. The vertices to get the thickening distance between.
v – int. The vertices to get the thickening distance between.

Returns:

int: The thickening distance between the two vertices.

get_next_vert_name()[source]

Get the next name for a vertex in the Reeb graph that isn’t already included. If there are no nodes, it will return 0. Otherwise, it will name the next vertex as one more than the maximum integer labeled vertex, ignoring any strings.

Returns:

str or int: The next name in the sequence.

add_node(vertex, f_vertex, reset_pos=True)[source]

Add a vertex to the Reeb graph. If the vertex name is given as None, it will be assigned via the get_next_vert_name method.

Parameters:

vertex (hashable like int or str, or None) – The name of the vertex to add.
f_vertex (float) – The function value of the vertex being added.
reset_pos (bool, optional) – If True, will reset the positions of the nodes based on the function values.

add_nodes_from(nodes, f_dict, reset_pos=True)[source]

Add a list of nodes to the Reeb graph.

Parameters:

nodes (list) – The list of node names to add.
f_dict (dict) – A dictionary of function values associated with the nodes. Should be f_dict[node] = f_value.
reset_pos (bool, optional) – If True, will reset the positions of the nodes based on the function values.

remove_node(vertex, reset_pos=True)[source]

Remove a vertex from the Reeb graph.

Parameters:

vertex (hashable like int or str) – The name of the vertex to remove.
reset_pos (bool, optional) – If True, will reset the positions of the nodes based on the function values.

remove_nodes_from(nodes, reset_pos=True)[source]

Remove a list of nodes from the Reeb graph.

Parameters:

nodes (list) – The list of node names to remove.
reset_pos (bool, optional) – If True, will reset the positions of the nodes based on the function values.

add_edge(u, v, reset_pos=True)[source]

Add an edge to the Reeb graph. Make sure that the edge points to the vertex with higher function value.

Note that if the edge added is between two vertices with the same function value, it will collapse the two vertices into one.

Parameters:

u – The edge to add.
v – The edge to add.
reset_pos (bool) – Optional. If True, will reset the positions of the nodes based on the function values.

add_edges_from(edges, reset_pos=True)[source]

Add a list of edges to the Reeb graph.

Parameters:

edges (list) – The list of edges to add.
reset_pos (bool) – Optional. If True, will reset the positions of the nodes based on the function values.

subdivide_edge(u, v, w, f_w)[source]

Subdivide an edge with a new vertex.

Parameters:

u – The edge to subdivide.
v – The edge to subdivide.
w – The new vertex to add.
f_w – The function value of the new vertex.

remove_regular_vertex(v)[source]

Remove a regular vertex from the Reeb graph. A regular vertex is one for which down degree = up degree = 1, so it can be removed and replaed with a single edge.

Parameters:: v (int) – The vertex to remove.

remove_all_regular_vertices()[source]: Remove all regular vertices from the Reeb graph.

remove_isolates()[source]: Remove all isolated vertices from the Reeb graph.

set_pos_from_f(seed=None, verbose=False)[source]

Set the position of the nodes based on the function values. The result will be the (spring layout x, function value y). Note that this will overwrite the previous positions.

Parameters:: verbose (bool) – Optional. If True, will print out the function values and the positions.

draw(with_labels=True, with_colorbar=False, cpx=0.1, ax=None, **kwargs)[source]

A drawing of the Reeb graph. Uses the fancy version from cereeberus.compute.draw.

Parameters:

with_labels (bool) – Optional. If True, will include the labels of the nodes.
cpx (float) – Optional. A parameter that controls “loopiness” of multiedges in the drawing.

Returns:

None

induced_subgraph(nodes)[source]

Returns the subgraph of the Reeb graph induced by the nodes in the list nodes.

Parameters:: nodes (list) – The list of nodes to include in the subgraph.
Returns:: The subgraph of the Reeb graph induced by the nodes in the list nodes.
Return type:: ReebGraph

slice(a, b, type='open', verbose=False)[source]

Returns the subgraph of the Reeb graph with image in the open interval (a,b) if type = ‘open’ or in the closed interval [a,b] of type = ‘closed’. This will convert any edges that cross the slice into vertices.

Parameters:

a (float) – The lower bound of the slice.
b (float) – The upper bound of the slice.
type (str) – Optional. The type of interval used to take the slice. Can be ‘open’ or ‘closed’. Default is ‘open’.

Returns:

The subgraph of the Reeb graph with image in (a,b).

Return type:

ReebGraph

connected_components()[source]

Returns the connected components of the Reeb graph by providing a set of vertices for each connected component. If you want to actually get the subgraphs of ReebGraph R returned as Reeb graphs, you can use:

[R.induced_subgraph(component) for component in R.connected_components()]

Returns:: A generator of sets of nodes, one for each component of the Reeb graph.

get_largest_component()[source]

Returns the largest connected component of the Reeb graph as a set of nodes. Note: this is not well defined unless the Reeb graph is minimal.

Returns:: The largest connected component of the Reeb graph based on number of vertices.
Return type:: ReebGraph

get_multi_edges()[source]

Returns a set of the edges that have count higher than 1. Useful for checking for multiedges in the Reeb graph.

Returns:: A set of edges that have count higher than 1.
Return type:: set

adjacency_matrix(symmetrize=True)[source]

Returns the adjacency matrix of the Reeb graph. Symmetrizes the matrix by default; if symmetrize = False, it will return the directed adjacency matrix.

Parameters:: symmetrize (bool) – Optional. If True, will return the symmetrized adjacency matrix. If False, will return the directed adjacency matrix.
Returns:: The adjacency matrix of the Reeb graph.
Return type:: numpy.ndarray

plot_adjacency_matrix(symmetrize=True)[source]

boundary_matrix(astype='numpy')[source]

Creates an boundary matrix for the graph, where $B[v,e] = 1$ if vertex $v$ is an endpoint of edge $e$ and $B[v,e] = 0$ otherwise. If astype is map, it will return a dictionary with keys as edges and values as lists of vertices that are endpoints of that edge.

Parameters:: astype (str) – Optional. The type of output to return. Can be ‘numpy’, or ‘map’. Default is ‘numpy’.
Returns:: The boundary matrix.
Return type:: numpy.ndarray

plot_boundary_matrix()[source]

smoothing_and_maps(eps=1, verbose=False)[source]

Builds the eps-smoothed Reeb graph from the input. One way to define this is for a given Reeb graph $(X,f)$, the smoothed graph is the Reeb graph of the product space $(X \times [-\varepsilon, \varepsilon], f(x) + t)$. This function also returns the maps (i) from the vertices of the original Reeb graph to the vertices of the smoothed Reeb graph and (ii) from the edges of the original to the edges of the smoothed graph. These maps are given as a dictionary with keys as vertices (resp. edges) in the original Reeb graph and values as vertices (resp. edges) in the smoothed Reeb graph.

Parameters:

eps (float) – The amount of smoothing to apply.
verbose (bool) – Optional. If True, will print out additional information during the smoothing process.

Returns:

ReebGraph, vertex_map, edge_map.

Return type:

tuple

smoothing(eps=1)[source]

Builds the eps-smoothed Reeb graph from the input. One way to define this is for a given Reeb graph $(X,f)$, the smoothed graph is the Reeb graph of the product space $(X \times [-\varepsilon, \varepsilon], f(x) + t)$.

Parameters:: eps (float) – The amount of smoothing to apply.
Returns:: The smoothed Reeb graph.
Return type:: ReebGraph

to_mapper(delta=None)[source]

Convert the Reeb graph to a Mapper graph as long as all function values are integers. Note this is NOT the same as computing the mapper graph of a given Reeb graph as the input topological space. This will create a new Mapper graph object with the same nodes and edges as the Reeb graph.

Parameters:: delta (float) – Optional. The delta value to use for the Mapper graph. If None, will use 1.
Returns:: The Mapper graph representation of the Reeb graph.
Return type:: MapperGraph