torch_topological.utils

Utilities module.

torch_topological.utils.is_iterable(x)

Check whether variable is iterable.

Parameters:

x (any) – Input object.

Returns:

True if x is iterable.

Return type:

bool

torch_topological.utils.nesting_level(x)

Calculate nesting level of a list of objects.

To convert between sparse and dense representations of topological features, we need to determine the nesting level of an input list. The nesting level is defined as the maximum number of times we can recurse into the object while still obtaining lists.

Parameters:

x (list) – Input list of objects.

Returns:

Nesting level of x. If x has no well-defined nesting level, for example because x is not a list of something, will return 0.

Return type:

int

Notes

This function is implemented recursively. It is therefore a bad idea to apply it to objects with an extremely high nesting level.

Examples

>>> nesting_level([1, 2, 3])
1

>>> nesting_level([[1, 2], [3, 4]])
2

torch_topological.utils.pairwise(iterable)

Return iterator to iterate over consecutive pairs.

Parameters:

iterable (iterable) –

Returns:

An iterator to iterate over consecutive pairs of the input data.

Return type:

iterator

Notes

A similar function appears in more recent versions of the collections module. For compatibility with old Python versions, we provide our own implementation.

Examples

>>> [x for x in pairwise(["ABC"])]
["AB", "BC"]

torch_topological.utils.persistent_entropy(D, **kwargs)

Calculate persistent entropy of a persistence diagram.

Parameters:

D (torch.tensor) – Persistence diagram, assumed to be in shape (n, 2), where each entry corresponds to a tuple of the form \((x, y)\), with \(x\) denoting the creation of a topological feature and \(y\) denoting its destruction.

Return type:

Persistent entropy of D.

torch_topological.utils.polynomial_function(D, p, q, **kwargs)

Parametrise polynomial function over persistence diagrams.

This function follows an approach by Adcock et al. [Adcock16a] and parametrises a polynomial function over a persistence diagram.

Parameters:

• D (torch.tensor) – Persistence diagram, assumed to be in shape (n, 2), where each entry corresponds to a tuple of the form \((x, y)\), with \(x\) denoting the creation of a topological feature and \(y\) denoting its destruction.

• p (float) – Exponent for persistence differences in the diagram.

• q (float) – Exponent for mean persistence in the diagram.

Returns:

• Sum of the form \(\sigma L^p * \mu^q\), with \(L\) denoting

• an individual persistence value, and \(\mu\) denoting its

• average persistence.

References

[Adcock16a]

A. Adcock et al., “The Ring of Algebraic Functions on Persistence Bar Codes”, Homology, Homotopy and Applications, Volume 18, Issue 1, pp. 381–402, 2016.

torch_topological.utils.total_persistence(D, p=2, **kwargs)

Calculate total persistence of a persistence diagram.

This function will calculate the total persistence of a persistence diagram. Infinite values will be ignored.

Parameters:

• D (torch.tensor) – Persistence diagram, assumed to be in shape (n, 2), where each entry corresponds to a tuple of the form \((x, y)\), with \(x\) denoting the creation of a topological feature and \(y\) denoting its destruction.

• p (float) – Weight parameter for the total persistence calculation.

Returns:

Total persistence of D.

Return type:

float

torch_topological.utils.wrap_if_not_iterable(x)

Wrap variable in case it cannot be iterated over.

This function provides a convenience wrapper for variables that need to be iterated over. If the variable is already an iterable, there is nothing to be done and it will be returned as-is. Otherwise, will ‘wrap’ the variable to be the single item of a list.

The primary purpose of this function is to make it easier for users to interact with certain classes: essentially, one does not have to think any more about single inputs vs. iterable inputs.

Parameters:

x (any) – Input object.

Returns:

If x can be iterated over, x will be returned as-is. Else, will return [x], i.e. a list containing x.

Return type:

list or type of x

Examples

>>> wrap_if_not_iterable(1.0)
[1.0]
>>> wrap_if_not_iterable('Hello, World!')
'Hello, World!'

class torch_topological.utils.SelectByDimension(min_dim, max_dim=None)

Select persistence diagrams by dimension.

This is a simple selector that enables filtering the outputs of persistent homology calculation algorithms by dimension: often, one is really only interested in a specific dimension but the corresponding algorithm yields more diagrams. To this end, this module can be applied as a lightweight filter.

__init__(min_dim, max_dim=None)

Prepare filter for subsequent usage.

Provides the filter with the required parameters. A minimum dimension must be provided. There is also the option to use a maximum dimension, thus permitting filtering by ranges.

Parameters:

• min_dim (int) – Minimum dimension to allow through the filter. If this is the sole provided parameter, only diagrams satisfying the dimension requirement will be selected.

• max_dim (int) – Optional upper dimension. If set, the selection returns a diagram whose dimension is within [min_dim, max_dim].

forward(X)

Apply selection parameters to input.

Iterate over input and select diagrams according to the pre-defined parameters.

Parameters:

X (iterable of PersistenceInformation) – An iterable containing PersistenceInformation objects at its lowest level.

Returns:

Input, i.e. X, but with all non-matching persistence diagrams removed.

Return type:

iterable

training: bool