topo.eval.rmetric

Attributes

plt

_HAVE_SK

Classes

RiemannMetric

Functions

_ensure_array(A)

_symmetrize(L)

_center(Y)

riemann_metric(Y, laplacian[, n_dim])

eigsorted(cov)

_project_spd(Gi[, eps, norm])

_ellipse_from_G(Gi[, scale, eps])

_scaling_values(G[, mode, eps])

_prepare_colors(c, n[, cmap, vmin, vmax, default_alpha])

plot_riemann_metric_localized(Y, L[, G_emb, n_plot, ...])

Plot localized Riemannian indicatrices (ellipses) over a 2-D embedding.

plot_riemann_metric_global(Y, L[, G_emb, grid_res, ...])

Plot grid-averaged Riemannian indicatrices over a 2-D embedding.

calculate_deformation(Y, L[, G_emb, center, use_dual, ...])

Compute a per-point contraction/expansion scalar from the embedding metric.

plot_metric_contraction_expansion(Y, L[, G_emb, ...])

Scatter plot of local contraction/expansion over a 2-D embedding.

get_eccentricity(emb, laplacian[, G_emb])

Module Contents

topo.eval.rmetric.plt = None
topo.eval.rmetric._HAVE_SK = True
topo.eval.rmetric._ensure_array(A)
topo.eval.rmetric._symmetrize(L)
topo.eval.rmetric._center(Y)
topo.eval.rmetric.riemann_metric(Y, laplacian, n_dim=None)
class topo.eval.rmetric.RiemannMetric(Y, L)
Y
L
mdimG
get_dual_rmetric(invert_h=False)
get_rmetric(return_svd=False)
get_mdimG()
get_detG(use_log=True)
fit(Y, L=None)
transform(Y, L=None)
topo.eval.rmetric.eigsorted(cov)
topo.eval.rmetric._project_spd(Gi, eps=1e-08, norm='trace')
topo.eval.rmetric._ellipse_from_G(Gi, scale=1.0, eps=1e-08)
topo.eval.rmetric._scaling_values(G, mode='anisotropy', eps=1e-08)
topo.eval.rmetric._prepare_colors(c, n, cmap='viridis', vmin=None, vmax=None, default_alpha=None)
topo.eval.rmetric.plot_riemann_metric_localized(Y, L, G_emb=None, n_plot=1500, scale_mode='anisotropy', scale_gain=1.0, scale_base='auto', alpha=None, edgecolor=None, facecolor=None, ax=None, seed=7, zorder=2, show_points=True, colors=None, cmap='viridis', vmin=None, vmax=None, point_alpha=0.6, ellipse_alpha=None, point_size=6, scatter_kw=None)

Plot localized Riemannian indicatrices (ellipses) over a 2-D embedding.

Each selected point i is annotated with an ellipse derived from the local metric G[i] (eigenpairs → axes & orientation). Ellipse sizes are scaled to remain within current axes limits (rotation-safe circumscribed-circle bound). Optional per-sample colors control both the point color and the ellipse color.

Parameters:

  • Y ((n, 2) array-like) – 2-D embedding coordinates.

  • L ((n, n) array-like or sparse matrix) – Graph Laplacian (will be symmetrized). Used only if G_emb is None.

  • G_emb ((n, 2, 2) array-like, optional) – Precomputed embedding-space Riemann metric per point. If None, computed from (Y, L).

  • n_plot (int, default 1500) – Number of points for which to draw ellipses (uniform random subset).

  • scale_mode ({"anisotropy","trace","det","none"}, default "anisotropy") – How to derive a per-point scalar factor from G to modulate ellipse axes (passed to _scaling_values).

  • scale_gain (float, default 1.0) – Global multiplicative scale factor for ellipse axes.

  • scale_base ({"auto"} or float, default "auto") – Base axis scale in embedding units; “auto” uses 5% of the largest span.

  • alpha (float, optional) – Global alpha for filled ellipses when colors is not provided.

  • edgecolor (color, optional) – Ellipse edge color. Defaults to “k”.

  • facecolor (color, optional) – Ellipse face color when colors is not provided. Defaults to “C0”.

  • ax (matplotlib.axes.Axes, optional) – Target axes. If None, uses current axes.

  • seed (int, default 7) – RNG seed for selecting the subset of points to annotate.

  • zorder (int, default 2) – Z-order for ellipses; points are drawn at zorder-2.

  • show_points (bool, default True) – Whether to scatter the raw embedding points.

  • colors (array-like, optional) – Per-sample colors (numeric, categorical, or matplotlib color specs). If numeric, cmap, vmin, vmax apply. Drives both points & ellipses.

  • cmap (str or Colormap, default "viridis") – Colormap for numeric colors.

  • vmin (float, optional) – Color scaling limits for numeric colors.

  • vmax (float, optional) – Color scaling limits for numeric colors.

  • point_alpha (float, default 0.6) – Alpha for the scatter points.

  • ellipse_alpha (float, optional) – Alpha for filled ellipses. If None and colors is provided, the fill inherits the point alpha while edges remain opaque.

  • point_size (float, default 6) – Marker size for scatter points.

  • scatter_kw (dict, optional) – Extra kwargs forwarded to ax.scatter.

