DensityFiltration

class gtda.images.DensityFiltration(radius=3, metric='euclidean', metric_params={}, n_jobs=None)[source]

Filtrations of 2D/3D binary images based on the number of activated neighboring pixels.

The density filtration assigns to each pixel of a binary image a greyscale value equal to the number of activated pixels within a ball centered around it.

Parameters
  • radius (float, optional, default: 1.) – The radius of the ball within which the number of activated pixels is considered.

  • metric (string or callable, optional, default: 'euclidean') – Determines a rule with which to calculate distances between pairs of pixels. If metric is a string, it must be one of the options allowed by scipy.spatial.distance.pdist for its metric parameter, or a metric listed in sklearn.pairwise.PAIRWISE_DISTANCE_FUNCTIONS, including “euclidean”, “manhattan”, or “cosine”. If metric is a callable function, it is called on each pair of instances and the resulting value recorded. The callable should take two arrays from the entry in X as input, and return a value indicating the distance between them.

  • metric_params (dict, optional, default: {}) – Additional keyword arguments for the metric function.

  • 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.

n_dimensions_

Dimension of the images. Set in fit.

Type

2 or 3

mask_

The mask applied around each pixel to calculate the weighted number of its activated neighbors. Set in fit.

Type

ndarray of shape (radius, radius [, radius])

References

[1] A. Garin and G. Tauzin, “A topological reading lesson: Classification

of MNIST using TDA”; 19th International IEEE Conference on Machine Learning and Applications (ICMLA 2020), 2019; arXiv: 1910.08345.

__init__(radius=3, metric='euclidean', metric_params={}, n_jobs=None)[source]

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

fit(X, y=None)[source]

Calculate n_dimensions_ and mask_ from a collection of binary images. Then, return the estimator.

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_x, n_pixels_y [, n_pixels_z])) – Input data. Each entry along axis 0 is interpreted as a 2D or 3D binary image.

  • 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 (ndarray of shape (n_samples, n_pixels_x, n_pixels_y [, n_pixels_z])) – Input data. Each entry along axis 0 is interpreted as a 2D or 3D binary image.

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

Returns

Xt – Transformed collection of images. Each entry along axis 0 is a 2D or 3D greyscale image.

Return type

ndarray of shape (n_samples, n_pixels_x, n_pixels_y [, n_pixels_z])

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, colorscale='greys', origin='upper', plotly_params=None)[source]

Plot a sample from a collection of 2D greyscale images.

Parameters
  • Xt (ndarray of shape (n_samples, n_pixels_x, n_pixels_y)) – Collection of 2D greyscale images, such as returned by transform.

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

  • colorscale (str, optional, default: 'greys') – Color scale to be used in the heat map. Can be anything allowed by plotly.graph_objects.Heatmap.

  • origin ('upper' | 'lower', optional, default: 'upper') – Position of the [0, 0] pixel of data, in the upper left or lower left corner. The convention 'upper' is typically used for matrices and images.

  • plotly_params (dict or None, optional, default: None) – Custom parameters to configure the plotly figure. Allowed keys are "trace" 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)[source]

For each binary image in the collection X, calculate a corresponding greyscale image based on the density of its pixels. Return the collection of greyscale images.

Parameters
  • X (ndarray of shape (n_samples, n_pixels_x, n_pixels_y [, n_pixels_z])) – Input data. Each entry along axis 0 is interpreted as a 2D or 3D binary image.

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

Returns

Xt – Transformed collection of images. Each entry along axis 0 is a 2D or 3D greyscale image.

Return type

ndarray of shape (n_samples, n_pixels_x, n_pixels_y [, n_pixels_z])

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, ..)