Plotting (gd.pl)¶

The plotting module provides functions for visualizing GEDI results, including embeddings, convergence metrics, and feature plots.

Embedding Plots¶

`embedding`	Plot GEDI embedding colored by various attributes.
`umap`	Plot GEDI UMAP embedding.
`pca`	Plot GEDI PCA embedding.

gedi2py.plotting.embedding(adata, *, basis='X_gedi_umap', color=None, layer=None, size=None, alpha=1.0, title=None, legend_loc='right margin', legend_fontsize=10, cmap='viridis', palette=None, frameon=False, ncols=4, wspace=0.4, show=None, save=None, ax=None, return_fig=False, **kwargs)[source]¶

Plot GEDI embedding colored by various attributes.

Parameters:

adata (AnnData) – Annotated data matrix.
basis (str, default: 'X_gedi_umap') – Key in adata.obsm for the embedding coordinates. Defaults to X_gedi_umap.
color (Union[str, Sequence[str], None], default: None) – Key(s) for annotation in adata.obs or gene names to color by. Can be a single key or a list of keys.
layer (str | None, default: None) – Layer to use for gene expression values.
size (float | None, default: None) – Point size. If None, automatically determined.
alpha (float, default: 1.0) – Point transparency (0-1).
title (Union[str, Sequence[str], None], default: None) – Panel title(s). If None, uses the color key(s).
legend_loc (str, default: 'right margin') – Location of the legend. Options: 'right margin', 'on data', 'best', 'upper right', etc.
legend_fontsize (int | float, default: 10) – Font size for legend text.
cmap (str, default: 'viridis') – Colormap for continuous variables.
palette (Union[str, Sequence[str], None], default: None) – Color palette for categorical variables.
frameon (bool, default: False) – Whether to show axis frame.
ncols (int, default: 4) – Number of columns for multi-panel plots.
wspace (float, default: 0.4) – Width space between panels.
show (bool | None, default: None) – If True, show the figure. If None, defaults to True unless save is specified.
save (str | None, default: None) – Path to save the figure.
ax (Axes | None, default: None) – Pre-existing axes for the plot. Only valid when color is a single key.
return_fig (bool, default: False) – If True, return the figure object.
**kwargs – Additional arguments passed to matplotlib.pyplot.scatter.

Returns:

If return_fig=True: Returns the Figure object
If ax is provided: Returns the Axes object
Otherwise: Returns None

Return type:

Depending on ``return_fig`` and ax

Examples

>>> import gedi2py as gd
>>> gd.tl.gedi(adata, batch_key="sample", n_latent=10)
>>> gd.tl.umap(adata)
>>> gd.pl.embedding(adata, color="cell_type")
>>> gd.pl.embedding(adata, color=["batch", "cell_type", "total_counts"])

Example

import gedi2py as gd
import matplotlib.pyplot as plt

# Basic embedding plot
gd.pl.embedding(adata, color="cell_type")

# Multiple colors
gd.pl.embedding(adata, color=["sample", "cell_type"], ncols=2)

# Customize appearance
gd.pl.embedding(
    adata,
    basis="X_gedi_umap",
    color="cell_type",
    size=10,
    alpha=0.8,
    palette="tab20",
    legend_loc="right margin",
    frameon=False,
)
plt.show()

gedi2py.plotting.umap(adata, *, color=None, key='gedi', **kwargs)[source]¶

Plot GEDI UMAP embedding.

Convenience wrapper for embedding() with basis='X_{key}_umap'.

See embedding() for full parameter documentation.

Return type:: Figure | Axes | list[Axes] | None

Convenience wrapper for embedding(basis="X_gedi_umap", ...).

gd.pl.umap(adata, color="sample")

gedi2py.plotting.pca(adata, *, color=None, components=(1, 2), key='gedi', **kwargs)[source]¶

Plot GEDI PCA embedding.

Parameters:

adata (AnnData) – Annotated data matrix.
color (Union[str, Sequence[str], None], default: None) – Key(s) for annotation to color by.
components (tuple[int, int], default: (1, 2)) – Which principal components to plot (1-indexed).
key (str, default: 'gedi') – Key prefix for GEDI results.
**kwargs – Additional arguments passed to embedding().

Return type:

Figure | Axes | list[Axes] | None

:param See embedding() for full parameter documentation.:

Convenience wrapper for embedding(basis="X_gedi_pca", ...).

gd.pl.pca(adata, color="sample")

Convergence Plots¶

`convergence`	Plot GEDI training convergence.
`loss`	Plot GEDI training loss (negative log-likelihood).

