ggml_ot.pl.embedding

Contents

ggml_ot.pl.embedding#

ggml_ot.pl.embedding(distances, labels, *, method=None, precomputed_emb=None, symbols=None, ax=None, cluster_ID=None, title=None, cmap=None, legend='auto', s=200, hue_order=None, annotation=None, linewidth=0.02, annotation_image_path=None, label_type='categorical', return_embedding=False, show=None, save=None, **kwargs)[source]#

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 or None, default None

Dimensionality-reduction method. One of "umap", "tsne", "diffusion", "fast_diffusion", "mds". When None, defaults to "umap".

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 None

Subplot title. None resolves to "Embedding (<method>)" using the resolved method (e.g. "Embedding (UMAP)", "Embedding (Diffusion)"). Pass an empty string to suppress.

cmap str, dict, colormap, or None, default None

Colour palette for the scatter plot. None falls back to "Set2".

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.

label_type {“categorical”}, default "categorical"

How to colour the scatter (discrete palette). Only "categorical" is supported in this stable release.

return_embedding bool, default False

If True, return (ax, embedding) regardless of show.

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 or None

The axes if the plot is not shown; otherwise None.

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". UMAP, t-SNE, and MDS use ggml_ot.settings.random_seed for reproducibility. Set it to None for nondeterministic embeddings.