grassp.pl.pretty_embedding

pretty_embedding(adata, color=None, basis='X_umap', figsize=(8, 8), dpi=200, legend_fontsize=5, label_fontsize=12, label_stroke_width=0.0, label_stroke_color='darkgray', edge_frac=0.97, label_plot_lines=True, vector_text=True, **kwargs)

Create a publication-quality embedding plot with automatic label placement.

This function wraps scanpy’s embedding plot and adds automatically positioned labels along the convex hull boundary using a force-directed layout algorithm. Labels are placed to avoid overlap with each other and with data points.

Parameters:

adata AnnData

Annotated data matrix with embedding coordinates in .obsm[basis].

color str | None (default: None)

Categorical key in adata.obs to colour and label groups by. A single key only – the hull label pass places one label per category, so it has no meaning for a list of keys or for a continuous variable. If None, points are drawn in one colour and no labels are placed.

basis str (default: 'X_umap')

Key in .obsm for the embedding coordinates (e.g., ‘X_umap’, ‘X_pca’).

figsize tuple[float, float] (default: (8, 8))

Figure size as (width, height) in inches.

dpi int (default: 200)

Figure resolution in dots per inch.

legend_fontsize int (default: 5)

Font size for the legend. No legend is drawn by default (the hull labels replace it); this applies only if one is re-enabled by passing legend_loc through **kwargs.

label_fontsize int (default: 12)

Font size for cluster/group labels placed on the plot.

label_stroke_width float (default: 0.0)

Width of the white outline/stroke (halo) drawn around label text for readability. Default 0.0 (no halo) so that labels export as fully editable text in vector formats — a non-zero halo is drawn with a matplotlib path-effect, which outlines the label glyphs to vector paths and makes them no longer selectable/editable as text in Illustrator. Set a value like 1.0 if on-screen readability matters more than vector-text editability.

label_stroke_color str (default: 'darkgray')

Color of the outline/stroke (halo) around label text. Only used when label_stroke_width is non-zero.

edge_frac float (default: 0.97)

Controls how close to the convex hull edge labels are placed (0-1). Higher values place labels closer to the edge.

label_plot_lines bool (default: True)

Whether to draw connector lines (arrows) from labels to cluster centroids.

vector_text bool (default: True)

If True (default), set matplotlib’s rcParams so that text in vector exports (PDF/EPS/SVG) stays as editable TrueType text rather than Type-3 fonts or outlined paths — i.e. selectable and editable when the figure is opened in Illustrator. This updates the global rcParams (needed because they are read at savefig time, after this function returns).

**kwargs

Additional keyword arguments passed to sc.pl.embedding(). The defaults this function sets – legend_loc, frameon and add_outline – can be overridden here.

Return type:

Axes

Returns:

Matplotlib axes object containing the plot.

Examples

>>> import grassp as gr
>>> adata = gr.ds.itzhak_2016()
>>> gr.pl.pretty_embedding(adata, color="compartment")