TensorFlow layer for representations

	Vectorizations, distances and kernels that work on persistence diagrams, compatible with scikit-learn and tensorflow.	Authors: Mathieu Carrière, Martin Royer, Gard Spreemann, Wojciech Reise Since: GUDHI 3.1.0 License: MIT
	Representations manual
	TensorFlow layer for representations

PersLay is a layer for neural network architectures that allows to automatically learn the best representation to use for persistence diagrams in supervised machine learning during training time. Its parameters allow to reproduce most of the known finite-dimensional representations (such as, e.g., landscapes and images), and can be combined to create even new ones, that are best suited for a given supervised machine learning task with persistence diagrams. PersLay is implemented in TensorFlow.

This notebook explains how to use PersLay.

Example

PersLay

import numpy             as np
import tensorflow        as tf
from sklearn.preprocessing import MinMaxScaler
import gudhi.representations as gdr
import gudhi.tensorflow.perslay as prsl

diagrams = [np.array([[0.,4.],[1.,2.],[3.,8.],[6.,8.]])]
diagrams = gdr.DiagramScaler(use=True, scalers=[([0,1], MinMaxScaler())]).fit_transform(diagrams)
diagrams = tf.RaggedTensor.from_tensor(tf.constant(diagrams, dtype=tf.float32))

rho = tf.identity
phi = prsl.GaussianPerslayPhi((5, 5), ((-.5, 1.5), (-.5, 1.5)), .1)
weight = prsl.PowerPerslayWeight(1.,0.)
perm_op = tf.math.reduce_sum

perslay = prsl.Perslay(phi=phi, weight=weight, perm_op=perm_op, rho=rho)
vectors = perslay(diagrams)
print(vectors)

tf.Tensor(
[[[[1.72661e-16]
   [4.17060e-09]
   [1.13369e-08]
   [8.57388e-12]
   [2.12439e-14]]

  [[4.17151e-09]
   [1.00741e-01]
   [2.73843e-01]
   [3.07242e-02]
   [7.61575e-05]]

  [[8.03829e-06]
   [1.58027e+00]
   [8.29970e-01]
   [1.23954e+01]
   [3.07241e-02]]

  [[8.02694e-06]
   [1.30657e+00]
   [9.09230e+00]
   [6.16648e-02]
   [1.39492e-06]]

  [[9.03313e-13]
   [1.49548e-07]
   [1.51460e-04]
   [1.02051e-06]
   [7.80935e-16]]]], shape=(1, 5, 5, 1), dtype=float32)

Perslay reference manual

class gudhi.tensorflow.perslay.Perslay

Bases: Layer

This is a TensorFlow layer for vectorizing persistence diagrams in a differentiable way within a neural network. This function implements the PersLay equation, see the corresponding article.

__init__(weight, phi, perm_op, rho, **kwargs)

Constructor for the Perslay class.

Parameters:

• weight (function) – weight function for the persistence diagram points. Can be either GridPerslayWeight, GaussianMixturePerslayWeight, PowerPerslayWeight, or a custom TensorFlow function that takes persistence diagrams as argument (represented as an (n x None x 2) ragged tensor, where n is the number of diagrams).

• phi (function) – transformation function for the persistence diagram points. Can be either GaussianPerslayPhi, TentPerslayPhi, FlatPerslayPhi, or a custom TensorFlow class (that can have trainable parameters) with a method call that takes persistence diagrams as argument (represented as an (n x None x 2) ragged tensor, where n is the number of diagrams).

• perm_op (function) – permutation invariant function, such as tf.math.reduce_sum, tf.math.reduce_mean, tf.math.reduce_max, tf.math.reduce_min, or a custom TensorFlow function that takes two arguments: a tensor and an axis on which to apply the permutation invariant operation. If perm_op is the string “topk” (where k is a number), this function will be computed as tf.math.top_k with parameter int(k).

• rho (function) – postprocessing function that is applied after the permutation invariant operation. Can be any TensorFlow layer.

build(input_shape)

Creates the variables of the layer (for subclass implementers).

This is a method that implementers of subclasses of Layer or Model can override if they need a state-creation step in-between layer instantiation and layer call. It is invoked automatically before the first execution of call().

This is typically used to create the weights of Layer subclasses (at the discretion of the subclass implementer).

Parameters:

input_shape – Instance of TensorShape, or list of instances of TensorShape if the layer expects a list of inputs (one instance per input).

call(diagrams)

Apply Perslay on a ragged tensor containing a list of persistence diagrams.

Parameters:

diagrams (n x None x 2) – ragged tensor containing n persistence diagrams. The second dimension is ragged since persistence diagrams can have different numbers of points.

