Plotting (.pl)

class spatialdata_plot.pl.basic.PlotAccessor(sdata)

A class to provide plotting functions for SpatialData objects.

Parameters:

sdata (SpatialData) – The SpatialData object to provide plotting functions for.

Notes

This class provides a number of methods that can be used to generate plots of the data stored in a SpatialData object. These methods are accessed via the SpatialData.pl accessor.

render_images(element=None, channel=None, cmap=None, norm=None, na_color='default', palette=None, alpha=1.0, scale=None, **kwargs)

Render image elements in SpatialData.

In case of no elements specified, “broadcasting” of parameters is applied. This means that for any particular SpatialElement, we validate whether a given parameter is valid. If not valid for a particular SpatialElement the specific parameter for that particular SpatialElement will be ignored. If you want to set specific parameters for specific elements please chain the render functions: pl.render_images(...).pl.render_images(...).pl.show() .

Parameters:

• element (str | None) – The name of the image element to render. If None, all image elements in the SpatialData object will be used and all parameters will be broadcasted if possible.

• channel (list[str] | list[int] | str | int | None) – To select specific channels to plot. Can be a single channel name/int or a list of channel names/ints. If None, all channels will be used.

• cmap (list[Colormap | str] | Colormap | str | None) – Colormap or list of colormaps for continuous annotations, see matplotlib.colors.Colormap. Each colormap applies to a corresponding channel.

• norm (Normalize | None, optional) – Colormap normalization for continuous annotations, see matplotlib.colors.Normalize. Applies to all channels if set.

• na_color (ColorLike | None, default "default" (gets set to "lightgray")) – 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 represent RGB/RGBA values (1.0, 0.0, 0.0, 1.0). When None, the values won’t be shown.

• palette (list[str] | str | None) – Palette to color images. The number of palettes should be equal to the number of channels.

• alpha (float | int, default 1.0) – Alpha value for the images. Must be a numeric between 0 and 1.

• scale (str | None) –

  Influences the resolution of the rendering. Possibilities include:

  1) None (default): The image is rasterized to fit the canvas size. For multiscale images, the best scale is selected before rasterization. 2) A scale name: Renders the specified scale ( of a multiscale image) as-is (with adjustments for dpi in show()). 3) “full”: Renders the full image without rasterization. In the case of multiscale images, the highest resolution scale is selected. Note that this may result in long computing times for large images.

• kwargs (Any) – Additional arguments to be passed to cmap, norm, and other rendering functions.

Return type:

SpatialData

Returns:

sd.SpatialData The SpatialData object with the rendered images.

render_labels(element=None, color=None, groups=None, contour_px=3, palette=None, cmap=None, norm=None, na_color='default', outline_alpha=0.0, fill_alpha=0.4, scale=None, table_name=None, table_layer=None, **kwargs)

Render labels elements in SpatialData.

In case of no elements specified, “broadcasting” of parameters is applied. This means that for any particular SpatialElement, we validate whether a given parameter is valid. If not valid for a particular SpatialElement the specific parameter for that particular SpatialElement will be ignored. If you want to set specific parameters for specific elements please chain the render functions: pl.render_images(...).pl.render_images(...).pl.show() .

Parameters:

• element (str | None) – The name of the labels element to render. If None, all label elements in the SpatialData object will be used and all parameters will be broadcasted if possible.

• color (list[str] | str | None) – Can either be string representing a color-like or key in sdata.table.obs or in the index of sdata.table.var. The latter can be used to color by categorical or continuous variables. If the color column is found in multiple locations, please provide the table_name to be used for the element if you would like a specific table to be used. By default one table will automatically be choosen.

