CubicalPersistence

class gtda.homology.CubicalPersistence(homology_dimensions=0, 1, coeff=2, periodic_dimensions=None, infinity_values=None, reduced_homology=True, n_jobs=None)

Persistence diagrams resulting from filtered cubical complexes.

Given a greyscale image, information about the appearance and disappearance of topological features (technically, homology classes) of various dimensions and at different scales is summarised in the corresponding persistence diagram.

Important note:

• Persistence diagrams produced by this class must be interpreted with care due to the presence of padding triples which carry no information. See transform for additional information.

Parameters

• homology_dimensions (list or tuple, optional, default: (0, 1)) – Dimensions (non-negative integers) of the topological features to be detected.

• coeff (int prime, optional, default: 2) – Compute homology with coefficients in the prime field \(\mathbb{F}_p = \{ 0, \ldots, p - 1 \}\) where \(p\) equals coeff.

• periodic_dimensions (boolean ndarray of shape (n_dimensions,) or None, optional, default: None) – Periodicity of the boundaries along each of the axes, where n_dimensions is the dimension of the images of the collection. The boolean in the d`th position expresses whether the boundaries along the `d`th axis are periodic. The default ``None` is equivalent to passing numpy.zeros((n_dimensions,), dtype=np.bool), i.e. none of the boundaries are periodic.

• infinity_values (float or None, default: None) – Which death value to assign to features which are still alive at filtration value numpy.inf. None assigns the maximum pixel values within all images passed to fit.

• reduced_homology (bool, optional, default: True) – If True, the earliest-born triple in homology dimension 0 which has infinite death is discarded from each diagram computed in transform.

• n_jobs (int or None, optional, default: None) – The number of jobs to use for the computation. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors.

periodic_dimensions_

Effective periodicity of the boundaries along each of the axes. Set in fit.

Type

boolean ndarray of shape (n_dimensions,)

infinity_values_

Effective death value to assign to features which have infinite persistence. Set in fit.

Type

float

See also

images.HeightFiltration, images.RadialFiltration, images.DilationFiltration, images.ErosionFiltration, images.SignedDistanceFiltration

Notes

GUDHI is used as a C++ backend for computing cubical persistent homology 1. Python bindings were modified for performance.

References

1

P. Dlotko, “Cubical complex”, 2015; GUDHI User and Reference Manual.

__init__(homology_dimensions=0, 1, coeff=2, periodic_dimensions=None, infinity_values=None, reduced_homology=True, n_jobs=None)

Initialize self. See help(type(self)) for accurate signature.

fit(X, y=None)

Do nothing and return the estimator unchanged.

This method is here to implement the usual scikit-learn API and hence work in pipelines.

Parameters

• X (ndarray of shape (n_samples, n_pixels_1, .., n_pixels_d)) – Input data. Array of d-dimensional images.

• y (None) – There is no need of a target in a transformer, yet the pipeline API requires this parameter.

Returns

self

Return type

object

fit_transform(X, y=None, **fit_params)

Fit to data, then transform it.

Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.

Parameters

• X ({array-like, sparse matrix, dataframe} of shape (n_samples, n_features)) –

• y (ndarray of shape (n_samples,), default=None) – Target values.

• **fit_params (dict) – Additional fit parameters.

Returns

X_new – Transformed array.

Return type

ndarray array of shape (n_samples, n_features_new)

fit_transform_plot(X, y=None, sample=0, **plot_params)

Fit to data, then apply transform_plot.

Parameters

• X (ndarray of shape (n_samples, ..)) – Input data.

• y (ndarray of shape (n_samples,) or None) – Target values for supervised problems.

• sample (int) – Sample to be plotted.

• **plot_params – Optional plotting parameters.

Returns

Xt – Transformed one-sample slice from the input.

Return type

ndarray of shape (1, ..)

get_params(deep=True)

Get parameters for this estimator.

Parameters

deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns

params – Parameter names mapped to their values.

Return type

mapping of string to any

static plot(Xt, sample=0, homology_dimensions=None, plotly_params=None)

Plot a sample from a collection of persistence diagrams, with homology in multiple dimensions.

Parameters

• Xt (ndarray of shape (n_samples, n_features, 3)) – Collection of persistence diagrams, such as returned by transform.

• sample (int, optional, default: 0) – Index of the sample in Xt to be plotted.

• homology_dimensions (list, tuple or None, optional, default: None) – Which homology dimensions to include in the plot. None means plotting all dimensions present in Xt[sample].

• plotly_params (dict or None, optional, default: None) – Custom parameters to configure the plotly figure. Allowed keys are "traces" and "layout", and the corresponding values should be dictionaries containing keyword arguments as would be fed to the update_traces and update_layout methods of plotly.graph_objects.Figure.

Returns

fig – Plotly figure.

Return type

plotly.graph_objects.Figure object

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as pipelines). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters

**params (dict) – Estimator parameters.

Returns

self – Estimator instance.

Return type

object

transform(X, y=None)

For each image in X, compute the relevant persistence diagram as an array of triples [b, d, q]. Each triple represents a persistent topological feature in dimension q (belonging to homology_dimensions) which is born at b and dies at d. Only triples in which b < d are meaningful. Triples in which b and d are equal (“diagonal elements”) may be artificially introduced during the computation for padding purposes, since the number of non-trivial persistent topological features is typically not constant across samples. They carry no information and hence should be effectively ignored by any further computation.

Parameters

• X (ndarray of shape (n_samples, n_pixels_1, .., n_pixels_d)) – Input data. Array of d-dimensional images.

• y (None) – There is no need of a target in a transformer, yet the pipeline API requires this parameter.

Returns

Xt – Array of persistence diagrams computed from the feature arrays or distance matrices in X. n_features equals \(\sum_q n_q\), where \(n_q\) is the maximum number of topological features in dimension \(q\) across all samples in X.

Return type

ndarray of shape (n_samples, n_features, 3)

transform_plot(X, sample=0, **plot_params)

Take a one-sample slice from the input collection and transform it. Before returning the transformed object, plot the transformed sample.

Parameters

• X (ndarray of shape (n_samples, ..)) – Input data.

• sample (int) – Sample to be plotted.

• **plot_params – Optional plotting parameters.

Returns

Xt – Transformed one-sample slice from the input.

Return type

ndarray of shape (1, ..)