oineus.plot_diagram

oineus.plot_diagram(diagrams, ax=None, *, color=None, cmap=None, log_x=False, log_y=False, title=None, suptitle=None, axis_bounds=None, dims=None, max_dimension=None, scatter_only=True, density_threshold=20000, near_diagonal_fraction=0.03, density_style=None, inf_line_margin=0.05, point_style=None, inf_point_style=None, diagonal_style=None, inf_line_style=None, grid_style=None, dim_label_fmt='H{dim}', use_density=<object object>)[source]

Plot one or more persistence diagrams.

Default rendering is pure scatter: every finite point gets its own marker, so the visual density of overlapping markers faithfully tracks the actual point density. Pass scatter_only=False to opt into the hybrid density-bulk + outlier-scatter mode (suitable for very large diagrams where the near-diagonal noise band saturates the scatter). In that hybrid mode the bulk near the diagonal is rendered as a 2D density (via mpl_scatter_density) while points further than near_diagonal_fraction of the axis range from the diagonal are still drawn as crisp scatter, so high-persistence (topologically meaningful) features are never aggregated.

Color of the diagram points is taken from the top-level color argument: pass a single color ("red", "#012345", (r, g, b[, a])) to override every dim, a dict mapping dim -> color, or a list cycled through dims in sort order. None (default) leaves the choice to matplotlib’s per-call cycle. Passing a single color when the input has more than one dim emits a UserWarning.

When color is set and density mode is active, the density artist uses a single-hue fade-to-transparent ramp keyed off color rather than the cmap-based default; this is what makes 2-diagram overlays of the form plot_diagram(dgm_a, color="C0"); plot_diagram(dgm_b, color="C1") on the same axes read as two distinct distributions.

cmap is forwarded to the density-aggregation path when color is None; pass None to keep the default (viridis).

Style-dict kwargs (point_style, inf_point_style, diagonal_style, inf_line_style, density_style) default to copies of the module-level DEFAULT_*_STYLE dicts and no longer carry a color / c key. inf_point_style controls the markers placed on the horizontal inf-line (death = +-inf); the default uses an upward triangle so essentials read distinctly from finite points.

The use_density kwarg is deprecated; pass scatter_only instead. use_density=False corresponds to scatter_only=True and vice versa.

Parameters:

  • log_x (bool)

  • log_y (bool)

  • title (str | None)

  • suptitle (str | None)

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

  • dims (Iterable[int] | None)

  • max_dimension (int | None)

  • scatter_only (bool)

  • density_threshold (int)

  • near_diagonal_fraction (float)

  • density_style (dict | None)

  • inf_line_margin (float)

  • point_style (dict | None)

  • inf_point_style (dict | None)

  • diagonal_style (dict | None)

  • inf_line_style (dict | None)

  • grid_style (dict | bool | None)

  • dim_label_fmt (str)