• groups (list[str] | 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. The list can contain multiple discrete labels to be visualized.

• palette (list[str] | str | None) – Palette for discrete annotations. List of valid color names that should be used for the categories. Must match the number of groups. The list can contain multiple palettes (one per group) to be visualized. 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.

• cmap (Colormap | str | None) – Colormap for continuous annotations, see matplotlib.colors.Colormap.

• norm (Normalize | None) – Colormap normalization for continuous annotations, see matplotlib.colors.Normalize.

• na_color (ColorLike | None, default "default" (gets set to "lightgray")) – 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 represent RGB/RGBA values (1.0, 0.0, 0.0, 1.0). When None, the values won’t be shown.

• outline_alpha (float | int, default 0.0) – Alpha value for the outline of the labels. Invisible by default.

• fill_alpha (float | int, default 0.3) – Alpha value for the fill of the labels.

• scale (str | None) –

  Influences the resolution of the rendering. Possibilities for setting this parameter:

  1) None (default). The image is rasterized to fit the canvas size. For multiscale images, the best scale is selected before the rasterization step. 2) Name of one of the scales in the multiscale image to be rendered. This scale is rendered as it is (exception: a dpi is specified in show(). Then the image is rasterized to fit the canvas and dpi). 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!

• table_name (str | None) – Name of the table containing the color columns.

• table_layer (str | None) – Layer of the AnnData table to use for coloring if color is in sdata.table.var_names. If None, sdata.table.X of the default table is used for coloring.

• kwargs (Any) – Additional arguments to be passed to cmap and norm.

Return type:

SpatialData

Returns:

None

render_points(element=None, color=None, alpha=1.0, groups=None, palette=None, na_color='default', cmap=None, norm=None, size=1.0, method=None, table_name=None, table_layer=None, **kwargs)

Render points elements in SpatialData.

In case of no elements specified, “broadcasting” of parameters is applied. This means that for any particular SpatialElement, we validate whether a given parameter is valid. If not valid for a particular SpatialElement the specific parameter for that particular SpatialElement will be ignored. If you want to set specific parameters for specific elements please chain the render functions: pl.render_points(...).pl.render_points(...).pl.show() .

Parameters:

• element (str | None, optional) – The name of the points element to render. If None, all points elements in the SpatialData object will be used.

• color (str | None) – Can either be string representing a color-like or key in sdata.table.obs. The latter can be used to color by categorical or continuous variables. If element is None, 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 elements.

• alpha (float | int, default 1.0) – Alpha value for the points.