Returns:

ax (matplotlib.axes.Axes) – The axes with the plot.

Notes

  • The embedding is centered before plotting.

  • Ellipses are clipped to remain within axes limits via a conservative circumscribed-circle scaling.

topo.eval.rmetric.plot_riemann_metric_global(Y, L, G_emb=None, grid_res=20, k_avg=16, scale_mode='anisotropy', scale_gain=1.0, scale_base='auto', alpha=0.35, edgecolor='k', cmap='coolwarm', vmin=None, vmax=None, ax=None, zorder=3, show_points=True, point_alpha=0.25, point_size=4, scatter_kw=None, min_sep_factor=0.9, choose_strong_first=True, deformation_vals=None, deformation_kwargs=None, respect_existing_limits=True)

Plot grid-averaged Riemannian indicatrices over a 2-D embedding.

Builds a regular grid over the embedding extent, averages the local metric G over the k nearest embedded points per grid site, and draws one ellipse per selected site. A thinning step enforces a minimum center separation to limit overlap. Ellipse face colors encode local contraction/expansion via a centered log-determinant scalar field (computed or provided).

Parameters:

  • Y ((n, 2) array-like) – 2-D embedding coordinates.

  • L ((n, n) array-like or sparse matrix) – Graph Laplacian (symmetrized). Used if G_emb is None and to compute deformation when deformation_vals is None.

  • G_emb ((n, 2, 2) array-like, optional) – Precomputed embedding-space Riemann metric per point. If None, computed from (Y, L).

  • grid_res (int, default 20) – Number of grid steps along each axis.

  • k_avg (int, default 16) – Number of nearest embedded points to average per grid site.

  • scale_mode ({"anisotropy","trace","det","none"}, default "anisotropy") – Per-site axis modulation strategy (see _scaling_values).

  • scale_gain (float, default 1.0) – Global multiplicative scale for ellipse axes.

  • scale_base ({"auto"} or float, default "auto") – Base axis scale in embedding units; “auto” uses 5% of the largest span.

  • alpha (float, default 0.35) – Ellipse face alpha.

  • edgecolor (color, default "k") – Ellipse edge color.

  • cmap (str or Colormap, default "coolwarm") – Colormap for contraction/expansion.

  • vmin (float, optional) – Fixed color limits. If None, inferred symmetrically from the field.

  • vmax (float, optional) – Fixed color limits. If None, inferred symmetrically from the field.

  • ax (matplotlib.axes.Axes, optional) – Target axes. If None, uses current axes.

  • zorder (int, default 3) – Z-order for the ellipses; points are drawn at zorder-3.

  • show_points (bool, default True) – Whether to draw background scatter of embedded points.

  • point_alpha (float, default 0.25) – Alpha for background scatter.

  • point_size (float, default 4) – Size for background scatter points.

  • scatter_kw (dict, optional) – Extra kwargs to forward to ax.scatter.

  • min_sep_factor (float, default 0.9) – Minimum center separation as a fraction of scale_base for thinning.

  • choose_strong_first (bool, default True) – If True, greedy selection prefers grid sites with larger |deformation|.

  • deformation_vals ((n,) array-like, optional) – Precomputed contraction/expansion scalar per point (centered log det). If None, computed by calculate_deformation(…).

  • deformation_kwargs (dict, optional) – Extra kwargs forwarded to calculate_deformation when deformation_vals is None.

  • respect_existing_limits (bool, default True) – If True, reuse existing axes limits when not at default (0,1); otherwise derive from the embedding extent.

Returns:

ax (matplotlib.axes.Axes) – The axes with the plot.

Notes

  • Ellipses are scaled so their circumscribed circle fits within the axes box.

  • The deformation field is averaged over k_avg neighbors per grid site.

topo.eval.rmetric.calculate_deformation(Y, L, G_emb=None, center='median', use_dual=False, diffusion_t=0, diffusion_op=None, re_center_after_diffusion=True, clip_percentile=1.0, normalize='symmetric', return_limits=True)

Compute a per-point contraction/expansion scalar from the embedding metric.

The scalar is the centered log-determinant of the local metric:

val_i = log det(G_i) − center, with optional diffusion smoothing.

If use_dual=True, treats the input as the dual metric H and returns