Returns:

tensor containing the vectorizations of the persistence diagrams.

Return type:

vector (n x output_shape)

Weight functions

class gudhi.tensorflow.perslay.GaussianMixturePerslayWeight

Bases: Layer

This is a class for computing a differentiable weight function for persistence diagram points. This function is defined from a mixture of Gaussian functions.

__init__(gaussians, **kwargs)

Constructor for the GridPerslayWeight class.

Parameters:

gaussians (4 x n numpy array) – parameters of the n Gaussian functions, of the form transpose([[mu_x^1, mu_y^1, sigma_x^1, sigma_y^1], …, [mu_x^n, mu_y^n, sigma_x^n, sigma_y^n]]).

build(input_shape)

Creates the variables of the layer (for subclass implementers).

This is a method that implementers of subclasses of Layer or Model can override if they need a state-creation step in-between layer instantiation and layer call. It is invoked automatically before the first execution of call().

This is typically used to create the weights of Layer subclasses (at the discretion of the subclass implementer).

Parameters:

input_shape – Instance of TensorShape, or list of instances of TensorShape if the layer expects a list of inputs (one instance per input).

call(diagrams)

Apply GaussianMixturePerslayWeight on a ragged tensor containing a list of persistence diagrams.

Parameters:

diagrams (n x None x 2) – ragged tensor containing n persistence diagrams. The second dimension is ragged since persistence diagrams can have different numbers of points.

Returns:

ragged tensor containing the weights of the points in the n persistence diagrams. The second dimension is ragged since persistence diagrams can have different numbers of points.

Return type:

weight (n x None)

class gudhi.tensorflow.perslay.GridPerslayWeight

Bases: Layer

This is a class for computing a differentiable weight function for persistence diagram points. This function is defined from an array that contains its values on a 2D grid.

__init__(grid, grid_bnds, **kwargs)

Constructor for the GridPerslayWeight class.

Parameters:

• grid (n x n numpy array) – grid of values.

• grid_bnds (2 x 2 numpy array) – boundaries of the grid, of the form [[min_x, max_x], [min_y, max_y]].

build(input_shape)

Creates the variables of the layer (for subclass implementers).

This is a method that implementers of subclasses of Layer or Model can override if they need a state-creation step in-between layer instantiation and layer call. It is invoked automatically before the first execution of call().

This is typically used to create the weights of Layer subclasses (at the discretion of the subclass implementer).

Parameters:

input_shape – Instance of TensorShape, or list of instances of TensorShape if the layer expects a list of inputs (one instance per input).

call(diagrams)

Apply GridPerslayWeight on a ragged tensor containing a list of persistence diagrams.

Parameters:

diagrams (n x None x 2) – ragged tensor containing n persistence diagrams. The second dimension is ragged since persistence diagrams can have different numbers of points.

Returns:

ragged tensor containing the weights of the points in the n persistence diagrams. The second dimension is ragged since persistence diagrams can have different numbers of points.

Return type:

weight (n x None)

class gudhi.tensorflow.perslay.PowerPerslayWeight

Bases: Layer

This is a class for computing a differentiable weight function for persistence diagram points. This function is defined as a constant multiplied by the distance to the diagonal of the persistence diagram point raised to some power.

__init__(constant, power, **kwargs)

Constructor for the PowerPerslayWeight class.

Parameters:

• constant (float) – constant value.

• power (float) – power applied to the distance to the diagonal.

build(input_shape)

Creates the variables of the layer (for subclass implementers).

This is a method that implementers of subclasses of Layer or Model can override if they need a state-creation step in-between layer instantiation and layer call. It is invoked automatically before the first execution of call().

This is typically used to create the weights of Layer subclasses (at the discretion of the subclass implementer).

Parameters:

input_shape – Instance of TensorShape, or list of instances of TensorShape if the layer expects a list of inputs (one instance per input).

call(diagrams)

Apply PowerPerslayWeight on a ragged tensor containing a list of persistence diagrams.

Parameters:

diagrams (n x None x 2) – ragged tensor containing n persistence diagrams. The second dimension is ragged since persistence diagrams can have different numbers of points.

Returns:

ragged tensor containing the weights of the points in the n persistence diagrams. The second dimension is ragged since persistence diagrams can have different numbers of points.

Return type:

weight (n x None)

Phi functions

class gudhi.tensorflow.perslay.FlatPerslayPhi

Bases: Layer

This is a class for computing a transformation function for persistence diagram points. This function turns persistence diagram points into 1D constant functions (that evaluate to half of the bar length on the bar corresponding to the point and zero elsewhere), that are then evaluated on a regular 1D grid.

__init__(samples, theta, **kwargs)

