Pass docs

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning][].
 
 ### Fixed
 
-- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
+- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
 
 ## [0.2.0] - 2024-03-24
 

src/spatialdata_plot/pl/basic.py

@@ -150,10 +150,10 @@ def _copy(
  def render_shapes(
  self,
  elements: list[str] | str | None = None,
- color: str | None = None,
+ color: list[str | None] | str | None = None,
  fill_alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  outline: bool = False,
  outline_width: float | int = 1.5,
@@ -173,17 +173,29 @@ def render_shapes(
  elements : list[str] | str | None, optional
  The name(s) of the shapes element(s) to render. If `None`, all shapes
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  fill_alpha : float | int, default 1.0
- Alpha value for the fill of shapes.
- groups : list[str] | str | None, optional
+ Alpha value for the fill of shapes. If the alpha channel is present in a cmap passed by the
+ user, this value will multiply the value present in the cmap.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -274,8 +286,8 @@ def render_points(
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
  alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  cmap: Colormap | str | None = None,
  norm: None | Normalize = None,
@@ -291,17 +303,28 @@ def render_points(
  elements : list[str] | str | None, optional
  The name(s) of the points element(s) to render. If `None`, all points
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  alpha : float | int, default 1.0
  Alpha value for the points.
- groups : list[str] | str | None, optional
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -374,7 +397,7 @@ def render_images(
  cmap: list[Colormap] | Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
- palette: list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  alpha: float | int = 1.0,
  quantiles_for_norm: tuple[float | None, float | None] | None = None,
  scale: list[str] | str | None = None,
@@ -400,6 +423,11 @@ def render_images(
  Applies to all channels if set.
  na_color : ColorLike | None, default (0.0, 0.0, 0.0, 0.0)
  Color to be used for NA values. Accepts color-like values (string, hex, RGB(A)).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette to color images. In the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list contains the string
+ indicating the palette to be used. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  alpha : float | int, default 1.0
  Alpha value for the images. Must be a numeric between 0 and 1.
  quantiles_for_norm : tuple[float | None, float | None] | None, optional
@@ -476,10 +504,10 @@ def render_labels(
  self,
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
- groups: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
  contour_px: int = 3,
  outline: bool = False,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  cmap: Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
@@ -497,19 +525,31 @@ def render_labels(
  elements : list[str] | str | None, optional
  The name(s) of the label element(s) to render. If `None`, all label
  elements in the `SpatialData` object will be used.
- color : str | None, optional
- Key for annotations in :attr:`anndata.AnnData.obs` or variables/genes.
- groups : list[str] | str | None, optional
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette for discrete annotations. List of valid color names that should be
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  contour_px : int, default 3
  Draw contour of specified width for each segment. If `None`, fills
  entire segment, see :func:`skimage.morphology.erosion`.
  outline : bool, default False
  Whether to plot boundaries around segmentation masks.
- palette : list[str] | str | None, optional
- Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
  cmap : Colormap | str | None, optional
  Colormap for continuous annotations, see :class:`matplotlib.colors.Colormap`.
  norm : Normalize | None, optional
@@ -529,6 +569,10 @@ def render_labels(
  3) "full": render the full image without rasterization. In the case of a multiscale image, the scale
  with the highest resolution is selected. This can lead to long computing times for large images!
  4) List that is matched to the list of elements (can contain `None`, scale names or "full").
+ table_name:
+ Name of the table(s) containing the color(s) columns. If one name is given than the table is used for each
+ spatial element to be plotted if the table annotates it. If multiple names are given in a list than the
+ length must be equal to the number of spatial elements being plotted.
  kwargs
  Additional arguments to be passed to cmap and norm.
 
@@ -623,6 +667,12 @@ def show(
  Works only if there is one image in the SpatialData object.
  ncols :
  Number of columns in the figure. Default is 4.
+ return_ax :
+ Whether to return the axes object created. False by default.
+ colorbar :
+ Whether to plot the colorbar. True by default.
+ title :
+ The title of the plot. If not provided the plot will have the name of the coordinate system as title.
 
  Returns
  -------

src/spatialdata_plot/pl/render.py

@@ -677,17 +677,6 @@ def _render_labels(
  na_color=render_params.cmap_params.na_color,
  )
 
- _cax = ax.imshow(
- labels_infill,
- rasterized=True,
- cmap=None if categorical else render_params.cmap_params.cmap,
- norm=None if categorical else render_params.cmap_params.norm,
- alpha=render_params.fill_alpha,
- origin="lower",
- )
- _cax.set_transform(trans_data)
- cax = ax.add_image(_cax)
-
  # Then overlay the contour
  labels_contour = _map_color_seg(
  seg=label.values,
@@ -708,6 +697,16 @@ def _render_labels(
  alpha=render_params.outline_alpha,
  origin="lower",
  )
+ _cax = ax.imshow(
+ labels_infill,
+ rasterized=True,
+ cmap=None if categorical else render_params.cmap_params.cmap,
+ norm=None if categorical else render_params.cmap_params.norm,
+ alpha=render_params.fill_alpha,
+ origin="lower",
+ )
+ _cax.set_transform(trans_data)
+ cax = ax.add_image(_cax)
  else:
  # Default: no alpha, contour = infill
  label = _map_color_seg(

src/spatialdata_plot/pl/render_params.py

@@ -75,7 +75,7 @@ class ShapesRenderParams:
  col_for_color: str | None = None
  groups: str | list[list[str | None]] | list[str | None] | None = None
  contour_px: int | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  outline_alpha: float = 1.0
  fill_alpha: float = 0.3
  scale: float = 1.0
@@ -106,7 +106,7 @@ class ImageRenderParams:
  cmap_params: list[CmapParams] | CmapParams
  elements: str | Sequence[str] | None = None
  channel: list[str] | list[int] | int | str | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  alpha: float = 1.0
  quantiles_for_norm: tuple[float | None, float | None] = (None, None)
  scale: str | list[str] | None = None

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning][].
 
 ### Fixed
 
-- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
+- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
 
 ## [0.2.0] - 2024-03-24
 

src/spatialdata_plot/pl/basic.py

@@ -150,10 +150,10 @@ def _copy(
  def render_shapes(
  self,
  elements: list[str] | str | None = None,
- color: str | None = None,
+ color: list[str | None] | str | None = None,
  fill_alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  outline: bool = False,
  outline_width: float | int = 1.5,
@@ -173,17 +173,29 @@ def render_shapes(
  elements : list[str] | str | None, optional
  The name(s) of the shapes element(s) to render. If `None`, all shapes
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  fill_alpha : float | int, default 1.0
- Alpha value for the fill of shapes.
- groups : list[str] | str | None, optional
+ Alpha value for the fill of shapes. If the alpha channel is present in a cmap passed by the
+ user, this value will multiply the value present in the cmap.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -274,8 +286,8 @@ def render_points(
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
  alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  cmap: Colormap | str | None = None,
  norm: None | Normalize = None,
@@ -291,17 +303,28 @@ def render_points(
  elements : list[str] | str | None, optional
  The name(s) of the points element(s) to render. If `None`, all points
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  alpha : float | int, default 1.0
  Alpha value for the points.
- groups : list[str] | str | None, optional
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -374,7 +397,7 @@ def render_images(
  cmap: list[Colormap] | Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
- palette: list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  alpha: float | int = 1.0,
  quantiles_for_norm: tuple[float | None, float | None] | None = None,
  scale: list[str] | str | None = None,
@@ -400,6 +423,11 @@ def render_images(
  Applies to all channels if set.
  na_color : ColorLike | None, default (0.0, 0.0, 0.0, 0.0)
  Color to be used for NA values. Accepts color-like values (string, hex, RGB(A)).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette to color images. In the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list contains the string
+ indicating the palette to be used. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  alpha : float | int, default 1.0
  Alpha value for the images. Must be a numeric between 0 and 1.
  quantiles_for_norm : tuple[float | None, float | None] | None, optional
@@ -476,10 +504,10 @@ def render_labels(
  self,
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
- groups: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
  contour_px: int = 3,
  outline: bool = False,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  cmap: Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
@@ -497,19 +525,31 @@ def render_labels(
  elements : list[str] | str | None, optional
  The name(s) of the label element(s) to render. If `None`, all label
  elements in the `SpatialData` object will be used.
- color : str | None, optional
- Key for annotations in :attr:`anndata.AnnData.obs` or variables/genes.
- groups : list[str] | str | None, optional
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette for discrete annotations. List of valid color names that should be
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  contour_px : int, default 3
  Draw contour of specified width for each segment. If `None`, fills
  entire segment, see :func:`skimage.morphology.erosion`.
  outline : bool, default False
  Whether to plot boundaries around segmentation masks.
- palette : list[str] | str | None, optional
- Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
  cmap : Colormap | str | None, optional
  Colormap for continuous annotations, see :class:`matplotlib.colors.Colormap`.
  norm : Normalize | None, optional
@@ -529,6 +569,10 @@ def render_labels(
  3) "full": render the full image without rasterization. In the case of a multiscale image, the scale
  with the highest resolution is selected. This can lead to long computing times for large images!
  4) List that is matched to the list of elements (can contain `None`, scale names or "full").
+ table_name:
+ Name of the table(s) containing the color(s) columns. If one name is given than the table is used for each
+ spatial element to be plotted if the table annotates it. If multiple names are given in a list than the
+ length must be equal to the number of spatial elements being plotted.
  kwargs
  Additional arguments to be passed to cmap and norm.
 
@@ -623,6 +667,12 @@ def show(
  Works only if there is one image in the SpatialData object.
  ncols :
  Number of columns in the figure. Default is 4.
+ return_ax :
+ Whether to return the axes object created. False by default.
+ colorbar :
+ Whether to plot the colorbar. True by default.
+ title :
+ The title of the plot. If not provided the plot will have the name of the coordinate system as title.
 
  Returns
  -------

src/spatialdata_plot/pl/render.py

@@ -677,17 +677,6 @@ def _render_labels(
  na_color=render_params.cmap_params.na_color,
  )
 
- _cax = ax.imshow(
- labels_infill,
- rasterized=True,
- cmap=None if categorical else render_params.cmap_params.cmap,
- norm=None if categorical else render_params.cmap_params.norm,
- alpha=render_params.fill_alpha,
- origin="lower",
- )
- _cax.set_transform(trans_data)
- cax = ax.add_image(_cax)
-
  # Then overlay the contour
  labels_contour = _map_color_seg(
  seg=label.values,
@@ -708,6 +697,16 @@ def _render_labels(
  alpha=render_params.outline_alpha,
  origin="lower",
  )
+ _cax = ax.imshow(
+ labels_infill,
+ rasterized=True,
+ cmap=None if categorical else render_params.cmap_params.cmap,
+ norm=None if categorical else render_params.cmap_params.norm,
+ alpha=render_params.fill_alpha,
+ origin="lower",
+ )
+ _cax.set_transform(trans_data)
+ cax = ax.add_image(_cax)
  else:
  # Default: no alpha, contour = infill
  label = _map_color_seg(

src/spatialdata_plot/pl/render_params.py

@@ -75,7 +75,7 @@ class ShapesRenderParams:
  col_for_color: str | None = None
  groups: str | list[list[str | None]] | list[str | None] | None = None
  contour_px: int | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  outline_alpha: float = 1.0
  fill_alpha: float = 0.3
  scale: float = 1.0
@@ -106,7 +106,7 @@ class ImageRenderParams:
  cmap_params: list[CmapParams] | CmapParams
  elements: str | Sequence[str] | None = None
  channel: list[str] | list[int] | int | str | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  alpha: float = 1.0
  quantiles_for_norm: tuple[float | None, float | None] = (None, None)
  scale: str | list[str] | None = None

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning][].
 
 ### Fixed
 
-- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
+- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
 
 ## [0.2.0] - 2024-03-24
 

src/spatialdata_plot/pl/basic.py

@@ -150,10 +150,10 @@ def _copy(
  def render_shapes(
  self,
  elements: list[str] | str | None = None,
- color: str | None = None,
+ color: list[str | None] | str | None = None,
  fill_alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  outline: bool = False,
  outline_width: float | int = 1.5,
@@ -173,17 +173,29 @@ def render_shapes(
  elements : list[str] | str | None, optional
  The name(s) of the shapes element(s) to render. If `None`, all shapes
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  fill_alpha : float | int, default 1.0
- Alpha value for the fill of shapes.
- groups : list[str] | str | None, optional
+ Alpha value for the fill of shapes. If the alpha channel is present in a cmap passed by the
+ user, this value will multiply the value present in the cmap.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -274,8 +286,8 @@ def render_points(
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
  alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  cmap: Colormap | str | None = None,
  norm: None | Normalize = None,
@@ -291,17 +303,28 @@ def render_points(
  elements : list[str] | str | None, optional
  The name(s) of the points element(s) to render. If `None`, all points
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  alpha : float | int, default 1.0
  Alpha value for the points.
- groups : list[str] | str | None, optional
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -374,7 +397,7 @@ def render_images(
  cmap: list[Colormap] | Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
- palette: list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  alpha: float | int = 1.0,
  quantiles_for_norm: tuple[float | None, float | None] | None = None,
  scale: list[str] | str | None = None,
@@ -400,6 +423,11 @@ def render_images(
  Applies to all channels if set.
  na_color : ColorLike | None, default (0.0, 0.0, 0.0, 0.0)
  Color to be used for NA values. Accepts color-like values (string, hex, RGB(A)).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette to color images. In the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list contains the string
+ indicating the palette to be used. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  alpha : float | int, default 1.0
  Alpha value for the images. Must be a numeric between 0 and 1.
  quantiles_for_norm : tuple[float | None, float | None] | None, optional
@@ -476,10 +504,10 @@ def render_labels(
  self,
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
- groups: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
  contour_px: int = 3,
  outline: bool = False,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  cmap: Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
@@ -497,19 +525,31 @@ def render_labels(
  elements : list[str] | str | None, optional
  The name(s) of the label element(s) to render. If `None`, all label
  elements in the `SpatialData` object will be used.
- color : str | None, optional
- Key for annotations in :attr:`anndata.AnnData.obs` or variables/genes.
- groups : list[str] | str | None, optional
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette for discrete annotations. List of valid color names that should be
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  contour_px : int, default 3
  Draw contour of specified width for each segment. If `None`, fills
  entire segment, see :func:`skimage.morphology.erosion`.
  outline : bool, default False
  Whether to plot boundaries around segmentation masks.
- palette : list[str] | str | None, optional
- Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
  cmap : Colormap | str | None, optional
  Colormap for continuous annotations, see :class:`matplotlib.colors.Colormap`.
  norm : Normalize | None, optional
@@ -529,6 +569,10 @@ def render_labels(
  3) "full": render the full image without rasterization. In the case of a multiscale image, the scale
  with the highest resolution is selected. This can lead to long computing times for large images!
  4) List that is matched to the list of elements (can contain `None`, scale names or "full").
+ table_name:
+ Name of the table(s) containing the color(s) columns. If one name is given than the table is used for each
+ spatial element to be plotted if the table annotates it. If multiple names are given in a list than the
+ length must be equal to the number of spatial elements being plotted.
  kwargs
  Additional arguments to be passed to cmap and norm.
 
@@ -623,6 +667,12 @@ def show(
  Works only if there is one image in the SpatialData object.
  ncols :
  Number of columns in the figure. Default is 4.
+ return_ax :
+ Whether to return the axes object created. False by default.
+ colorbar :
+ Whether to plot the colorbar. True by default.
+ title :
+ The title of the plot. If not provided the plot will have the name of the coordinate system as title.
 
  Returns
  -------

src/spatialdata_plot/pl/render.py

@@ -677,17 +677,6 @@ def _render_labels(
  na_color=render_params.cmap_params.na_color,
  )
 
- _cax = ax.imshow(
- labels_infill,
- rasterized=True,
- cmap=None if categorical else render_params.cmap_params.cmap,
- norm=None if categorical else render_params.cmap_params.norm,
- alpha=render_params.fill_alpha,
- origin="lower",
- )
- _cax.set_transform(trans_data)
- cax = ax.add_image(_cax)
-
  # Then overlay the contour
  labels_contour = _map_color_seg(
  seg=label.values,
@@ -708,6 +697,16 @@ def _render_labels(
  alpha=render_params.outline_alpha,
  origin="lower",
  )
+ _cax = ax.imshow(
+ labels_infill,
+ rasterized=True,
+ cmap=None if categorical else render_params.cmap_params.cmap,
+ norm=None if categorical else render_params.cmap_params.norm,
+ alpha=render_params.fill_alpha,
+ origin="lower",
+ )
+ _cax.set_transform(trans_data)
+ cax = ax.add_image(_cax)
  else:
  # Default: no alpha, contour = infill
  label = _map_color_seg(

src/spatialdata_plot/pl/render_params.py

@@ -75,7 +75,7 @@ class ShapesRenderParams:
  col_for_color: str | None = None
  groups: str | list[list[str | None]] | list[str | None] | None = None
  contour_px: int | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  outline_alpha: float = 1.0
  fill_alpha: float = 0.3
  scale: float = 1.0
@@ -106,7 +106,7 @@ class ImageRenderParams:
  cmap_params: list[CmapParams] | CmapParams
  elements: str | Sequence[str] | None = None
  channel: list[str] | list[int] | int | str | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  alpha: float = 1.0
  quantiles_for_norm: tuple[float | None, float | None] = (None, None)
  scale: str | list[str] | None = None

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning][].
 
 ### Fixed
 
-- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
+- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
 
 ## [0.2.0] - 2024-03-24
 

src/spatialdata_plot/pl/basic.py

@@ -150,10 +150,10 @@ def _copy(
  def render_shapes(
  self,
  elements: list[str] | str | None = None,
- color: str | None = None,
+ color: list[str | None] | str | None = None,
  fill_alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  outline: bool = False,
  outline_width: float | int = 1.5,
@@ -173,17 +173,29 @@ def render_shapes(
  elements : list[str] | str | None, optional
  The name(s) of the shapes element(s) to render. If `None`, all shapes
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  fill_alpha : float | int, default 1.0
- Alpha value for the fill of shapes.
- groups : list[str] | str | None, optional
+ Alpha value for the fill of shapes. If the alpha channel is present in a cmap passed by the
+ user, this value will multiply the value present in the cmap.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -274,8 +286,8 @@ def render_points(
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
  alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  cmap: Colormap | str | None = None,
  norm: None | Normalize = None,
@@ -291,17 +303,28 @@ def render_points(
  elements : list[str] | str | None, optional
  The name(s) of the points element(s) to render. If `None`, all points
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  alpha : float | int, default 1.0
  Alpha value for the points.
- groups : list[str] | str | None, optional
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -374,7 +397,7 @@ def render_images(
  cmap: list[Colormap] | Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
- palette: list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  alpha: float | int = 1.0,
  quantiles_for_norm: tuple[float | None, float | None] | None = None,
  scale: list[str] | str | None = None,
@@ -400,6 +423,11 @@ def render_images(
  Applies to all channels if set.
  na_color : ColorLike | None, default (0.0, 0.0, 0.0, 0.0)
  Color to be used for NA values. Accepts color-like values (string, hex, RGB(A)).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette to color images. In the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list contains the string
+ indicating the palette to be used. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  alpha : float | int, default 1.0
  Alpha value for the images. Must be a numeric between 0 and 1.
  quantiles_for_norm : tuple[float | None, float | None] | None, optional
@@ -476,10 +504,10 @@ def render_labels(
  self,
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
- groups: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
  contour_px: int = 3,
  outline: bool = False,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  cmap: Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
@@ -497,19 +525,31 @@ def render_labels(
  elements : list[str] | str | None, optional
  The name(s) of the label element(s) to render. If `None`, all label
  elements in the `SpatialData` object will be used.
- color : str | None, optional
- Key for annotations in :attr:`anndata.AnnData.obs` or variables/genes.
- groups : list[str] | str | None, optional
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette for discrete annotations. List of valid color names that should be
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  contour_px : int, default 3
  Draw contour of specified width for each segment. If `None`, fills
  entire segment, see :func:`skimage.morphology.erosion`.
  outline : bool, default False
  Whether to plot boundaries around segmentation masks.
- palette : list[str] | str | None, optional
- Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
  cmap : Colormap | str | None, optional
  Colormap for continuous annotations, see :class:`matplotlib.colors.Colormap`.
  norm : Normalize | None, optional
@@ -529,6 +569,10 @@ def render_labels(
  3) "full": render the full image without rasterization. In the case of a multiscale image, the scale
  with the highest resolution is selected. This can lead to long computing times for large images!
  4) List that is matched to the list of elements (can contain `None`, scale names or "full").
+ table_name:
+ Name of the table(s) containing the color(s) columns. If one name is given than the table is used for each
+ spatial element to be plotted if the table annotates it. If multiple names are given in a list than the
+ length must be equal to the number of spatial elements being plotted.
  kwargs
  Additional arguments to be passed to cmap and norm.
 
@@ -623,6 +667,12 @@ def show(
  Works only if there is one image in the SpatialData object.
  ncols :
  Number of columns in the figure. Default is 4.
+ return_ax :
+ Whether to return the axes object created. False by default.
+ colorbar :
+ Whether to plot the colorbar. True by default.
+ title :
+ The title of the plot. If not provided the plot will have the name of the coordinate system as title.
 
  Returns
  -------

src/spatialdata_plot/pl/render.py

@@ -677,17 +677,6 @@ def _render_labels(
  na_color=render_params.cmap_params.na_color,
  )
 
- _cax = ax.imshow(
- labels_infill,
- rasterized=True,
- cmap=None if categorical else render_params.cmap_params.cmap,
- norm=None if categorical else render_params.cmap_params.norm,
- alpha=render_params.fill_alpha,
- origin="lower",
- )
- _cax.set_transform(trans_data)
- cax = ax.add_image(_cax)
-
  # Then overlay the contour
  labels_contour = _map_color_seg(
  seg=label.values,
@@ -708,6 +697,16 @@ def _render_labels(
  alpha=render_params.outline_alpha,
  origin="lower",
  )
+ _cax = ax.imshow(
+ labels_infill,
+ rasterized=True,
+ cmap=None if categorical else render_params.cmap_params.cmap,
+ norm=None if categorical else render_params.cmap_params.norm,
+ alpha=render_params.fill_alpha,
+ origin="lower",
+ )
+ _cax.set_transform(trans_data)
+ cax = ax.add_image(_cax)
  else:
  # Default: no alpha, contour = infill
  label = _map_color_seg(

src/spatialdata_plot/pl/render_params.py

@@ -75,7 +75,7 @@ class ShapesRenderParams:
  col_for_color: str | None = None
  groups: str | list[list[str | None]] | list[str | None] | None = None
  contour_px: int | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  outline_alpha: float = 1.0
  fill_alpha: float = 0.3
  scale: float = 1.0
@@ -106,7 +106,7 @@ class ImageRenderParams:
  cmap_params: list[CmapParams] | CmapParams
  elements: str | Sequence[str] | None = None
  channel: list[str] | list[int] | int | str | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  alpha: float = 1.0
  quantiles_for_norm: tuple[float | None, float | None] = (None, None)
  scale: str | list[str] | None = None

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning][].
 
 ### Fixed
 
-- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
+- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
 
 ## [0.2.0] - 2024-03-24
 

src/spatialdata_plot/pl/basic.py

@@ -150,10 +150,10 @@ def _copy(
  def render_shapes(
  self,
  elements: list[str] | str | None = None,
- color: str | None = None,
+ color: list[str | None] | str | None = None,
  fill_alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  outline: bool = False,
  outline_width: float | int = 1.5,
@@ -173,17 +173,29 @@ def render_shapes(
  elements : list[str] | str | None, optional
  The name(s) of the shapes element(s) to render. If `None`, all shapes
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  fill_alpha : float | int, default 1.0
- Alpha value for the fill of shapes.
- groups : list[str] | str | None, optional
+ Alpha value for the fill of shapes. If the alpha channel is present in a cmap passed by the
+ user, this value will multiply the value present in the cmap.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -274,8 +286,8 @@ def render_points(
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
  alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  cmap: Colormap | str | None = None,
  norm: None | Normalize = None,
@@ -291,17 +303,28 @@ def render_points(
  elements : list[str] | str | None, optional
  The name(s) of the points element(s) to render. If `None`, all points
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  alpha : float | int, default 1.0
  Alpha value for the points.
- groups : list[str] | str | None, optional
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -374,7 +397,7 @@ def render_images(
  cmap: list[Colormap] | Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
- palette: list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  alpha: float | int = 1.0,
  quantiles_for_norm: tuple[float | None, float | None] | None = None,
  scale: list[str] | str | None = None,
@@ -400,6 +423,11 @@ def render_images(
  Applies to all channels if set.
  na_color : ColorLike | None, default (0.0, 0.0, 0.0, 0.0)
  Color to be used for NA values. Accepts color-like values (string, hex, RGB(A)).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette to color images. In the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list contains the string
+ indicating the palette to be used. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  alpha : float | int, default 1.0
  Alpha value for the images. Must be a numeric between 0 and 1.
  quantiles_for_norm : tuple[float | None, float | None] | None, optional
@@ -476,10 +504,10 @@ def render_labels(
  self,
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
- groups: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
  contour_px: int = 3,
  outline: bool = False,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  cmap: Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
@@ -497,19 +525,31 @@ def render_labels(
  elements : list[str] | str | None, optional
  The name(s) of the label element(s) to render. If `None`, all label
  elements in the `SpatialData` object will be used.
- color : str | None, optional
- Key for annotations in :attr:`anndata.AnnData.obs` or variables/genes.
- groups : list[str] | str | None, optional
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette for discrete annotations. List of valid color names that should be
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  contour_px : int, default 3
  Draw contour of specified width for each segment. If `None`, fills
  entire segment, see :func:`skimage.morphology.erosion`.
  outline : bool, default False
  Whether to plot boundaries around segmentation masks.
- palette : list[str] | str | None, optional
- Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
  cmap : Colormap | str | None, optional
  Colormap for continuous annotations, see :class:`matplotlib.colors.Colormap`.
  norm : Normalize | None, optional
@@ -529,6 +569,10 @@ def render_labels(
  3) "full": render the full image without rasterization. In the case of a multiscale image, the scale
  with the highest resolution is selected. This can lead to long computing times for large images!
  4) List that is matched to the list of elements (can contain `None`, scale names or "full").
+ table_name:
+ Name of the table(s) containing the color(s) columns. If one name is given than the table is used for each
+ spatial element to be plotted if the table annotates it. If multiple names are given in a list than the
+ length must be equal to the number of spatial elements being plotted.
  kwargs
  Additional arguments to be passed to cmap and norm.
 
@@ -623,6 +667,12 @@ def show(
  Works only if there is one image in the SpatialData object.
  ncols :
  Number of columns in the figure. Default is 4.
+ return_ax :
+ Whether to return the axes object created. False by default.
+ colorbar :
+ Whether to plot the colorbar. True by default.
+ title :
+ The title of the plot. If not provided the plot will have the name of the coordinate system as title.
 
  Returns
  -------

src/spatialdata_plot/pl/render.py

@@ -677,17 +677,6 @@ def _render_labels(
  na_color=render_params.cmap_params.na_color,
  )
 
- _cax = ax.imshow(
- labels_infill,
- rasterized=True,
- cmap=None if categorical else render_params.cmap_params.cmap,
- norm=None if categorical else render_params.cmap_params.norm,
- alpha=render_params.fill_alpha,
- origin="lower",
- )
- _cax.set_transform(trans_data)
- cax = ax.add_image(_cax)
-
  # Then overlay the contour
  labels_contour = _map_color_seg(
  seg=label.values,
@@ -708,6 +697,16 @@ def _render_labels(
  alpha=render_params.outline_alpha,
  origin="lower",
  )
+ _cax = ax.imshow(
+ labels_infill,
+ rasterized=True,
+ cmap=None if categorical else render_params.cmap_params.cmap,
+ norm=None if categorical else render_params.cmap_params.norm,
+ alpha=render_params.fill_alpha,
+ origin="lower",
+ )
+ _cax.set_transform(trans_data)
+ cax = ax.add_image(_cax)
  else:
  # Default: no alpha, contour = infill
  label = _map_color_seg(

src/spatialdata_plot/pl/render_params.py

@@ -75,7 +75,7 @@ class ShapesRenderParams:
  col_for_color: str | None = None
  groups: str | list[list[str | None]] | list[str | None] | None = None
  contour_px: int | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  outline_alpha: float = 1.0
  fill_alpha: float = 0.3
  scale: float = 1.0
@@ -106,7 +106,7 @@ class ImageRenderParams:
  cmap_params: list[CmapParams] | CmapParams
  elements: str | Sequence[str] | None = None
  channel: list[str] | list[int] | int | str | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  alpha: float = 1.0
  quantiles_for_norm: tuple[float | None, float | None] = (None, None)
  scale: str | list[str] | None = None

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning][].
 
 ### Fixed
 
-- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
+- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
 
 ## [0.2.0] - 2024-03-24
 

src/spatialdata_plot/pl/basic.py

@@ -150,10 +150,10 @@ def _copy(
  def render_shapes(
  self,
  elements: list[str] | str | None = None,
- color: str | None = None,
+ color: list[str | None] | str | None = None,
  fill_alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  outline: bool = False,
  outline_width: float | int = 1.5,
@@ -173,17 +173,29 @@ def render_shapes(
  elements : list[str] | str | None, optional
  The name(s) of the shapes element(s) to render. If `None`, all shapes
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  fill_alpha : float | int, default 1.0
- Alpha value for the fill of shapes.
- groups : list[str] | str | None, optional
+ Alpha value for the fill of shapes. If the alpha channel is present in a cmap passed by the
+ user, this value will multiply the value present in the cmap.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -274,8 +286,8 @@ def render_points(
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
  alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  cmap: Colormap | str | None = None,
  norm: None | Normalize = None,
@@ -291,17 +303,28 @@ def render_points(
  elements : list[str] | str | None, optional
  The name(s) of the points element(s) to render. If `None`, all points
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  alpha : float | int, default 1.0
  Alpha value for the points.
- groups : list[str] | str | None, optional
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -374,7 +397,7 @@ def render_images(
  cmap: list[Colormap] | Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
- palette: list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  alpha: float | int = 1.0,
  quantiles_for_norm: tuple[float | None, float | None] | None = None,
  scale: list[str] | str | None = None,
@@ -400,6 +423,11 @@ def render_images(
  Applies to all channels if set.
  na_color : ColorLike | None, default (0.0, 0.0, 0.0, 0.0)
  Color to be used for NA values. Accepts color-like values (string, hex, RGB(A)).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette to color images. In the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list contains the string
+ indicating the palette to be used. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  alpha : float | int, default 1.0
  Alpha value for the images. Must be a numeric between 0 and 1.
  quantiles_for_norm : tuple[float | None, float | None] | None, optional
@@ -476,10 +504,10 @@ def render_labels(
  self,
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
- groups: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
  contour_px: int = 3,
  outline: bool = False,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  cmap: Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
@@ -497,19 +525,31 @@ def render_labels(
  elements : list[str] | str | None, optional
  The name(s) of the label element(s) to render. If `None`, all label
  elements in the `SpatialData` object will be used.
- color : str | None, optional
- Key for annotations in :attr:`anndata.AnnData.obs` or variables/genes.
- groups : list[str] | str | None, optional
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette for discrete annotations. List of valid color names that should be
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  contour_px : int, default 3
  Draw contour of specified width for each segment. If `None`, fills
  entire segment, see :func:`skimage.morphology.erosion`.
  outline : bool, default False
  Whether to plot boundaries around segmentation masks.
- palette : list[str] | str | None, optional
- Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
  cmap : Colormap | str | None, optional
  Colormap for continuous annotations, see :class:`matplotlib.colors.Colormap`.
  norm : Normalize | None, optional
@@ -529,6 +569,10 @@ def render_labels(
  3) "full": render the full image without rasterization. In the case of a multiscale image, the scale
  with the highest resolution is selected. This can lead to long computing times for large images!
  4) List that is matched to the list of elements (can contain `None`, scale names or "full").
+ table_name:
+ Name of the table(s) containing the color(s) columns. If one name is given than the table is used for each
+ spatial element to be plotted if the table annotates it. If multiple names are given in a list than the
+ length must be equal to the number of spatial elements being plotted.
  kwargs
  Additional arguments to be passed to cmap and norm.
 
@@ -623,6 +667,12 @@ def show(
  Works only if there is one image in the SpatialData object.
  ncols :
  Number of columns in the figure. Default is 4.
+ return_ax :
+ Whether to return the axes object created. False by default.
+ colorbar :
+ Whether to plot the colorbar. True by default.
+ title :
+ The title of the plot. If not provided the plot will have the name of the coordinate system as title.
 
  Returns
  -------

src/spatialdata_plot/pl/render.py

@@ -677,17 +677,6 @@ def _render_labels(
  na_color=render_params.cmap_params.na_color,
  )
 
- _cax = ax.imshow(
- labels_infill,
- rasterized=True,
- cmap=None if categorical else render_params.cmap_params.cmap,
- norm=None if categorical else render_params.cmap_params.norm,
- alpha=render_params.fill_alpha,
- origin="lower",
- )
- _cax.set_transform(trans_data)
- cax = ax.add_image(_cax)
-
  # Then overlay the contour
  labels_contour = _map_color_seg(
  seg=label.values,
@@ -708,6 +697,16 @@ def _render_labels(
  alpha=render_params.outline_alpha,
  origin="lower",
  )
+ _cax = ax.imshow(
+ labels_infill,
+ rasterized=True,
+ cmap=None if categorical else render_params.cmap_params.cmap,
+ norm=None if categorical else render_params.cmap_params.norm,
+ alpha=render_params.fill_alpha,
+ origin="lower",
+ )
+ _cax.set_transform(trans_data)
+ cax = ax.add_image(_cax)
  else:
  # Default: no alpha, contour = infill
  label = _map_color_seg(

src/spatialdata_plot/pl/render_params.py

@@ -75,7 +75,7 @@ class ShapesRenderParams:
  col_for_color: str | None = None
  groups: str | list[list[str | None]] | list[str | None] | None = None
  contour_px: int | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  outline_alpha: float = 1.0
  fill_alpha: float = 0.3
  scale: float = 1.0
@@ -106,7 +106,7 @@ class ImageRenderParams:
  cmap_params: list[CmapParams] | CmapParams
  elements: str | Sequence[str] | None = None
  channel: list[str] | list[int] | int | str | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  alpha: float = 1.0
  quantiles_for_norm: tuple[float | None, float | None] = (None, None)
  scale: str | list[str] | None = None

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning][].
 
 ### Fixed
 
-- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
+- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
 
 ## [0.2.0] - 2024-03-24
 

src/spatialdata_plot/pl/basic.py

@@ -150,10 +150,10 @@ def _copy(
  def render_shapes(
  self,
  elements: list[str] | str | None = None,
- color: str | None = None,
+ color: list[str | None] | str | None = None,
  fill_alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  outline: bool = False,
  outline_width: float | int = 1.5,
@@ -173,17 +173,29 @@ def render_shapes(
  elements : list[str] | str | None, optional
  The name(s) of the shapes element(s) to render. If `None`, all shapes
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  fill_alpha : float | int, default 1.0
- Alpha value for the fill of shapes.
- groups : list[str] | str | None, optional
+ Alpha value for the fill of shapes. If the alpha channel is present in a cmap passed by the
+ user, this value will multiply the value present in the cmap.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -274,8 +286,8 @@ def render_points(
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
  alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  cmap: Colormap | str | None = None,
  norm: None | Normalize = None,
@@ -291,17 +303,28 @@ def render_points(
  elements : list[str] | str | None, optional
  The name(s) of the points element(s) to render. If `None`, all points
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  alpha : float | int, default 1.0
  Alpha value for the points.
- groups : list[str] | str | None, optional
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -374,7 +397,7 @@ def render_images(
  cmap: list[Colormap] | Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
- palette: list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  alpha: float | int = 1.0,
  quantiles_for_norm: tuple[float | None, float | None] | None = None,
  scale: list[str] | str | None = None,
@@ -400,6 +423,11 @@ def render_images(
  Applies to all channels if set.
  na_color : ColorLike | None, default (0.0, 0.0, 0.0, 0.0)
  Color to be used for NA values. Accepts color-like values (string, hex, RGB(A)).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette to color images. In the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list contains the string
+ indicating the palette to be used. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  alpha : float | int, default 1.0
  Alpha value for the images. Must be a numeric between 0 and 1.
  quantiles_for_norm : tuple[float | None, float | None] | None, optional
@@ -476,10 +504,10 @@ def render_labels(
  self,
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
- groups: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
  contour_px: int = 3,
  outline: bool = False,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  cmap: Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
@@ -497,19 +525,31 @@ def render_labels(
  elements : list[str] | str | None, optional
  The name(s) of the label element(s) to render. If `None`, all label
  elements in the `SpatialData` object will be used.
- color : str | None, optional
- Key for annotations in :attr:`anndata.AnnData.obs` or variables/genes.
- groups : list[str] | str | None, optional
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette for discrete annotations. List of valid color names that should be
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  contour_px : int, default 3
  Draw contour of specified width for each segment. If `None`, fills
  entire segment, see :func:`skimage.morphology.erosion`.
  outline : bool, default False
  Whether to plot boundaries around segmentation masks.
- palette : list[str] | str | None, optional
- Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
  cmap : Colormap | str | None, optional
  Colormap for continuous annotations, see :class:`matplotlib.colors.Colormap`.
  norm : Normalize | None, optional
@@ -529,6 +569,10 @@ def render_labels(
  3) "full": render the full image without rasterization. In the case of a multiscale image, the scale
  with the highest resolution is selected. This can lead to long computing times for large images!
  4) List that is matched to the list of elements (can contain `None`, scale names or "full").
+ table_name:
+ Name of the table(s) containing the color(s) columns. If one name is given than the table is used for each
+ spatial element to be plotted if the table annotates it. If multiple names are given in a list than the
+ length must be equal to the number of spatial elements being plotted.
  kwargs
  Additional arguments to be passed to cmap and norm.
 
@@ -623,6 +667,12 @@ def show(
  Works only if there is one image in the SpatialData object.
  ncols :
  Number of columns in the figure. Default is 4.
+ return_ax :
+ Whether to return the axes object created. False by default.
+ colorbar :
+ Whether to plot the colorbar. True by default.
+ title :
+ The title of the plot. If not provided the plot will have the name of the coordinate system as title.
 
  Returns
  -------

src/spatialdata_plot/pl/render.py

@@ -677,17 +677,6 @@ def _render_labels(
  na_color=render_params.cmap_params.na_color,
  )
 
- _cax = ax.imshow(
- labels_infill,
- rasterized=True,
- cmap=None if categorical else render_params.cmap_params.cmap,
- norm=None if categorical else render_params.cmap_params.norm,
- alpha=render_params.fill_alpha,
- origin="lower",
- )
- _cax.set_transform(trans_data)
- cax = ax.add_image(_cax)
-
  # Then overlay the contour
  labels_contour = _map_color_seg(
  seg=label.values,
@@ -708,6 +697,16 @@ def _render_labels(
  alpha=render_params.outline_alpha,
  origin="lower",
  )
+ _cax = ax.imshow(
+ labels_infill,
+ rasterized=True,
+ cmap=None if categorical else render_params.cmap_params.cmap,
+ norm=None if categorical else render_params.cmap_params.norm,
+ alpha=render_params.fill_alpha,
+ origin="lower",
+ )
+ _cax.set_transform(trans_data)
+ cax = ax.add_image(_cax)
  else:
  # Default: no alpha, contour = infill
  label = _map_color_seg(

src/spatialdata_plot/pl/render_params.py

@@ -75,7 +75,7 @@ class ShapesRenderParams:
  col_for_color: str | None = None
  groups: str | list[list[str | None]] | list[str | None] | None = None
  contour_px: int | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  outline_alpha: float = 1.0
  fill_alpha: float = 0.3
  scale: float = 1.0
@@ -106,7 +106,7 @@ class ImageRenderParams:
  cmap_params: list[CmapParams] | CmapParams
  elements: str | Sequence[str] | None = None
  channel: list[str] | list[int] | int | str | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  alpha: float = 1.0
  quantiles_for_norm: tuple[float | None, float | None] = (None, None)
  scale: str | list[str] | None = None

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning][].
 
 ### Fixed
 
-- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
+- Fixed `fill_alpha` ignoring `alpha` channel from custom cmap
 
 ## [0.2.0] - 2024-03-24
 

src/spatialdata_plot/pl/basic.py

@@ -150,10 +150,10 @@ def _copy(
  def render_shapes(
  self,
  elements: list[str] | str | None = None,
- color: str | None = None,
+ color: list[str | None] | str | None = None,
  fill_alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  outline: bool = False,
  outline_width: float | int = 1.5,
@@ -173,17 +173,29 @@ def render_shapes(
  elements : list[str] | str | None, optional
  The name(s) of the shapes element(s) to render. If `None`, all shapes
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  fill_alpha : float | int, default 1.0
- Alpha value for the fill of shapes.
- groups : list[str] | str | None, optional
+ Alpha value for the fill of shapes. If the alpha channel is present in a cmap passed by the
+ user, this value will multiply the value present in the cmap.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -274,8 +286,8 @@ def render_points(
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
  alpha: float | int = 1.0,
- groups: list[list[str | None]] | list[str] | str | None = None,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  na_color: ColorLike | None = "lightgrey",
  cmap: Colormap | str | None = None,
  norm: None | Normalize = None,
@@ -291,17 +303,28 @@ def render_points(
  elements : list[str] | str | None, optional
  The name(s) of the points element(s) to render. If `None`, all points
  elements in the `SpatialData` object will be used.
- color : Colorlike | str | None, optional
- Can either be a color-like or a key in :attr:`sdata.table.obs`. The latter
- can be used to color by categorical or continuous variables.
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
  alpha : float | int, default 1.0
  Alpha value for the points.
- groups : list[str] | str | None, optional
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
- palette : list[str] | str | None, optional
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
+ palette : list[list[str | None]] | list[str | None] | str | None
  Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  na_color : str | list[float] | None, default "lightgrey"
  Color to be used for NAs values, if present. Can either be a named color
  ("red"), a hex representation ("#000000ff") or a list of floats that
@@ -374,7 +397,7 @@ def render_images(
  cmap: list[Colormap] | Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
- palette: list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  alpha: float | int = 1.0,
  quantiles_for_norm: tuple[float | None, float | None] | None = None,
  scale: list[str] | str | None = None,
@@ -400,6 +423,11 @@ def render_images(
  Applies to all channels if set.
  na_color : ColorLike | None, default (0.0, 0.0, 0.0, 0.0)
  Color to be used for NA values. Accepts color-like values (string, hex, RGB(A)).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette to color images. In the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list contains the string
+ indicating the palette to be used. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements).
  alpha : float | int, default 1.0
  Alpha value for the images. Must be a numeric between 0 and 1.
  quantiles_for_norm : tuple[float | None, float | None] | None, optional
@@ -476,10 +504,10 @@ def render_labels(
  self,
  elements: list[str] | str | None = None,
  color: list[str | None] | str | None = None,
- groups: list[list[str | None]] | list[str] | str | None = None,
+ groups: list[list[str | None]] | list[str | None] | str | None = None,
  contour_px: int = 3,
  outline: bool = False,
- palette: list[list[str | None]] | list[str] | str | None = None,
+ palette: list[list[str | None]] | list[str | None] | str | None = None,
  cmap: Colormap | str | None = None,
  norm: Normalize | None = None,
  na_color: ColorLike | None = (0.0, 0.0, 0.0, 0.0),
@@ -497,19 +525,31 @@ def render_labels(
  elements : list[str] | str | None, optional
  The name(s) of the label element(s) to render. If `None`, all label
  elements in the `SpatialData` object will be used.
- color : str | None, optional
- Key for annotations in :attr:`anndata.AnnData.obs` or variables/genes.
- groups : list[str] | str | None, optional
+ color : list[str | None] | str | None
+ Can either be string(s) representing a color-like or key(s) in :attr:`sdata.table.obs`. The latter
+ can be used to color by categorical or continuous variables. If provided as a list, the length of the list
+ must match the number of elements that will be plotted. Otherwise, if possible the color will be broadcasted
+ to all elements. For this, the table in which the color key is found must
+ annotate the respective element (region must be set to the specific element). If the color column is found
+ in multiple locations, please provide the table_name to be used for the element.
+ groups : list[list[str | None]] | list[str | None] | str | None
  When using `color` and the key represents discrete labels, `groups`
- can be used to show only a subset of them. Other values are set to NA.
+ can be used to show only a subset of them. Other values are set to NA. In general the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ discrete labels to be visualized. If not provided as list of lists, broadcasting behaviour is attempted
+ (use the same values for all elements).
+ palette : list[list[str | None]] | list[str | None] | str | None
+ Palette for discrete annotations. List of valid color names that should be
+ used for the categories. Must match the number of groups. Similarly to groups, in the case of a list of
+ lists means that there is one list per element to be plotted in the list and this list can contain multiple
+ palettes (one per group) to be visualized. If not provided as list of lists, broadcasting behaviour is
+ attempted (use the same values for all elements). If groups is provided but not palette, palette is set to
+ default "lightgray".
  contour_px : int, default 3
  Draw contour of specified width for each segment. If `None`, fills
  entire segment, see :func:`skimage.morphology.erosion`.
  outline : bool, default False
  Whether to plot boundaries around segmentation masks.
- palette : list[str] | str | None, optional
- Palette for discrete annotations. List of valid color names that should be
- used for the categories. Must match the number of groups.
  cmap : Colormap | str | None, optional
  Colormap for continuous annotations, see :class:`matplotlib.colors.Colormap`.
  norm : Normalize | None, optional
@@ -529,6 +569,10 @@ def render_labels(
  3) "full": render the full image without rasterization. In the case of a multiscale image, the scale
  with the highest resolution is selected. This can lead to long computing times for large images!
  4) List that is matched to the list of elements (can contain `None`, scale names or "full").
+ table_name:
+ Name of the table(s) containing the color(s) columns. If one name is given than the table is used for each
+ spatial element to be plotted if the table annotates it. If multiple names are given in a list than the
+ length must be equal to the number of spatial elements being plotted.
  kwargs
  Additional arguments to be passed to cmap and norm.
 
@@ -623,6 +667,12 @@ def show(
  Works only if there is one image in the SpatialData object.
  ncols :
  Number of columns in the figure. Default is 4.
+ return_ax :
+ Whether to return the axes object created. False by default.
+ colorbar :
+ Whether to plot the colorbar. True by default.
+ title :
+ The title of the plot. If not provided the plot will have the name of the coordinate system as title.
 
  Returns
  -------

src/spatialdata_plot/pl/render.py

@@ -677,17 +677,6 @@ def _render_labels(
  na_color=render_params.cmap_params.na_color,
  )
 
- _cax = ax.imshow(
- labels_infill,
- rasterized=True,
- cmap=None if categorical else render_params.cmap_params.cmap,
- norm=None if categorical else render_params.cmap_params.norm,
- alpha=render_params.fill_alpha,
- origin="lower",
- )
- _cax.set_transform(trans_data)
- cax = ax.add_image(_cax)
-
  # Then overlay the contour
  labels_contour = _map_color_seg(
  seg=label.values,
@@ -708,6 +697,16 @@ def _render_labels(
  alpha=render_params.outline_alpha,
  origin="lower",
  )
+ _cax = ax.imshow(
+ labels_infill,
+ rasterized=True,
+ cmap=None if categorical else render_params.cmap_params.cmap,
+ norm=None if categorical else render_params.cmap_params.norm,
+ alpha=render_params.fill_alpha,
+ origin="lower",
+ )
+ _cax.set_transform(trans_data)
+ cax = ax.add_image(_cax)
  else:
  # Default: no alpha, contour = infill
  label = _map_color_seg(

src/spatialdata_plot/pl/render_params.py

@@ -75,7 +75,7 @@ class ShapesRenderParams:
  col_for_color: str | None = None
  groups: str | list[list[str | None]] | list[str | None] | None = None
  contour_px: int | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  outline_alpha: float = 1.0
  fill_alpha: float = 0.3
  scale: float = 1.0
@@ -106,7 +106,7 @@ class ImageRenderParams:
  cmap_params: list[CmapParams] | CmapParams
  elements: str | Sequence[str] | None = None
  channel: list[str] | list[int] | int | str | None = None
- palette: ListedColormap | list[str | None] | None = None
+ palette: ListedColormap | list[list[str | None]] | list[str | None] | None = None
  alpha: float = 1.0
  quantiles_for_norm: tuple[float | None, float | None] = (None, None)
  scale: str | list[str] | None = None