oineus.plot_matching

oineus.plot_matching(dgm_a, dgm_b, matching, ax=None, *, plot_finite_to_finite=None, plot_a_to_diagonal=None, plot_b_to_diagonal=None, plot_essential=None, highlight_longest=None, plot_points=True, plot_diagonal_projections=False, plot_diagonal=True, scatter_only=True, density_threshold=20000, near_diagonal_fraction=0.03, edge_quantile=0.99, min_persistence=None, top_k_pairs=None, pair_filter='either', pair_overlay_threshold=1000, color_dgm_a=None, color_dgm_b=None, match_color=None, cmap_a=None, cmap_b=None, density_style=None, dgm_a_point_style=None, dgm_b_point_style=None, ordinary_edge_style=None, longest_edge_style=None, diagonal_style=None, diagonal_projection_a_style=None, diagonal_projection_b_style=None, inf_line_style=None, dgm_a_label='Diagram A', dgm_b_label='Diagram B', title=None, axis_bounds=None, inf_line_margin=0.05, use_density=<object object>)[source]

Plot a matching between two persistence diagrams.

Color of the per-side scatter is controlled by color_dgm_a and color_dgm_b (single colors; None uses DEFAULT_DIAGRAM_A_COLOR / DEFAULT_DIAGRAM_B_COLOR). The matching edges use match_color (single color; None uses DEFAULT_MATCHING_EDGE_COLOR). Per-side density colormaps are cmap_a and cmap_b; None keeps the monochromatic-fade-from-color default driven by the side’s color.

Dispatches on matching type: for Wasserstein (DiagramMatching) all edge categories are drawn by default; for BottleneckMatching only finite-to-finite edges are drawn and the longest edge(s) are overlaid in the highlight style.

dgm_a and dgm_b must be 2D numpy arrays (one homology dimension).

Edge filtering. Three knobs, applied in order:

  • min_persistence: drop edges where neither (or both, if pair_filter='both') endpoint has persistence death - birth >= min_persistence. Default None (no filter).

  • top_k_pairs: keep only the K edges with the largest endpoint persistence. When unset and the total ordinary-edge count is at least pair_overlay_threshold (default 1000), defaults to 200 and emits a UserWarning listing the cap.

  • edge_quantile: legacy length-based filter, only active when scatter_only=False (i.e. density mode). Kept for back-compat; min_persistence / top_k_pairs are the recommended controls.

With scatter_only=False (opt-in density mode) the diagram is rendered as a density background (near-diagonal points only) plus crisp scatter for high-persistence outliers; the edge_quantile filter then runs in addition.

The use_density kwarg is deprecated; pass scatter_only instead (semantics inverted).

Parameters:

  • plot_finite_to_finite (bool | None)

  • plot_a_to_diagonal (bool | None)

  • plot_b_to_diagonal (bool | None)

  • plot_essential (bool | None)

  • highlight_longest (bool | None)

  • plot_points (bool)

  • plot_diagonal_projections (bool)

  • plot_diagonal (bool)

  • scatter_only (bool)

  • density_threshold (int)

  • near_diagonal_fraction (float)

  • edge_quantile (float)

  • min_persistence (float | None)

  • top_k_pairs (int | None)

  • pair_filter (str)

  • pair_overlay_threshold (int)

  • density_style (dict | None)

  • dgm_a_point_style (dict | None)

  • dgm_b_point_style (dict | None)

  • ordinary_edge_style (dict | None)

  • longest_edge_style (dict | None)

  • diagonal_style (dict | None)

  • diagonal_projection_a_style (dict | None)

  • diagonal_projection_b_style (dict | None)

  • inf_line_style (dict | None)

  • dgm_a_label (str)

  • dgm_b_label (str)

  • title (str | None)

  • axis_bounds (Mapping[str, float] | None)

  • inf_line_margin (float)