ggml_ot.pl.embedding

ggml_ot.pl.embedding(distances, labels, *, method='umap', precomputed_emb=None, symbols=None, ax=None, cluster_ID=None, title='Embedding', cmap='Set2', legend='auto', s=200, hue_order=None, annotation=None, linewidth=0.02, annotation_image_path=None, return_embedding=False, show=None, save=None, **kwargs)

Plot a 2-D embedding of a precomputed distance matrix.

Parameters:

distances array-like

Distance matrix of shape (n_samples, n_samples).

labels array-like

Class labels used for colouring the points.

method str, default "umap"

Dimensionality-reduction method. One of "umap", "tsne", "diffusion", "fast_diffusion", "mds".

precomputed_emb array-like or None, default None

Precomputed 2-D coordinates of shape (n_samples, 2). When provided, method is ignored.

symbols array-like or None, default None

Labels used for marker styles.

ax matplotlib.axes.Axes or None, default None

Axes to draw on. A new figure is created when None.

cluster_ID array-like of bool or None, default None

Flags indicating centroid / medoid / representative points.

title str or None, default "Embedding"

Plot title.

cmap str, dict, or colormap, default "Set2"

Colour palette for the scatter plot.

legend str, default "auto"

Legend placement. One of "auto", "Side"/"right", "left", "Top", "Bottom", "Inside", or False.

s int, default 200

Marker size.

hue_order array-like or None, default None

Custom legend ordering of class labels.

annotation array-like of str or None, default None

Text annotations displayed on each point.

linewidth float, default 0.02

Edge width of scatter markers.

annotation_image_path array-like of str or None, default None

Image paths to overlay on the plot.

return_embedding bool, default False

If True, return (ax, embedding) instead of just ax.

show bool or None, default None

Whether to display the plot. None (default) automatically shows in interactive environments (notebooks, IPython) and suppresses in scripts. True/False override explicitly.

save str, bool, or None, default None

Whether to save the figure to disk. None/False skip saving. True saves to settings.figdir/embedding.<figformat>; a str overrides the filename.

Returns:

matplotlib.axes.Axes

The axes containing the embedding plot (when return_embedding=False).

tuple[matplotlib.axes.Axes, numpy.ndarray]

(ax, embedding) when return_embedding=True.

Notes

Computes a 2-D layout from a precomputed distance matrix using the chosen dimensionality-reduction method and renders a scatter plot coloured by labels. This is the main function behind ggml_ot.pl.embedding and is used by the benchmark evaluation helpers to visualise OT distances between patients.

Supported methods: "umap" (default, adaptive n_neighbors), "tsne", "mds", "diffusion", "fast_diffusion".