Constructor for the FlatPerslayPhi class.

Parameters:

• samples (float numpy array) – grid elements on which to evaluate the constant functions, of the form [x_1, …, x_n].

• theta (float) – sigmoid parameter used to approximate the constant function with a differentiable sigmoid function. The bigger the theta, the closer to a constant function the output will be.

build(input_shape)

Creates the variables of the layer (for subclass implementers).

This is a method that implementers of subclasses of Layer or Model can override if they need a state-creation step in-between layer instantiation and layer call. It is invoked automatically before the first execution of call().

This is typically used to create the weights of Layer subclasses (at the discretion of the subclass implementer).

Parameters:

input_shape – Instance of TensorShape, or list of instances of TensorShape if the layer expects a list of inputs (one instance per input).

call(diagrams)

Apply FlatPerslayPhi on a ragged tensor containing a list of persistence diagrams.

Parameters:

diagrams (n x None x 2) – ragged tensor containing n persistence diagrams. The second dimension is ragged since persistence diagrams can have different numbers of points.

Returns:

ragged tensor containing the evaluations on the 1D grid of the 1D constant functions corresponding to the persistence diagram points. The second dimension is ragged since persistence diagrams can have different numbers of points. output_shape (int numpy array): shape of the output tensor.

Return type:

output (n x None x num_samples)

class gudhi.tensorflow.perslay.GaussianPerslayPhi

Bases: Layer

This is a class for computing a transformation function for persistence diagram points. This function turns persistence diagram points into 2D Gaussian functions centered on the points, that are then evaluated on a regular 2D grid.

__init__(image_size, image_bnds, variance, **kwargs)

Constructor for the GaussianPerslayPhi class.

Parameters:

• image_size (int numpy array) – number of grid elements on each grid axis, of the form [n_x, n_y].

• image_bnds (2 x 2 numpy array) – boundaries of the grid, of the form [[min_x, max_x], [min_y, max_y]].

• variance (float) – variance of the Gaussian functions.

build(input_shape)

Creates the variables of the layer (for subclass implementers).

This is a method that implementers of subclasses of Layer or Model can override if they need a state-creation step in-between layer instantiation and layer call. It is invoked automatically before the first execution of call().

This is typically used to create the weights of Layer subclasses (at the discretion of the subclass implementer).

Parameters:

input_shape – Instance of TensorShape, or list of instances of TensorShape if the layer expects a list of inputs (one instance per input).

call(diagrams)

Apply GaussianPerslayPhi on a ragged tensor containing a list of persistence diagrams.

Parameters:

diagrams (n x None x 2) – ragged tensor containing n persistence diagrams. The second dimension is ragged since persistence diagrams can have different numbers of points.

Returns:

ragged tensor containing the evaluations on the 2D grid of the 2D Gaussian functions corresponding to the persistence diagram points, in the form of a 2D image with 1 channel that can be processed with, e.g., convolutional layers. The second dimension is ragged since persistence diagrams can have different numbers of points. output_shape (int numpy array): shape of the output tensor.

Return type:

output (n x None x image_size x image_size x 1)

class gudhi.tensorflow.perslay.TentPerslayPhi

Bases: Layer

This is a class for computing a transformation function for persistence diagram points. This function turns persistence diagram points into 1D tent functions (linearly increasing on the first half of the bar corresponding to the point from zero to half of the bar length, linearly decreasing on the second half and zero elsewhere) centered on the points, that are then evaluated on a regular 1D grid.

__init__(samples, **kwargs)

Constructor for the GaussianPerslayPhi class.

Parameters:

samples (float numpy array) – grid elements on which to evaluate the tent functions, of the form [x_1, …, x_n].

build(input_shape)

Creates the variables of the layer (for subclass implementers).

This is a method that implementers of subclasses of Layer or Model can override if they need a state-creation step in-between layer instantiation and layer call. It is invoked automatically before the first execution of call().

This is typically used to create the weights of Layer subclasses (at the discretion of the subclass implementer).

Parameters:

input_shape – Instance of TensorShape, or list of instances of TensorShape if the layer expects a list of inputs (one instance per input).

call(diagrams)

Apply TentPerslayPhi on a ragged tensor containing a list of persistence diagrams.

Parameters:

diagrams (n x None x 2) – ragged tensor containing n persistence diagrams. The second dimension is ragged since persistence diagrams can have different numbers of points.

Returns:

ragged tensor containing the evaluations on the 1D grid of the 1D tent functions corresponding to the persistence diagram points. The second dimension is ragged since persistence diagrams can have different numbers of points. output_shape (int numpy array): shape of the output tensor.

Return type:

output (n x None x num_samples)