1.4. MapperGraph class

This is the mapper graph class which is inherited from the Reeb graph class. The main differences are

1. The Mapper graph is a graph with a function, but all function values are stored as integers. There is also a stored delta value which is can be used for scaling, so that all function values can be thought of as delta * f(v).

2. All edges have adjacent integer values. This equivalently means that no integer has a point in the interior of an edge in its inverse image.

Note that this class can be imported as:

import cereeberus
R = cereeberus.MapperGraph()

class cereeberus.reeb.mapper.MapperGraph(G=None, f={}, delta=None, seed=None, verbose=False)

A mapper graph structure. This inherits the properties of the Reeb graph in that it is a graph with a function given on the vertices, but with some additional requirements.

• The values are integers in some range, [n_low, n_low+1, cdots, n_high], although we consider the funciton values to be [delta * n_low, delta* (n_low+1), cdots, delta * n_high] for a stored delta

• If an edge crosses a value, it has a vertex (so that the inverse image of any integer is only vertices, not interiors of edges)

• An internal delta is stored so that this can be interpreted as function values [delta * n_low, delta* (n_low+1), cdots, delta * n_high]

__init__(G=None, f={}, delta=None, seed=None, verbose=False)

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 used when initializing constrained x-positions for drawing.

• verbose – bool, optional. If True, will print out additional information during initialization.

add_edge(u, v, reset_pos=True)

Add an edge to the graph. This will also update the internal structure to make sure it satisfies the mapper properties.

mapperify()

Take the internal structure and make sure it satisfies the requirement that all edges have adjacent function values.

add_node(vertex, f_vertex, reset_pos=True)

Same as adding a node in Reeb, but with the additional requirement that the function value is an integer.

set_pos_from_f(seed=None, repulsion=0.5, verbose=False)

Same as the Reeb graph function, but we want to draw the vertex locations at delta*function value.

induced_subgraph(nodes)

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

Parameters:

nodes (list) – The list of nodes to include in the subgraph.

Returns:

MapperGraph

smoothing_and_maps(n=1)

Compute the smoothing of a mapper graph as given in todo: Cite the paper. Note that the input \(n\) parameter is related to the integer function values, not the delta-scaled function values.

Parameters:

n (int) – The amount of smoothing

Returns:

MapperGraph, vertex_map, edge_map

Return type:

tuple

smoothing(n=1)

Compute the smoothing of a mapper graph as given in todo: Cite the paper. Note that the input \(n\) parameter is related to the integer function values, not the delta-scaled function values.

Parameters:

n (int, optional) – Smoothing amount. Defaults to 1.

Raises:

ValueError – _description_

Returns:

_description_

Return type:

_type_

draw_pie(labels, categories=None, colors=None, zoom=0.15, size_by_points=False, min_zoom=0.08, max_zoom=0.3, with_edges=True, with_legend=True, with_labels=True, cpx=0.1, cpy=0.0, ax=None)

Draw this mapper graph with each vertex shown as a small pie chart of the labels breakdown among the data points assigned to that vertex.

This requires the mapper graph to have been built via cereeberus.computeMapper(), which records which original data points ended up in each node.

Parameters:

• labels (sequence) – a category label for every point in the point cloud (or distance matrix) used to build this mapper graph via computeMapper.

• categories (list, optional) – ordered category values to plot. Defaults to the sorted set of unique labels.

• colors (dict, optional) – mapping from category value to a matplotlib color. Defaults to the “tab10” colormap.

• zoom (float) – size of each pie-chart glyph. Reduce this for dense graphs where nodes sit close together, to avoid neighboring pies overlapping.

• size_by_points (bool) – if True, scale each pie’s size by the number of points assigned to that node. This can be useful for emphasizing nodes that represent more data, but can also make the graph harder to read if the size differences are extreme. If True, min_zoom and max_zoom control the range of zoom values.

• min_zoom (float) – when size_by_points is True, the minimum and maximum zoom values to use for the smallest and largest nodes, respectively.

• max_zoom (float) – when size_by_points is True, the minimum and maximum zoom values to use for the smallest and largest nodes, respectively.

• with_edges (bool) – whether to draw the underlying graph edges.

• with_legend (bool) – whether to add a legend.

• with_labels (bool) – whether to draw each node’s index/name

• cpx (float) – curvature parameters for multi-edges.

• cpy (float) – curvature parameters for multi-edges.

• ax (matplotlib.axes.Axes, optional)

Returns:

matplotlib.axes.Axes

thickening_distance_by_level(level, obj_type='V')

Get the thickening distance matrix at a given level. This distance is the amount of thickening needed before the given pair of vertices at that level map to the same connected component.

Parameters:

• level – int. The level to get the thickening distance matrix at.

• obj_type – str. ‘V’ or ‘E’ to get the distance matrix for vertices or edges, respectively. Default is ‘V’.

Returns:

LabeledMatrix

thickening_distance_matrix(obj_type='V')

Get the thickening distance matrix for the entire mapper graph. This is a labeled block matrix with rows and columns indexed by vertices, and entries given by the thickening distance between the two vertices.

Returns:

LabeledBlockMatrix