level_set_filtration

level_set_filtration(image, max_dimension=1, min_heatmap=-inf, max_heatmap=inf, visualise_output=False, visualise_peristence_diagram_kwargs={})

Compute the level set filtration of a given single channel 2D image. The level-set filtration is a method used to study the topology of a scalar function defined on a space (e.g., a real-valued function on a manifold or domain). Given a continuous function f: X -> R, the filtration is built by considering sublevel sets X_alpha = f^{-1}((−∞, α]) for increasing values of α. These sublevel sets show how the topology of the domain changes as α increases. As α increases, new regions of the space are added, creating a nested sequence of sublevel sets. This filtration reveals how topological features such as connected components, loops, and voids emerge and disappear across the domain.

Parameters:

imagearray-like

The input image, which must be a 2-dimensional array-like structure (list, tuple, or numpy array).

max_dimensionint, optional

The maximum dimension of persistent homology to compute. Default is 1.

min_heatmapfloat, optional

The minimum value for the heatmap. Default is -infinity.

max_heatmapfloat, optional

The maximum value for the heatmap. Default is infinity.

visualise_outputbool, optional

If True, visualise the persistence diagram. Default is False.

visualise_peristence_diagram_kwargsdict, optional

Additional keyword arguments to pass to the persistence_diagram function when visualising the persistence diagram.

Returns:

dict

A dictionary containing the persistent features. The key ‘dgms’ maps to a list of persistence diagrams, one for each dimension up to max_dimension.

Raises:

ValueError

If the input image is not a 2-dimensional array-like structure. If min_heatmap or max_heatmap is not a float or int. If the input image does not have exactly 2 dimensions.

Notes

This function uses the Ripser library to compute the persistent homology of the level set filtration. The input image is converted to a sparse distance matrix, which is then passed to Ripser.

Examples

>>> import muspan as ms 
>>> import numpy as np
>>> image = np.array([[1, 2], [3, 4]])
>>> result = ms.topology.level_set_filtration(image)
>>> print(result['dgms'])