oineus.wasserstein_matching

oineus.wasserstein_matching(dgm_1, dgm_2, *, q=2.0, delta=0.01, internal_p=inf, ignore_inf_points=True)[source]

Compute the optimal q-Wasserstein matching between two persistence diagrams.

Parameters:

  • dgm_1 (array-like or list[DiagramPoint]) – Single-dimension persistence diagrams: a (n_points, 2) numpy array of (birth, death), or a list[DiagramPoint]. To pass an oineus.Diagrams object, extract the dimension first via dgm.in_dimension(d).

  • dgm_2 (array-like or list[DiagramPoint]) – Single-dimension persistence diagrams: a (n_points, 2) numpy array of (birth, death), or a list[DiagramPoint]. To pass an oineus.Diagrams object, extract the dimension first via dgm.in_dimension(d).

  • q (float, default 2.0) – Wasserstein exponent. distance == cost ** (1/q).

  • delta (float, default 0.01) – Relative error parameter for Hera. Must be strictly positive (the auction has no exact mode).

  • internal_p (float, default np.inf) – Ground metric in the (birth, death) plane. np.inf selects the L_infinity norm.

  • ignore_inf_points (bool, default True) – If True, essential (infinite-coordinate) points are dropped. If False, each of the four essential families must have equal cardinality on both sides; otherwise ValueError is raised.

Returns:

Matching object with attributes finite_to_finite (ndarray (n, 2)), a_to_diagonal, b_to_diagonal (1-D ndarrays), essential (an EssentialMatches grouped view) and the scalar distance, cost fields.

Return type:

DiagramMatching

Raises:

ValueError – If essential cardinalities differ in any of the four families when ignore_inf_points=False.

Examples

>>> import numpy as np
>>> import oineus
>>> dgm_a = np.array([[0.0, 1.0], [0.5, 2.0]])
>>> dgm_b = np.array([[0.1, 0.9], [0.6, 1.8]])
>>> m = oineus.wasserstein_matching(dgm_a, dgm_b, q=2.0)
>>> m.finite_to_finite.tolist()
[[0, 0], [1, 1]]

>>> dgm_a = np.array([[0.0, 1.0], [0.5, np.inf]])
>>> dgm_b = np.array([[0.1, 0.9], [0.6, np.inf]])
>>> m = oineus.wasserstein_matching(dgm_a, dgm_b, ignore_inf_points=False)
>>> m.essential.inf_death.tolist()
[[1, 1]]
>>> m.essential[oineus.InfKind.INF_DEATH].tolist()
[[1, 1]]