chalc.sixpack¶

Routines for computing 6-packs of persistence diagrams.

Classes¶

`DiagramEnsemble`	6-pack of persistence diagrams.
`SimplexPairings`	Persistence diagram object.

Functions¶

`compute`(→ DiagramEnsemble)	Compute the 6-pack of persistence diagrams of a coloured point-cloud.
`from_filtration`(→ DiagramEnsemble)	Compute 6-pack of persistence diagrams from a chromatic filtration.

Module Contents¶

class DiagramEnsemble( ker: SimplexPairings | None = None, cok: SimplexPairings | None = None, dom: SimplexPairings | None = None, cod: SimplexPairings | None = None, im: SimplexPairings | None = None, rel: SimplexPairings | None = None, entrance_times: collections.abc.Sequence[float] = [], dimensions: collections.abc.Sequence[int] = [], )¶

Bases: collections.abc.Mapping

6-pack of persistence diagrams.

DiagramName: TypeAlias = Literal['ker', 'cok', 'dom', 'cod', 'im', 'rel']¶: Names of the diagrams in the 6-pack.

__bool__() → bool¶: Return true if any diagram in the 6-pack is non-empty.

__contains__(key: object) → bool¶: Return true if a diagram is in the 6-pack.

__eq__(other: object) → bool¶: Check if two 6-packs of persistence diagrams are equal.

__getitem__(key: DiagramName) → SimplexPairings¶: Access a specific diagram in the 6-pack.

__iter__() → collections.abc.Iterator[tuple[DiagramName, SimplexPairings]]¶: Iterate over all diagrams in the 6-pack.

__len__() → int¶: Return the number of diagrams in the 6-pack.

classmethod from_file(file: h5py.Group) → DiagramEnsemble¶

Load a 6-pack of persistence diagrams from a HDF5 file or group.

Parameters:: file – A h5py file or group.

get(key: DiagramName, default: U = None) → SimplexPairings | U¶

Access a specific diagram in the 6-pack.

Returns a default value if the diagram does not exist.

get_matrix(diagram_name: DiagramName, dim: int) → numpy.ndarray[tuple[int, Literal[2]], numpy.dtype[numpy.float64]]¶

get_matrix(diagram_name: DiagramName, dim: list[int] | None = None) → list[numpy.ndarray[tuple[int, Literal[2]], numpy.dtype[numpy.float64]]]

Get a specific diagram as a matrix of birth and death times.

Parameters:

diagram_name – One of 'ker', 'cok', 'dom', 'cod', 'im', or 'rel'.
dim – Dimension(s) of the diagram desired. If a list is provided then a list of matrices is returned, with the order of matrices respecting the order of entries of dim. If dim is not provided then the returned matrix will contain persistent features from all homological dimensions from zero to max(self.dimensions).

Returns:

An \(m \times 2\) matrix whose rows are a pair of birth and death times, or a list of such matrices.

items() → collections.abc.ItemsView[DiagramName, SimplexPairings]¶: View of the diagrams in the 6-pack.

keys() → collections.abc.KeysView[DiagramName]¶: View of the names of the diagrams in the 6-pack.

num_features() → int¶: Count the total number of features across all diagrams in the 6-pack.

save(file: h5py.Group) → None¶

Save a 6-pack of persistence diagrams to a HDF5 file or group.

Parameters:: file – A h5py file or group.

threshold(tolerance: float) → DiagramEnsemble¶: Discard all features with persistence <=tolerance.

values() → collections.abc.ValuesView[SimplexPairings]¶: View of the diagrams in the 6-pack.

property dimensions: numpy.ndarray[tuple[int], numpy.dtype[numpy.int64]]¶: Dimensions of the simplices.

property entrance_times: numpy.ndarray[tuple[int], numpy.dtype[numpy.float64]]¶: Entrance times of the simplices.

class SimplexPairings(paired: collections.abc.Collection[tuple[int, int]] = set(), unpaired: collections.abc.Collection[int] = set())¶

Bases: collections.abc.Collection

Persistence diagram object.

__bool__() → bool¶: Return true if the diagram is non-empty.

__contains__(feature: object) → bool¶

Return true if a feature is in the diagram.

The feature to check should be either a pair of simplices (int, int) or a single simplex (int).

__eq__(other: object) → bool¶: Check if two diagrams have the same paired and unpaired simplices.

