API Reference

Plotting

plot_density

pynebulosa.plot_density(adata, features, *, joint=False, reduction=None, layer=None, dims=(0, 1), method='wkde', adjust=1.0, size=1.0, cmap='viridis', figsize=None, ncols=3, show=None, save=None, ax=None)[source]

Plot gene-weighted 2D kernel density.

Main user-facing function. Port of R’s plot_density() generic.

Creates scatter plots of cell embeddings colored by gene-weighted kernel density estimates. For multiple features, creates a grid of subplots. When joint=True, appends a panel showing the product of individual densities.

Parameters:

  • adata (AnnData) – AnnData object with computed dimensionality reduction.

  • features (str | list[str]) – Gene name(s) or obs column name(s) to visualize.

  • joint (bool) – If True and multiple features are given, append a joint density plot (product of individual densities).

  • reduction (str | None) – Key in adata.obsm (e.g. "X_umap"). Auto-detected if None.

  • layer (str | None) – Layer in adata.layers for expression data. Uses adata.X if None.

  • dims (tuple[int, int]) – 0-indexed dimension pair to plot. Default: (0, 1).

  • method (str) – KDE method: "wkde" (custom weighted KDE) or "ks" (scipy gaussian_kde with weights).

  • adjust (float) – Bandwidth adjustment factor.

  • size (float) – Point size for scatter plot.

  • cmap (str) – Matplotlib colormap name. Default: "viridis".

  • figsize (tuple[float, float] | None) – Figure size (width, height) in inches.

  • ncols (int) – Number of columns for multi-panel layout.

  • show (bool | None) – Show the plot. If None, uses matplotlib’s default.

  • save (str | None) – Path to save the figure.

  • ax (matplotlib.axes.Axes | None) – Pre-existing axes (only for single-feature plots).

Returns:

  • For a single feature with *ax* provided (the Axes.)

  • For multiple features or when creating a new figure (the Figure.)

  • Returns None when show=True.

Return type:

matplotlib.figure.Figure | matplotlib.axes.Axes | None

Examples

>>> import scanpy as sc
>>> import pynebulosa as nb
>>> adata = sc.datasets.pbmc3k_processed()
>>> nb.plot_density(adata, "CD4")
>>> nb.plot_density(adata, ["CD8A", "CCR7"], joint=True)

Density estimation

calculate_density

pynebulosa.calculate_density(w, coords, method='wkde', adjust=1.0, map_to_cells=True)[source]

Estimate weighted kernel density.

Port of the R function Nebulosa:::calculate_density.

Parameters:

  • w (ndarray) – Weight vector (e.g. gene expression), length N.

  • coords (ndarray) – 2D coordinates (e.g. UMAP embedding), shape (N, 2).

  • method (Literal['wkde', 'ks']) – KDE method: "wkde" (custom weighted KDE) or "ks" (scipy’s gaussian_kde with weights).

  • adjust (float) – Bandwidth adjustment factor (only for "wkde").

  • map_to_cells (bool) – If True, return per-cell density values. If False, return the raw density estimation result.

Returns:

  • If map_to_cells is True, a 1D array of density values (length N).

  • If map_to_cells is False, a dict (for "wkde") or

  • gaussian_kde object (for "ks").

Return type:

ndarray | dict

wkde2d

pynebulosa.wkde2d(x, y, w, h=None, adjust=1.0, n=100, lims=None)[source]

Weighted 2D kernel density estimation.

Direct port of the R function Nebulosa:::wkde2d.

Parameters:

  • x (ndarray) – 1D array of coordinates for dimension 1 (N cells).

  • y (ndarray) – 1D array of coordinates for dimension 2 (N cells).

  • w (ndarray) – 1D array of weights (e.g. gene expression values).

  • h (tuple[float, float] | None) – Bandwidths for x and y directions. If None, computed automatically using Silverman’s rule.

  • adjust (float) – Bandwidth adjustment factor. Default: 1.0.

  • n (int) – Number of grid points in each direction. Default: 100.

  • lims (tuple[float, float, float, float] | None) – Grid limits as (x_min, x_max, y_min, y_max). If None, uses data range.

Returns:

  • Dictionary with keys "x", "y" (grid coordinates, each

  • length n) and "z" (density matrix, shape (n, n)).

Return type:

dict