torch_topological.utils
Utilities module.
- torch_topological.utils.is_iterable(x)[source]
Check whether variable is iterable.
- Parameters
x (any) – Input object.
- Returns
True
ifx
is iterable.- Return type
bool
- torch_topological.utils.nesting_level(x)[source]
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
. Ifx
has no well-defined nesting level, for example becausex
is not a list of something, will return0
.- 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.persistent_entropy(D, **kwargs)[source]
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)[source]
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)[source]
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)[source]
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 containingx
.- 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)[source]
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)[source]
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)[source]
Apply selection parameters to input.
Iterate over input and select diagrams according to the pre-defined parameters.
- Parameters
X (iterable of
PersistenceInformation
) – An iterable containingPersistenceInformation
objects at its lowest level.- Returns
Input, i.e.
X
, but with all non-matching persistence diagrams removed.- Return type
iterable
- training: bool