chalc.plotting¶

Plotting and visualisation utilities.

Functions¶

`animate_filtration`(→ matplotlib.animation.FuncAnimation)	Create animation of 2-skeleton of filtered simplicial complex.
`draw_filtration`(→ matplotlib.axes.Axes)	Draw selected vertices, edges, and triangles of a filtration in the plane.
`plot_persistence_diagram`(→ matplotlib.axes.Axes)	Plot the persistence diagram for a persistence module.
`plot_sixpack`(→ tuple[matplotlib.figure.Figure, ...)	Plot the persistence diagrams for a `chalc.morphisms.FiltrationMorphism.sixpack()`.

Module Contents¶

animate_filtration( filtration: chalc.filtration.Filtration, points: numpy.ndarray[tuple[Literal[2], int], numpy.dtype[numpy.floating]], filtration_times: collections.abc.Sequence[float], *, animation_length: float, plot_colours: str | numpy.ndarray | None = None, vertices_kwargs: dict | None = None, edges_kwargs: dict | None = None, faces_kwargs: dict | None = None, ) → matplotlib.animation.FuncAnimation¶

Create animation of 2-skeleton of filtered simplicial complex.

Parameters:

filtration – A filtered complex.
points – The vertices of filtration as a \(2\times N\) numpy matrix.
filtration_times – Sequence of filtration times for which to draw animation frames.
animation_length – Total length of the animation in seconds, unrelated to the filtration times.
plot_colours – Either the name of a matplotlib qualitative colour map, or a list of colours. If not provided, the current matplotlib colour cycle will be used.
vertices_kwargs – Keyword arguments to pass to the matplotlib scatter function for plotting points.
edges_kwargs – Keyword arguments to pass to the matplotlib plot function for plotting edges.
faces_kwargs – Keyword arguments to pass to the matplotlib fill function for plotting faces.

draw_filtration( filtration: chalc.filtration.Filtration, points: numpy.ndarray[tuple[Literal[2], int], numpy.dtype[numpy.floating]], select: collections.abc.Callable[[chalc.filtration.Simplex, int], bool] | None = None, *, include_faces: bool = True, ax: matplotlib.axes.Axes | None = None, plot_colours: str | numpy.ndarray | None = None, vertices_kwargs: dict | None = None, edges_kwargs: dict | None = None, faces_kwargs: dict | None = None, ) → matplotlib.axes.Axes¶

Draw selected vertices, edges, and triangles of a filtration in the plane.

Parameters:

filtration – A filtered simplicial complex. Only its 2-skeleton is drawn.
points – The vertices of filtration as a \(2\times N\) numpy matrix.
select – Optional callback select(simplex, index) returning True if the simplex should be drawn. It receives a simplex handle and its zero-based index in filtration.boundary_matrix(). The callback is called once for each simplex of dimension at most 2, in boundary-matrix order. Simplices of higher dimension still count towards the indices. If omitted, all vertices, edges, and triangles are drawn.

Keyword Arguments:

include_faces – Whether to select all faces of selected simplices.
ax – A matplotlib axes object. If provided then the filtration will be plotted on the given axes.
plot_colours – Either the name of a matplotlib qualitative colour map, or a list of colours. If not provided, the current matplotlib colour cycle will be used.
vertices_kwargs – Keyword arguments to pass to the matplotlib scatter function for plotting points.
edges_kwargs – Keyword arguments to pass to the matplotlib plot function for plotting edges.
faces_kwargs – Keyword arguments to pass to the matplotlib fill function for plotting faces.

Returns:

The axes on which the simplices were drawn.

Raises:

ValueError – If points does not have shape (2, filtration.num_vertices).

Notes

The callback must not modify filtration. Representative supports must use the indices of filtration.boundary_matrix(). For representatives computed from a dimension-limited boundary matrix, pass the corresponding skeleton as filtration.

plot_persistence_diagram(

persistence_module: chalc.morphisms.AugmentedPersistenceModule,

*,

truncation: float | None = None,

degrees: collections.abc.Collection[int] | chalc.morphisms.IndexArray | int | numpy.integer | None = None,

ax: matplotlib.axes.Axes | None = None,

threshold: float = 0,

kwargs_per_dim: collections.abc.Mapping[int, dict] | None = None,

points_legend: bool = True,

lines_legend: bool = True,

**kwargs,

) → matplotlib.axes.Axes¶

Plot the persistence diagram for a persistence module.

Parameters:

persistence_module – The augmented persistence module.
truncation – The maximum entrance time for which the persistence module is plotted. A positive finite default is calculated from the retained intervals.
degrees – The homological degrees in which to plot features. If not provided, all degrees will be included in the plots.
ax – A matplotlib axes object. If provided then the persistence diagram will be plotted on the given axes.
threshold – Only features with persistence greater than this value will be plotted. The threshold is applied before truncating their displayed coordinates.
kwargs_per_dim – Keyword arguments for each degree, as a mapping { degree : dictionary of kwargs }. These will be passed to the matplotlib scatter function, and take precedence over any other keyword arguments.
points_legend – Whether to show a legend for the feature degrees.
lines_legend – Whether to show a legend for the truncation lines.
**kwargs – Additional keyword arguments to pass to the matplotlib scatter function.

Returns:

The axes containing the diagram, creating a new figure if ax is omitted.

plot_sixpack( sixpack: chalc.morphisms.SixPack, truncations: collections.abc.Mapping[chalc.morphisms.PersistenceModuleName, float | None] | float | None = None, degrees: collections.abc.Collection[int] | chalc.morphisms.IndexArray | int | numpy.integer | None = None, threshold: float = 0, ) → tuple[matplotlib.figure.Figure, numpy.ndarray[tuple[Literal[2], Literal[3]], numpy.dtype[Any]]]¶

Plot the persistence diagrams for a chalc.morphisms.FiltrationMorphism.sixpack().

Parameters:

sixpack – The 6-pack of persistence modules.
truncations – The maximum entrance time up to which features are plotted. Can be either a single value, or a mapping from persistence module names to values. A sensible default is calculated for module names omitted from the mapping.
degrees – The homological degrees for which to plot features. If not provided, all degrees will be included in the plots.
threshold – Only features with persistence greater than this value will be plotted.

Returns:

The figure and a (2, 3) array of axes. The top row contains domain, codomain, and image; the bottom row contains kernel, cokernel, and relative.