__iter__() → collections.abc.Iterator[tuple[int, int] | int]¶: Iterate over all features in the diagram.

__len__() → int¶: Return the number of features in the diagram.

__str__() → str¶: Return string representation of the persistence diagram.

paired_as_matrix() → numpy.ndarray[tuple[int, Literal[2]], numpy.dtype[numpy.int64]]¶: Return a matrix representation of the finite persistence features in the diagram.

property paired: set[tuple[int, int]]¶: Set of indices of paired simplices (read-only).

property unpaired: set[int]¶: Set of indices of unpaired simplices (read-only).

compute( x: numpy.ndarray[tuple[NumRows, NumCols], numpy.dtype[numpy.floating]], colours: collections.abc.Sequence[int], dom: collections.abc.Collection[int] | int | None = None, k: int | None = None, method: Literal['alpha', 'delcech', 'delrips'] = 'alpha', max_diagram_dimension: int | None = None, tolerance: float = 0, ) → DiagramEnsemble¶

Compute the 6-pack of persistence diagrams of a coloured point-cloud.

This function constructs a filtered simplicial complex \(K\) from the point cloud, and computes the 6-pack of persistence diagrams associated with the inclusion \(f : L \hookrightarrow K\) where \(L\) is some filtered subcomplex of \(K\).

Parameters:

x – Numpy matrix whose columns are points.
colours – Sequence of integers describing the colours of the points.
dom – Integer or collection of integers describing the colours of the points in the domain (the subcomplex \(L\)).
k – If not None, then the domain is taken to be the \(k\)-chromatic subcomplex of \(K\), i.e., the subcomplex of simplices having at most \(k\) colours.
method – Filtration used to construct the chromatic complex. Must be one of 'alpha', 'delcech', or 'delrips'.
max_diagram_dimension – Maximum homological dimension for which the persistence diagrams are computed. By default diagrams of all dimensions are computed.
tolerance – Retain only points with persistence strictly greater than this value.

Returns :

Diagrams corresponding to the following persistence modules (where \(H_*\) is the persistent homology functor and \(f_*\) is the induced map on persistent homology):

\(H_*(L)\) (domain)
\(H_*(K)\) (codomain)
\(\ker(f_*)\) (kernel)
\(\mathrm{coker}(f_*)\) (cokernel)
\(\mathrm{im}(f_*)\) (image)
\(H_*(K, L)\) (relative homology)

Each diagram is represented by sets of paired and unpaired simplices, and contains simplices of all dimensions. dgms also contains the entrance times of the simplices and their dimensions.

from_filtration( K: chalc.filtration.FilteredComplex, dom: collections.abc.Collection[int] | int | None = None, k: int | None = None, max_diagram_dimension: int | None = None, tolerance: float = 0, ) → DiagramEnsemble¶

Compute 6-pack of persistence diagrams from a chromatic filtration.

Given a filtered chromatic simplicial complex \(K\) and a subcomplex \(L\) of \(K\), this function computes the 6-pack of persistence diagram associated with the inclusion map \(f : L \hookrightarrow K\). The subcomplex is specified by the colours of its vertices, or by an integer \(k\) wherein all simplices with \(k\) or fewer colours are considered part of the subcomplex.

Parameters:

K – A filtered chromatic simplicial complex.
dom – Integer or collection of integers describing the colours of the points in the domain (the subcomplex \(L\)).
k – If not None, then the domain is taken to be the \(k\)-chromatic subcomplex of \(K\), i.e., the subcomplex of simplices having at most \(k\) colours.
max_diagram_dimension – Maximum homological dimension for which the persistence diagrams are computed. By default diagrams of all dimensions are computed.
tolerance – Retain only points with persistence strictly greater than this value.

Returns:

Diagrams corresponding to the following persistence modules (where \(H_*\) is the persistent homology functor and \(f_*\) is the induced map on persistent homology):

\(H_*(L)\) (domain)
\(H_*(K)\) (codomain)
\(\ker(f_*)\) (kernel)
\(\mathrm{coker}(f_*)\) (cokernel)
\(\mathrm{im}(f_*)\) (image)
\(H_*(K, L)\) (relative homology)

Each diagram is represented by sets of paired and unpaired simplices, and contain simplices of all dimensions. dgms also contains the entrance times of the simplices and their dimensions.