gedi2py.plotting.convergence(adata, *, which='all', key='gedi', log_scale=True, title=None, figsize=None, show=None, save=None, ax=None, return_fig=False)[source]¶

Plot GEDI training convergence.

Visualizes how model parameters evolved during training to assess convergence. Available metrics:

sigma2: Noise variance (should stabilize)
dZ: Change in metagenes Z per iteration
dA: Change in pathway coefficients A (if using pathway priors)
do: Change in offsets o

Parameters:

adata (AnnData) – Annotated data matrix with GEDI results.
which (Literal['sigma2', 'dZ', 'dA', 'do', 'all'], default: 'all') – Which convergence metric(s) to plot: - "sigma2": Only noise variance - "dZ": Only metagene changes - "dA": Only pathway coefficient changes - "do": Only offset changes - "all": All available metrics (default)
key (str, default: 'gedi') – Key in adata.uns where GEDI results are stored.
log_scale (bool, default: True) – If True, use log scale for y-axis (except sigma2).
title (str | None, default: None) – Plot title.
figsize (tuple[float, float] | None, default: None) – Figure size (width, height) in inches.
show (bool | None, default: None) – If True, show the figure.
save (str | None, default: None) – Path to save the figure.
ax (Axes | None, default: None) – Pre-existing axes for the plot. Only valid for single metric.
return_fig (bool, default: False) – If True, return the figure object.

Returns:

Depending on ``return_fig``

Return type:

Figure, Axes, or None.

Examples

>>> import gedi2py as gd
>>> gd.tl.gedi(adata, batch_key="sample", n_latent=10)
>>> gd.pl.convergence(adata)
>>> gd.pl.convergence(adata, which="sigma2", log_scale=False)

Example

# Plot all convergence metrics
gd.pl.convergence(adata, which="all")

# Plot specific metric
gd.pl.convergence(adata, which="sigma2", log_scale=True)

# Save figure
gd.pl.convergence(adata, save="convergence.png")

Available Metrics

sigma2: Noise variance
dZ: Change in Z matrix
dA: Change in A matrix
do: Change in offsets
all: All metrics in subplots

gedi2py.plotting.loss(adata, *, key='gedi', title='Training Loss', figsize=(6, 4), show=None, save=None, ax=None, return_fig=False)[source]¶

Plot GEDI training loss (negative log-likelihood).

Parameters:

adata (AnnData) – Annotated data matrix with GEDI results.
key (str, default: 'gedi') – Key in adata.uns where GEDI results are stored.
title (str, default: 'Training Loss') – Plot title.
figsize (tuple[float, float], default: (6, 4)) – Figure size.
show (bool | None, default: None) – If True, show the figure.
save (str | None, default: None) – Path to save the figure.
ax (Axes | None, default: None) – Pre-existing axes.
return_fig (bool, default: False) – If True, return the figure.

Returns:

Depending on ``return_fig``

Return type:

Figure, Axes, or None.

Plot the loss/objective function over iterations.

gd.pl.loss(adata, log_scale=False)

Feature Plots¶

`features`	Plot gene expression on GEDI embedding.
`metagenes`	Plot top genes per GEDI metagene (latent factor).
`dispersion`	Plot gene dispersion from GEDI model.
`variance_explained`	Plot variance explained by GEDI components.

gedi2py.plotting.features(adata, features, *, basis='X_gedi_umap', layer=None, cmap='viridis', vmin=None, vmax=None, size=None, alpha=1.0, ncols=4, figsize=None, show=None, save=None, return_fig=False)[source]¶

Plot gene expression on GEDI embedding.

Parameters:

adata (AnnData) – Annotated data matrix.
features (Union[str, Sequence[str]]) – Gene name(s) to plot.
basis (str, default: 'X_gedi_umap') – Key in adata.obsm for embedding coordinates.
layer (str | None, default: None) – Layer to use for expression values. If None, uses adata.X.
cmap (str, default: 'viridis') – Colormap for expression values.
vmin (float | None, default: None) – Minimum value for color scale.
vmax (float | None, default: None) – Maximum value for color scale.
size (float | None, default: None) – Point size. If None, automatically determined.
alpha (float, default: 1.0) – Point transparency.
ncols (int, default: 4) – Number of columns for multi-panel plots.
figsize (tuple[float, float] | None, default: None) – Figure size.
show (bool | None, default: None) – If True, show the figure.
save (str | None, default: None) – Path to save the figure.
return_fig (bool, default: False) – If True, return the figure.

Return type:

Figure if ``return_fig=True``, else ``None`.`

Examples