val_i = −log det(H_i) − center (equivalently, minus the log-det).

Parameters:

  • Y ((n, 2) array-like) – 2-D embedding coordinates.

  • L ((n, n) array-like or sparse matrix) – Graph Laplacian (symmetrized). Used if G_emb is None and to build a diffusion operator when diffusion_t > 0 and diffusion_op is None.

  • G_emb ((n, 2, 2) array-like, optional) – Precomputed embedding-space Riemann metric per point. If None, computed from (Y, L).

  • center ({"median","mean"} or float, default "median") – How to center the log-det values (robust median, mean, or explicit value).

  • use_dual (bool, default False) – If True, compute −log det(H) instead of log det(G).

  • diffusion_t (int, default 0) – Number of steps of diffusion smoothing on the scalar field.

  • diffusion_op ((n, n) array-like, optional) – Markov operator P for smoothing. If None and diffusion_t>0, a random-walk operator is built from L.

  • re_center_after_diffusion (bool, default True) – If True, re-apply centering after diffusion smoothing.

  • clip_percentile (float, default 2.0) – Percentile for robust clipping used to derive display limits.

  • normalize ({"symmetric","none"}, default "symmetric") – If “symmetric”, color limits are ±max(|clipped vals|); otherwise [lo, hi].

  • return_limits (bool, default True) – If True, also return effective (vmin, vmax) for plotting.

Returns:

  • vals ((n,) ndarray) – Centered (and optionally smoothed) log-det scalar per sample.

  • (vmin, vmax) (tuple of float) – Effective color limits (only if return_limits=True).

Notes

  • Eigenvalues are clipped away from 0 before taking logs for numerical stability.

  • When building P from L, a random-walk normalization (row-stochastic) is used.

topo.eval.rmetric.plot_metric_contraction_expansion(Y, L, G_emb=None, center='median', normalize='symmetric', clip_percentile=2.0, s=6, alpha=0.9, cmap='coolwarm', vmin=None, vmax=None, show_colorbar=True, ax=None, zorder=1, use_dual=False, diffusion_t=0, diffusion_op=None, re_center_after_diffusion=True, plot_strong_last=True, legend_fontsize=9, title='Local contraction / expansion', title_fontsize=11)

Scatter plot of local contraction/expansion over a 2-D embedding.

Colors are the centered log-determinant of the (dual) metric at each point, optionally smoothed by diffusion. Points with strongest magnitude can be drawn last to emphasize structure.

Parameters:

  • Y ((n, 2) array-like) – 2-D embedding coordinates.

  • L ((n, n) array-like or sparse matrix) – Graph Laplacian (symmetrized). Used to compute the metric and, if needed, a diffusion operator.

  • G_emb ((n, 2, 2) array-like, optional) – Precomputed embedding-space Riemann metric per point. If None, computed from (Y, L).

  • center ({"median","mean"} or float, default "median") – How to center the log-det values before coloring.

  • normalize ({"symmetric","none"}, default "symmetric") – Color normalization for auto limits (±max vs. [lo, hi]).

  • clip_percentile (float, default 2.0) – Percentile used for robust limit derivation.

  • s (float, default 6) – Marker size.

  • alpha (float, default 0.9) – Marker alpha.

  • cmap (str or Colormap, default "coolwarm") – Colormap for the scalar field.

  • vmin (float, optional) – Fixed color limits; if None, computed from data.

  • vmax (float, optional) – Fixed color limits; if None, computed from data.

  • show_colorbar (bool, default True) – Whether to draw a colorbar.

  • ax (matplotlib.axes.Axes, optional) – Target axes. If None, uses current axes.

  • zorder (int, default 1) – Z-order of the scatter.

  • use_dual (bool, default False) – If True, color by −log det(H) (dual metric).

  • diffusion_t (int, default 0) – Number of steps of diffusion smoothing on the scalar field.

  • diffusion_op ((n, n) array-like, optional) – Markov operator P for smoothing. If None and diffusion_t>0, built from L.

  • re_center_after_diffusion (bool, default True) – Re-apply centering after smoothing.

  • plot_strong_last (bool, default True) – If True, draw largest |values| last to improve visual prominence.

  • legend_fontsize (float, default 9) – Font size for the colorbar label.

  • title (str, default "Local contraction / expansion") – Figure title.

  • title_fontsize (float, default 11) – Font size for the title.

Returns:

  • ax (matplotlib.axes.Axes) – The axes with the scatter.

  • vals ((n,) ndarray) – The centered (and optionally smoothed) log-det values used for coloring.

Notes

  • Axes limits are padded by 6% of the embedding span and aspect is set to 1:1.

topo.eval.rmetric.get_eccentricity(emb, laplacian, G_emb=None)