chalc.sixpack¶

Routines for computing 6-packs of persistence diagrams.

Submodules¶

Attributes¶

DiagramName

Names of diagrams in a 6-pack of persistence diagrams.

Classes¶

`FiltrationInclusion`	Abstract inclusion of a filtered subcomplex.
`FiltrationMorphism`	Abstract map between filtered simplicial complexes.
`KChromaticInclusion`	Inclusion of the simplices having at most \(k\) colours.
`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`	Inclusion of a subfiltration spanned by any combination(s) of colours.
`SubChromaticQuotient`	Represents a gluing map in a chromatic filtration.

Package Contents¶

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

class FiltrationInclusion(filtration: chalc.filtration.Filtration)¶

Bases: FiltrationMorphism, abc.ABC

Inheritance diagram of chalc.sixpack.FiltrationInclusion

Abstract inclusion of a filtered subcomplex.

This class constructs the inclusion of an arbitrary subfiltration of a chromatic filtration.

This is an abstract class. To specify an inclusion map, use one of its concrete subclasses or create your own. To implement your own inclusion map, you need to implement the membership test simplex_in_domain which checks if a simplex is in the domain of the inclusion map.

abstractmethod simplex_in_domain(column: tuple[list[int], int, float, list[int]]) → 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. This column has the same format as the columns returned by chalc.filtration.Filtration.boundary_matrix().