>>> import gedi2py as gd
>>> gd.pl.features(adata, ["CD4", "CD8A", "FOXP3"])

Example

# Plot marker genes
gd.pl.features(
    adata,
    features=["CD3D", "CD14", "MS4A1", "NKG7"],
    ncols=2,
)

# Use different colormap
gd.pl.features(
    adata,
    features="CD3D",
    cmap="RdBu_r",
    vmin=-2,
    vmax=2,
)

gedi2py.plotting.metagenes(adata, *, n_genes=10, key='gedi', figsize=None, show=None, save=None, return_fig=False)[source]¶

Plot top genes per GEDI metagene (latent factor).

Shows a heatmap of the top genes with highest loadings for each latent factor in the Z matrix.

Parameters:

adata (AnnData) – Annotated data matrix with GEDI results.
n_genes (int, default: 10) – Number of top genes to show per metagene.
key (str, default: 'gedi') – Key prefix for GEDI results.
figsize (tuple[float, float] | None, default: None) – Figure size.
show (bool | None, default: None) – If True, show the figure.
save (str | None, default: None) – Path to save the figure.
return_fig (bool, default: False) – If True, return the figure.

Return type:

Figure if ``return_fig=True``, else ``None`.`

Examples

>>> import gedi2py as gd
>>> gd.tl.gedi(adata, batch_key="sample", n_latent=10)
>>> gd.pl.metagenes(adata, n_genes=15)

Visualize metagene patterns across cells.

# Plot first 4 metagenes
gd.pl.metagenes(adata, metagenes=[0, 1, 2, 3], ncols=2)

gedi2py.plotting.dispersion(adata, *, key='gedi', n_top=20, log_scale=True, figsize=(10, 6), show=None, save=None, return_fig=False)[source]¶

Plot gene dispersion from GEDI model.

Visualizes the dispersion (variance/mean ratio) of genes, which can help identify highly variable genes.

Parameters:

adata (AnnData) – Annotated data matrix with GEDI dispersion computed.
key (str, default: 'gedi') – Key prefix for GEDI results.
n_top (int, default: 20) – Number of top dispersed genes to label.
log_scale (bool, default: True) – If True, use log scale for axes.
figsize (tuple[float, float], default: (10, 6)) – Figure size.
show (bool | None, default: None) – If True, show the figure.
save (str | None, default: None) – Path to save the figure.
return_fig (bool, default: False) – If True, return the figure.

Return type:

Figure if ``return_fig=True``, else ``None`.`

Examples

>>> import gedi2py as gd
>>> gd.tl.dispersion(adata)
>>> gd.pl.dispersion(adata, n_top=30)

Plot gene dispersion vs mean expression.

gd.pl.dispersion(adata, highlight_hvg=True)

gedi2py.plotting.variance_explained(adata, *, key='gedi', n_components=None, figsize=(8, 4), show=None, save=None, return_fig=False)[source]¶

Plot variance explained by GEDI components.

Shows the proportion of variance explained by each latent factor based on the SVD singular values.

Parameters:

adata (AnnData) – Annotated data matrix with GEDI SVD computed.
key (str, default: 'gedi') – Key prefix for GEDI results.
n_components (int | None, default: None) – Number of components to show. If None, shows all.
figsize (tuple[float, float], default: (8, 4)) – Figure size.
show (bool | None, default: None) – If True, show the figure.
save (str | None, default: None) – Path to save the figure.
return_fig (bool, default: False) – If True, return the figure.

Return type:

Figure if ``return_fig=True``, else ``None`.`

Examples

>>> import gedi2py as gd
>>> gd.tl.svd(adata)
>>> gd.pl.variance_explained(adata)

Plot variance explained by each latent factor.

# Bar plot of variance explained
gd.pl.variance_explained(adata)

# Cumulative variance
gd.pl.variance_explained(adata, cumulative=True)

Common Parameters¶

Most plotting functions share these parameters:

Parameter	Type	Description
show	bool \| None	Show the plot (default: True in interactive mode)
save	str \| None	Path to save the figure
ax	Axes \| None	Matplotlib axes to plot on
return_fig	bool	Return the Figure object instead of showing

Using with Matplotlib

import matplotlib.pyplot as plt

# Create custom figure
fig, axes = plt.subplots(1, 3, figsize=(15, 4))

gd.pl.umap(adata, color="sample", ax=axes[0], show=False)
gd.pl.umap(adata, color="cell_type", ax=axes[1], show=False)
gd.pl.convergence(adata, which="sigma2", ax=axes[2], show=False)

plt.tight_layout()
plt.savefig("analysis.png", dpi=300)
plt.show()