chalc.sixpack¶

Routines for computing 6-packs of persistence diagrams.

Attributes¶

`NumpyMatrix`	Type hint for an `M x N` numpy matrix whose entries are of type `T`.
`NumpyVector`	Type hint for an numpy vector of length `N` with entries of type `T`.

Classes¶

`DiagramEnsemble`	6-pack of persistence diagrams.
`SimplexPairings`	Persistence diagram object, represented by a

Functions¶

`compute`(→ DiagramEnsemble)	Compute the 6-pack of persistence diagrams of a coloured point-cloud.
`from_filtration`(→ DiagramEnsemble)	Compute the 6-pack of persistence diagrams associated to a filtered simplicial complex with coloured vertices.

Module Contents¶

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

Bases: collections.abc.Mapping

6-pack of persistence diagrams.

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

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

__iter__() → Iterator[tuple[DiagramName, SimplexPairings]]¶: Iterate over all 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, with a default value if the diagram does not exist.

get_matrix(diagram_name: DiagramName, dim: int) → NumpyMatrix[NumRows, Literal[2], numpy.float64]¶

get_matrix(diagram_name: DiagramName, dim: list[int] | None = None) → list[NumpyMatrix[NumRows, Literal[2], 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.

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

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

property dimensions: NumpyVector[Size, numpy.int64]¶: Dimensions of the simplices.

property entrance_times: NumpyVector[Size, 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, represented by a set of simplex pairings and a set of unpaired simplices.

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

__contains__(feature: tuple[int, int] | int) → bool¶: Returns true if a feature, represented by either a pair of simplices or a single unpaired simplex, is in the diagram.

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

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

paired_as_matrix() → NumpyMatrix[NumRows, Literal[2], numpy.int64]¶: Returns 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: NumpyMatrix[NumRows, NumCols, 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 the 6-pack of persistence diagrams associated to a filtered simplicial complex with coloured vertices.

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:

\(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.

Return type:

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

NumpyMatrix: TypeAlias = np.ndarray[tuple[M, N], np.dtype[T]]¶: Type hint for an M x N numpy matrix whose entries are of type T.

NumpyVector: TypeAlias = np.ndarray[N, np.dtype[T]]¶: Type hint for an numpy vector of length N with entries of type T.