• groups (list[str] | 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. If element is None, broadcasting behaviour is attempted (use the same values for all elements).

• palette (list[str] | str | None) – Palette for discrete annotations. List of valid color names that should be used for the categories. Must match the number of groups. If element is None, 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 (ColorLike | None, default "default" (gets set to "lightgray")) – 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 represent RGB/RGBA values (1.0, 0.0, 0.0, 1.0). When None, the values won’t be shown.

• cmap (Colormap | str | None, optional) – Colormap for discrete or continuous annotations using ‘color’, see matplotlib.colors.Colormap. If no palette is given and color refers to a categorical, the colors are sampled from this colormap.

• norm (bool | Normalize, default False) – Colormap normalization for continuous annotations.

• size (float | int, default 1.0) – Size of the points

• method (str | None, optional) – Whether to use ‘matplotlib’ and ‘datashader’. When None, the method is chosen based on the size of the data.

• table_name (str | None) – Name of the table 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 you want to use different tables for particular elements, as specified under element.

• table_layer (str | None) – Layer of the table to use for coloring if color is in sdata.table.var_names. If None, the data in sdata.table.X is used for coloring.

• **kwargs (Any) –

  Additional arguments for customization. This can include:

  datashader_reductionLiteral[

  “sum”, “mean”, “any”, “count”, “std”, “var”, “max”, “min”

  ], default: “sum”

  Reduction method for datashader when coloring by continuous values. Defaults to ‘sum’.

Return type:

SpatialData

Returns:

sd.SpatialData The modified SpatialData object with the rendered shapes.

render_shapes(element=None, color=None, fill_alpha=1.0, groups=None, palette=None, na_color='default', outline_width=1.5, outline_color='#000000', outline_alpha=0.0, cmap=None, norm=None, scale=1.0, method=None, table_name=None, table_layer=None, **kwargs)

Render shapes elements in SpatialData.

In case of no elements specified, “broadcasting” of parameters is applied. This means that for any particular SpatialElement, we validate whether a given parameter is valid. If not valid for a particular SpatialElement the specific parameter for that particular SpatialElement will be ignored. If you want to set specific parameters for specific elements please chain the render functions: pl.render_points(...).pl.render_points(...).pl.show() .

Parameters:

• element (str | None, optional) – The name of the shapes element to render. If None, all shapes elements in the SpatialData object will be used.

• color (str | None) – Can either be string representing a color-like or key in sdata.table.obs. The latter can be used to color by categorical or continuous variables. If element is None, 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 elements.

• fill_alpha (float | int, default 1.0) – 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[str] | 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. If elment is None, broadcasting behaviour is attempted (use the same values for all elements).

• palette (list[str] | str | None) – Palette for discrete annotations. List of valid color names that should be used for the categories. Must match the number of groups. If element is None, 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 (ColorLike | None, default "default" (gets set to "lightgray")) – 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 represent RGB/RGBA values (1.0, 0.0, 0.0, 1.0). When None, the values won’t be shown.

• outline_width (float | int, default 1.5) – Width of the border.

• outline_color (str | list[float], default "#000000") – Color of the border. Can either be a named color (“red”), a hex representation (“#000000”) or a list of floats that represent RGB/RGBA values (1.0, 0.0, 0.0, 1.0). If the hex representation includes alpha, e.g. “#000000ff”, the last two positions are ignored, since the alpha of the outlines is solely controlled by outline_alpha.

• outline_alpha (float | int, default 0.0) – Alpha value for the outline of shapes. Invisible by default.

• cmap (Colormap | str | None, optional) – Colormap for discrete or continuous annotations using ‘color’, see matplotlib.colors.Colormap.

• norm (bool | Normalize, default False) – Colormap normalization for continuous annotations.

• scale (float | int, default 1.0) – Value to scale circles, if present.

• method (str | None, optional) – Whether to use ‘matplotlib’ and ‘datashader’. When None, the method is chosen based on the size of the data.

• table_name (str | None) – Name of the table 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 you want to use different tables for particular elements, as specified under element.

• table_layer (str | None) – Layer of the table to use for coloring if color is in sdata.table.var_names. If None, the data in sdata.table.X is used for coloring.

• **kwargs (Any) –

  Additional arguments for customization. This can include:

  datashader_reductionLiteral[

  “sum”, “mean”, “any”, “count”, “std”, “var”, “max”, “min”

  ], default: “sum”

  Reduction method for datashader when coloring by continuous values. Defaults to ‘sum’.

Notes

• Empty geometries will be removed at the time of plotting.

• An outline_width of 0.0 leads to no border being plotted.

• When passing a color-like to ‘color’, this has precendence over the potential existence as a column name.

Return type:

SpatialData

Returns:

sd.SpatialData The modified SpatialData object with the rendered shapes.

show(coordinate_systems=None, legend_fontsize=None, legend_fontweight='bold', legend_loc='right margin', legend_fontoutline=None, na_in_legend=True, colorbar=True, wspace=None, hspace=0.25, ncols=4, frameon=None, figsize=None, dpi=None, fig=None, title=None, share_extent=True, pad_extent=0, ax=None, return_ax=False, save=None)

Plot the images in the SpatialData object.

Parameters:

• coordinate_systems (list[str] | str | None (default: None)) – Name(s) of the coordinate system(s) to be plotted. If None, all coordinate systems are plotted. If a coordinate system doesn’t contain any relevant elements (as specified in the render_* calls), it is automatically not plotted.

• figsize (tuple[float, float] | None (default: None)) – Size of the figure (width, height) in inches. The size of the actual canvas may deviate from this, depending on the dpi! In matplotlib, the actual figure size (in pixels) is dpi * figsize. If None, the default of matlotlib is used (6.4, 4.8)

• dpi (int | None (default: None)) – Resolution of the plot in dots per inch (as in matplotlib). If None, the default of matplotlib is used (100.0).

• ax (list[Axes] | Axes | None (default: None)) – Matplotlib axes object to plot on. If None, a new figure is created. Works only if there is one image in the SpatialData object.

• ncols (int (default: 4)) – Number of columns in the figure. Default is 4.

• return_ax (bool (default: False)) – Whether to return the axes object created. False by default.

• colorbar (bool (default: True)) – Whether to plot the colorbar. True by default.

• title (list[str] | str | None (default: None)) – The title of the plot. If not provided the plot will have the name of the coordinate system as title.

Return type:

SpatialData

Returns:

sd.SpatialData A SpatialData object.

property sdata: SpatialData

The SpatialData object to provide plotting functions for.