chalc.sixpack¶

Routines for computing 6-packs of persistence diagrams.

Classes¶

`FiltrationInclusion`	Represents the inclusion of a filtered subcomplex.
`FiltrationMorphism`	Represents a map of filtrations.
`KChromaticInclusion`	Corresponds to the inclusion of the \(k\)-chromatic subcomplex of a chromatic filtration.
`KChromaticQuotient`	Corresponds to gluing all subfiltrations spanned by \(k\) colours.
`SimplexPairings`	Persistence diagram represented by paired and unpaired simplices.
`SixPack`	6-pack of persistence diagrams.
`SubChromaticInclusion`	Corresponds to the inclusion of a particular subset or subsets of colours.

Functions¶

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

Module Contents¶

class FiltrationInclusion¶

Bases: FiltrationMorphism, abc.ABC

digraph inheritance1064b7f578 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "ABC" [URL="https://docs.python.org/3/library/abc.html#abc.ABC",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Helper class that provides a standard way to create an ABC using"]; "FiltrationInclusion" [URL="#chalc.sixpack.FiltrationInclusion",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Represents the inclusion of a filtered subcomplex."]; "FiltrationMorphism" -> "FiltrationInclusion" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ABC" -> "FiltrationInclusion" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FiltrationMorphism" [URL="#chalc.sixpack.FiltrationMorphism",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Represents a map of filtrations."]; "ABC" -> "FiltrationMorphism" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

Represents the inclusion of a filtered subcomplex.

simplex_in_domain(column: tuple[list[int], int, float, list[int]], filtration: chalc.filtration.Filtration) → bool¶

Check if a simplex is in the domain of the inclusion map.

A simplex is identified by its column in the boundary matrix of the filtration.

class FiltrationMorphism¶

Bases: abc.ABC

digraph inheritance04459cd4ff { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "ABC" [URL="https://docs.python.org/3/library/abc.html#abc.ABC",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Helper class that provides a standard way to create an ABC using"]; "FiltrationMorphism" [URL="#chalc.sixpack.FiltrationMorphism",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Represents a map of filtrations."]; "ABC" -> "FiltrationMorphism" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

Represents a map of filtrations.

This is an abstract class. To specify a morphism, instantiate one of the subclasses.

compute_diagrams(filtration: chalc.filtration.Filtration, max_dgm_dim: int) → SixPack¶: Compute the 6-pack of persistence diagrams induced by this morphism.

class KChromaticInclusion¶

Bases: int, FiltrationInclusion

digraph inheritancee1c0b48be8 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "ABC" [URL="https://docs.python.org/3/library/abc.html#abc.ABC",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Helper class that provides a standard way to create an ABC using"]; "FiltrationInclusion" [URL="#chalc.sixpack.FiltrationInclusion",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Represents the inclusion of a filtered subcomplex."]; "FiltrationMorphism" -> "FiltrationInclusion" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ABC" -> "FiltrationInclusion" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FiltrationMorphism" [URL="#chalc.sixpack.FiltrationMorphism",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Represents a map of filtrations."]; "ABC" -> "FiltrationMorphism" [arrowsize=0.5,style="setlinewidth(0.5)"]; "KChromaticInclusion" [URL="#chalc.sixpack.KChromaticInclusion",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Corresponds to the inclusion of the :math:`k`-chromatic subcomplex of a chromatic filtration."]; "FiltrationInclusion" -> "KChromaticInclusion" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

Corresponds to the inclusion of the \(k\)-chromatic subcomplex of a chromatic filtration.

The \(k\)-chromatic subcomplex is the subfiltration spanned by simplices having at most \(k\) colours.

class KChromaticQuotient¶

Bases: int, FiltrationMorphism

digraph inheritance2e16e7abdf { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "ABC" [URL="https://docs.python.org/3/library/abc.html#abc.ABC",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Helper class that provides a standard way to create an ABC using"]; "FiltrationMorphism" [URL="#chalc.sixpack.FiltrationMorphism",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Represents a map of filtrations."]; "ABC" -> "FiltrationMorphism" [arrowsize=0.5,style="setlinewidth(0.5)"]; "KChromaticQuotient" [URL="#chalc.sixpack.KChromaticQuotient",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Corresponds to gluing all subfiltrations spanned by :math:`k` colours."]; "FiltrationMorphism" -> "KChromaticQuotient" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

Corresponds to gluing all subfiltrations spanned by \(k\) colours.

Given a chromatic filtration \(K\) with colours \(C\), this is the quotient map \(\bigsqcup_{\substack{I \subset C\\ |I| = k}} K_I \to K\), where \(K_I\) is the subfiltration spanned by simplices whose colours are a subset of \(I\).

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

Bases: collections.abc.Collection

digraph inheritance8a8b59eca3 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "Collection" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled"]; "Sized" -> "Collection" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Iterable" -> "Collection" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Container" -> "Collection" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Container" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled"]; "Iterable" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled"]; "SimplexPairings" [URL="#chalc.sixpack.SimplexPairings",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Persistence diagram represented by paired and unpaired simplices."]; "Collection" -> "SimplexPairings" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Sized" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled"]; }

Persistence diagram represented by paired and unpaired simplices.

__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.

__hash__() → int¶: Return a hash of the persistence diagram.

__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¶: Represent the persistence diagram as a string.

property paired: frozenset[tuple[int, int]]¶: Set of indices of paired simplices.

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 unpaired: frozenset[int]¶: Set of indices of unpaired simplices.

class SixPack( kernel: SimplexPairings | None = None, cokernel: SimplexPairings | None = None, domain: SimplexPairings | None = None, codomain: SimplexPairings | None = None, image: SimplexPairings | None = None, relative: SimplexPairings | None = None, entrance_times: collections.abc.Sequence[float] = [], dimensions: collections.abc.Sequence[int] = [], )¶

Bases: collections.abc.Mapping

digraph inheritancea7e3d7a2fa { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "Collection" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled"]; "Sized" -> "Collection" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Iterable" -> "Collection" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Container" -> "Collection" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Container" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled"]; "Iterable" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled"]; "Mapping" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="A Mapping is a generic container for associating key/value"]; "Collection" -> "Mapping" [arrowsize=0.5,style="setlinewidth(0.5)"]; "SixPack" [URL="#chalc.sixpack.SixPack",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="6-pack of persistence diagrams."]; "Mapping" -> "SixPack" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Sized" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled"]; }

6-pack of persistence diagrams.

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

__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 identical.

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

__hash__() → int¶: Return a hash of the 6-pack of persistence diagrams.

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

__len__() → int¶: Return the number of 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.

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

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

Parameters:: file – A h5py file or group.

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

get_matrix(diagram_name: DiagramName, dimension: 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'.
dimension – 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 dimension 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.

classmethod names() → tuple[DiagramName, Ellipsis]¶: Return 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) → SixPack¶: Discard all features with persistence <=tolerance.

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

class SubChromaticInclusion¶

Bases: tuple, FiltrationInclusion

digraph inheritanceed821eed96 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "ABC" [URL="https://docs.python.org/3/library/abc.html#abc.ABC",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Helper class that provides a standard way to create an ABC using"]; "FiltrationInclusion" [URL="#chalc.sixpack.FiltrationInclusion",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Represents the inclusion of a filtered subcomplex."]; "FiltrationMorphism" -> "FiltrationInclusion" [arrowsize=0.5,style="setlinewidth(0.5)"]; "ABC" -> "FiltrationInclusion" [arrowsize=0.5,style="setlinewidth(0.5)"]; "FiltrationMorphism" [URL="#chalc.sixpack.FiltrationMorphism",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Represents a map of filtrations."]; "ABC" -> "FiltrationMorphism" [arrowsize=0.5,style="setlinewidth(0.5)"]; "SubChromaticInclusion" [URL="#chalc.sixpack.SubChromaticInclusion",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Corresponds to the inclusion of a particular subset or subsets of colours."]; "FiltrationInclusion" -> "SubChromaticInclusion" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

Corresponds to the inclusion of a particular subset or subsets of colours.

If the subset is a collection of integers, then all simplices whose colours lie in that subset are included. Otherwise, if each element of the subset is itself a collection of integers, then all simplices whose colours lie in any of those collections are included.

For example, SubChromaticInclusion(combinations(all_colours, k)) represents the same morphism as KChromaticInclusion(k).

compute( points: numpy.ndarray[tuple[compute.NumRows, compute.NumCols], numpy.dtype[numpy.float64]], colours: collections.abc.Sequence[int], mapping_method: FiltrationMorphism, filtration_algorithm: Literal['alpha', 'delcech', 'delrips'] = 'delcech', max_diagram_dimension: int | None = None, threshold: float = 0, max_num_threads: int = 1, ) → SixPack¶

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 a map of \(f : L \to K\) of filtrations, where \(L\) is some filtration constructed from \(K\).

Parameters:

points – Numpy matrix whose columns are points.
colours – Sequence of integers describing the colours of the points.
mapping_method – The method for constructing the map of filtrations.
filtration_algorithm – 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.
threshold – Retain only points with persistence strictly greater than this value.
max_num_threads – Maximum number of threads to use to compute the filtration.

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.