sixpack(max_diagram_dimension: int | None = None) → chalc.sixpack.types.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:: max_diagram_dimension – Maximum homological dimension for which the persistence diagrams are computed. By default diagrams of all dimensions are computed.

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_*(\mathrm{cyl}(f), 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.

class FiltrationMorphism(filtration: chalc.filtration.Filtration)¶

Bases: abc.ABC

Inheritance diagram of chalc.sixpack.FiltrationMorphism

Abstract map between filtered simplicial complexes.

The map is a combinatorial proxy for the spatial relationships between points in the filtration of different colours. This is an abstract class. To specify a morphism, instantiate one of its concrete subclasses.

abstractmethod sixpack(max_diagram_dimension: int | None = None) → chalc.sixpack.types.SixPack¶

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

Parameters:: max_diagram_dimension – Maximum homological dimension for which the persistence diagrams are computed. By default diagrams of all dimensions are computed.

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_*(\mathrm{cyl}(f), 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.

class KChromaticInclusion(filtration: chalc.filtration.Filtration, k: int)¶

Bases: FiltrationInclusion

Inheritance diagram of chalc.sixpack.KChromaticInclusion

Inclusion of the simplices having at most \(k\) colours.

The \(k\)-chromatic subfiltration is spanned by simplices having at most \(k\) colours. This represents a special case of SubChromaticInclusion. Using the notation from SubChromaticInclusion, this class corresponds to setting \(\tau\) to be the \(k\)-skeleton of \(\Delta^s\), where \(\{0, \ldots, s\}\) is the set of colours.

In practical terms, the following code:

KChromaticInclusion(filtration, k).sixpack()

should give the same 6-pack of persistence diagrams as this:

SubChromaticInclusion(
        filtration,
        itertools.combinations(range(n_colours), k),
).sixpack()

There is, however, a slight performance benefit to using KChromaticInclusion over SubChromaticInclusion in this situation.

Examples

To consider the inclusion of all monochromatic simplices:

KChromaticInclusion(filtration, 1).sixpack()

To consider the inclusion of all simplices spanned by at most two colours:

KChromaticInclusion(filtration, 2).sixpack()

k: int¶: The value k.

simplex_in_domain(column: tuple[list[int], int, float, list[int]]) → 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. This column has the same format as the columns returned by chalc.filtration.Filtration.boundary_matrix().

class KChromaticQuotient(filtration: chalc.filtration.Filtration, k: int)¶

Bases: FiltrationQuotient

Inheritance diagram of chalc.sixpack.KChromaticQuotient

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

This represents a special case of SubChromaticQuotient. Using the notation from SubChromaticQuotient, this class corresponds to having the \(\tau_i\) range over all combinations of \(k\) colours from the set of colours \(\{0, \ldots, s\}\).

In practical terms, the following code:

KChromaticQuotient(filtration, k).sixpack()

should give the same 6-pack of persistence diagrams as this:

n_colours = len(set(colours))
SubChromaticQuotient(
        filtration,
        tuple(
                (combination,)
                for combination in combinations(range(n_colours), k))
        )
)

Note

KChromaticQuotient(1) is essentially the same as KChromaticInclusion(1) since both represent the inclusion of all monochromatic simplices. You should prefer to use KChromaticInclusion(1) for performance reasons, since KChromaticQuotient(1) will compute the mapping cylinder of the inclusion map, which is unnecessary.

k: int¶: The value k.

simplex_in_filtration(column: tuple[list[int], int, float, list[int]], i: int) → bool¶: Check if a simplex is in the i^th subfiltration.

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

Bases: collections.abc.Collection

Inheritance diagram of chalc.sixpack.SimplexPairings

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.

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

Inheritance diagram of chalc.sixpack.SixPack

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.

filter(func: collections.abc.Callable[[str, int, float, float], bool]) → SixPack¶

Filter out features in the diagram.

func should take four arguments: the name of the diagram to which a feature belongs, the dimension of the feature, and its birth and death times, and should return a boolean indicating whether the feature should be kept.

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: collections.abc.Sequence[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.

max_nonempty_dimension() → int¶

Get the maximum dimension of features across all diagrams.

Returns -1 if there are no features 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.

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

class SubChromaticInclusion( filtration: chalc.filtration.Filtration, tau: collections.abc.Collection[collections.abc.Collection[int]] | collections.abc.Collection[int], )¶

Bases: FiltrationInclusion, collections.abc.Sized

Inheritance diagram of chalc.sixpack.SubChromaticInclusion

Inclusion of a subfiltration spanned by any combination(s) of colours.

Let \(\{0, \ldots, s\}\) be a set of colours, let \(\Delta^s\) be the abstract simplicial complex whose vertices represent individual colours, and let \(\tau\) be any subcomplex of \(\Delta^s\). For a filtered simplicial complex \(K\) on a vertex set \(V\), and a colouring \(\mu:V \to \{0, \ldots, s\}\) of \(V\), let \(K/\tau\) denote the subfiltration of \(K\) comprising simplices \(\sigma \in K\) satisfying \(\mu(\sigma) \in \tau\). This class represents the inclusion map \(K/\tau \hookrightarrow K\).

The complex \(\tau\) is specified by its maximal faces, or by its maximal face if there is only one.

Examples

The inclusion of all monochromatic simplices of colours 0 and 1:

SubChromaticInclusion(filtration, [[0], [1]]).sixpack()

The inclusion of any simplex with colours in \(\{0, 1\}\), (which includes all monochromatic simplices of colours 0 and 1), i.e., \(\tau = \{\{0, 1\}, \{0\}, \{1\}\}\):

SubChromaticInclusion(filtration, [[0, 1]]).sixpack()

In this case since \(\tau\) has a single maximal face, you can also write the following.

SubChromaticInclusion(filtration, [0, 1]).sixpack()

You can also specify more general subsets of colours, for example \(\tau = \{\{0, 1\}, \{1, 2\}, \{0\}, \{1\}, \{2\}\}\).

SubChromaticInclusion(filtration, [[0, 1], [1, 2]]).sixpack()

simplex_in_domain(column: tuple[list[int], int, float, list[int]]) → 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. This column has the same format as the columns returned by chalc.filtration.Filtration.boundary_matrix().

class SubChromaticQuotient(filtration: chalc.filtration.Filtration, tau: collections.abc.Collection[collections.abc.Collection[collections.abc.Collection[int]]])¶

Bases: FiltrationQuotient

Inheritance diagram of chalc.sixpack.SubChromaticQuotient

Represents a gluing map in a chromatic filtration.

Let \(\{0, \ldots, s\}\) be a set of colours, let \(\Delta^s\) be the abstract simplicial complex whose vertices represent individual colours, and let \(\tau_0, \ldots, \tau_m\) be any subcomplexes of \(\Delta^s\). For a filtered simplicial complex \(K\) on a vertex set \(V\), and a colouring \(\mu:V \to \{0, \ldots, s\}\) of \(V\), let \(K/\tau_i\) denote the subfiltration of \(K\) comprising simplices \(\sigma \in K\) satisfying \(\mu(\sigma) \in \tau_i\) (\(1 \leq i \leq m\)). This class represents the quotient map

\[\bigsqcup_{i=0}^m K/\tau_i \twoheadrightarrow K,\]

Each complex \(\tau_i\) is specified by its maximal faces, or by its maximal face if there is only one.

Examples

If there is only one \(\tau_i\), then this is the same as the SubChromaticInclusion of \(\tau_i\). For example, both of the following computations produce the same 6-pack of persistence diagrams, corresponding to the inclusion of all monochromatic simplices of colours 0 and 1:

# Using SubChromaticQuotient
SubChromaticQuotient(
        filtration,
        [
                [[0, 1]],  # tau_0 = {{0,1}, {0}, {1}}
        ],
).sixpack()

# Using SubChromaticInclusion
SubChromaticInclusion(
        filtration,
        [[0,1]],
).sixpack()

If the \(\tau_i\) are disjoint, then this class produces the same result as SubChromaticInclusion:

# Using SubChromaticQuotient
SubChromaticQuotient(
        filtration,
        [
                [
                        [0, 1],
                ],  # tau_0 = {{0,1}, {0}, {1}}
                [
                        [2, 3],
                ],  # tau_1 = {{2,3}, {2}, {3}}
        ],
).sixpack()

# Using SubChromaticInclusion
SubChromaticInclusion(
        filtration,
        [
                # tau = {{0, 1}, {2, 3}, {0}, {1}, {2}, {3}}
                [0, 1], [2, 3],
        ],
).sixpack()

In general this is not necessarily the case:

# Using SubChromaticQuotient - gluing two subfiltrations
SubChromaticQuotient(
        filtration,
        [
                [
                        [0, 1],
                ],  # tau_0 = {{0,1}, {0}, {1}}
                [
                        [1, 2],
                ],  # tau_1 = {{1,2}, {1}, {2}}
        ],
).sixpack()

# Using SubChromaticInclusion - inclusion of a union of two subfiltrations
SubChromaticInclusion(
        filtration,
        [
                # tau = {{0, 1}, {1, 2}, {0}, {1}, {2}}
                [0, 1], [1, 2],
        ]
)

simplex_in_filtration(column: tuple[list[int], int, float, list[int]], i: int) → bool¶: Check if a simplex is in the i^th subfiltration.