masspcf.persistence

Persistent homology, barcodes, and stable rank functions.

barcode

class masspcf.persistence.barcode.Barcode(bc)

Bases: object

A persistence barcode, i.e. a collection of bars (birth-death intervals).

A barcode is represented as an (n, 2) array where each row is a bar given as a (birth, death) pair from a persistent homology computation.

Parameters:

bc (Barcode or numpy.ndarray) – An existing Barcode to copy, or an (n, 2) NumPy array of (birth, death) pairs (float32 or float64).

is_isomorphic_to(bc: Barcode, atol: float = 1e-08, rtol: float = 1e-05)

Check whether two barcodes are isomorphic (same multiset of bars).

Bar endpoints are compared with a numerical tolerance so that barcodes computed via different but mathematically equivalent routes (for example, from a point cloud versus a precomputed distance matrix) still compare equal despite floating-point rounding. Two endpoints a and b are considered equal when abs(a - b) <= atol + rtol * abs(b); infinite endpoints must match exactly.

Parameters:

• bc (Barcode) – The barcode to compare against.

• atol (float, optional) – Absolute tolerance for endpoint comparison, by default 1e-8.

• rtol (float, optional) – Relative tolerance for endpoint comparison, by default 1e-5. Pass atol=0, rtol=0 for a bitwise comparison.

to_numpy()

Return the bars as an (n, 2) NumPy array of (birth, death) pairs.

ph_tensor

class masspcf.persistence.ph_tensor.BarcodeTensor(data)

Bases: Tensor

homology

class masspcf.persistence.homology.ComplexType(*values)

Bases: Enum

VietorisRips = 1

class masspcf.persistence.homology.DistanceType(*values)

Bases: Enum

Euclidean = 1

masspcf.persistence.homology.compute_persistent_homology(X: PointCloudTensor | DistanceMatrix | DistanceMatrixTensor | FloatTensor | ndarray, max_dim: int = 1, distance_type: DistanceType = DistanceType.Euclidean, complex_type: ComplexType = ComplexType.VietorisRips, reduced: bool = False, verbose: bool = False) → BarcodeTensor

Compute persistent homology of a point cloud or distance matrix.

Returns barcodes for homology dimensions 0 through max_dim. When complex_type is ComplexType.VietorisRips (currently the only available option), the computation uses Ripser [1]. When the input contains multiple point clouds or distance matrices, the computations are parallelized across them.

For an input tensor of shape \((d_1, \ldots, d_n)\), the output has shape \((d_1, \ldots, d_n, \texttt{max_dim} + 1)\).

Parameters:

• X (PointCloudTensor, DistanceMatrix, DistanceMatrixTensor, FloatTensor, or numpy.ndarray) – Input data. A FloatTensor or NumPy array is interpreted as a single point cloud (one row per point). A DistanceMatrix or DistanceMatrixTensor provides precomputed pairwise distances directly; distance_type is ignored in that case.

• max_dim (int, optional) – Maximum homology dimension to compute, by default 1.

• distance_type (DistanceType, optional) – Distance metric for point cloud input, by default DistanceType.Euclidean. Ignored when the input is a distance matrix.

• complex_type (ComplexType, optional) – Simplicial complex type, by default ComplexType.VietorisRips.

• reduced (bool, optional) – If True, compute reduced homology (no essential H0 class). If False (default), an infinite bar [0, inf) is added to H0 representing the single connected component.

• verbose (bool, optional) – Show progress information, by default False.

Returns:

A tensor of barcodes.

Return type:

BarcodeTensor

barcode_summary

masspcf.persistence.barcode_summary.barcode_to_accumulated_persistence(bc: Barcode | BarcodeTensor, max_death: float = inf, verbose: bool = True)

Convert barcodes to accumulated persistence functions.

The accumulated persistence function (APF) is defined as

\[\mathrm{APF}(t) = \sum_{i=1}^{N} \ell_i \, \mathbf{1}_{m_i \leq t}\]

where \(N\) is the number of bars, \(\ell_i = d_i - b_i\) is the lifetime of bar \(i\), and \(m_i = (b_i + d_i) / 2\) is its midpoint [2].

When max_death is finite, only bars with \(d_i \leq\) max_death are included (Equation 2 in the paper).

Parameters:

• bc (Barcode or BarcodeTensor) – A single barcode or a tensor of barcodes.

• max_death (float, optional) – If finite, exclude bars whose death time exceeds this value. By default inf (all finite bars included).

• verbose (bool, optional) – Show progress information, by default False.

Returns:

A single Pcf if the input is a single Barcode, otherwise a PcfTensor with the same shape as the input.

Return type:

Pcf or PcfTensor

masspcf.persistence.barcode_summary.barcode_to_betti_curve(bc: Barcode | BarcodeTensor, verbose=False)

Convert barcodes to Betti curves.

The Betti curve is the PCF that counts, for each filtration value \(t \geq 0\), the number of bars alive at \(t\) (i.e., bars with birth \(\leq t <\) death) [3][4].

Parameters:

• bc (Barcode or BarcodeTensor) – A single barcode or a tensor of barcodes.

• verbose (bool, optional) – Show progress information, by default False.

Returns:

A single Pcf if the input is a single Barcode, otherwise a PcfTensor with the same shape as the input.

Return type:

Pcf or PcfTensor

masspcf.persistence.barcode_summary.barcode_to_stable_rank(bc: Barcode | BarcodeTensor, verbose=False)

Convert barcodes to stable rank functions.

The stable rank of a barcode is the PCF that counts, for each \(t \geq 0\), the number of bars with length (death minus birth) strictly greater than \(t\) [5].

Parameters:

• bc (Barcode or BarcodeTensor) – A single barcode or a tensor of barcodes.

• verbose (bool, optional) – Show progress information, by default False.

Returns:

A single Pcf if the input is a single Barcode, otherwise a PcfTensor with the same shape as the input.

Return type:

Pcf or PcfTensor

References

[1]

Ulrich Bauer. Ripser: efficient computation of Vietoris–Rips persistence barcodes. Journal of Applied and Computational Topology, 5:391–423, 2021. doi:10.1007/s41468-021-00071-5.

[2]

Christophe A. N. Biscio and Jesper Møller. The accumulated persistence function, a new useful functional summary statistic for topological data analysis, with a view to brain artery trees and spatial point process applications. Journal of Computational and Graphical Statistics, 28(3):671–681, 2019. doi:10.1080/10618600.2019.1573686.

[3]

Yuhei Umeda. Time series classification via topological data analysis. Information and Media Technologies, 12:228–239, 2017. doi:10.11185/imt.12.228.

[4]

Frédéric Chazal and Bertrand Michel. An introduction to topological data analysis: fundamental and practical aspects for data scientists. Frontiers in Artificial Intelligence, 2021. doi:10.3389/frai.2021.667963.

[5]

Wojciech Chachólski and Henri Riihimäki. Metrics and stabilization in one parameter persistence. SIAM Journal on Applied Algebra and Geometry, 4(1):69–98, 2020. doi:10.1137/19M1243932.