Ctrl+K

Plotting (.pl)

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(elements=None, channel=None, cmap=None, norm=None, na_color=(0.0, 0.0, 0.0, 0.0), palette=None, alpha=1.0, quantiles_for_norm=None, scale=None, **kwargs)#

Render image elements in SpatialData.

Parameters:

  • elements (list[str] | str | None, optional) – The name(s) of the image element(s) to render. If None, all image elements in the SpatialData object will be used. If a string is provided, it is converted into a single-element list.

  • channel (list[str] | list[int] | str | int | None, optional) – 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] | Colormap | str | None, optional) – 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 (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) – Optional pair of floats (pmin < pmax, 0-100) which will be used for quantile normalization.

  • scale (list[str] | str | None, optional) –

    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 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. 4) A list matching the list of elements. Can contain None, scale names, or “full”. Each scale applies to the corresponding element.

  • 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(elements=None, color=None, groups=None, contour_px=3, outline=False, palette=None, cmap=None, norm=None, na_color=(0.0, 0.0, 0.0, 0.0), outline_alpha=1.0, fill_alpha=0.3, scale=None, table_name=None, **kwargs)#

Render labels elements in SpatialData.

Parameters:

  • 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 (list[str | None] | str | None) – Can either be string(s) representing a color-like or key(s) in 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. 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 skimage.morphology.erosion().

  • outline (bool, default False) – Whether to plot boundaries around segmentation masks.

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

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

  • na_color (ColorLike | None, optional) – Color to be used for NAs values, if present.

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

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

  • scale (list[str] | str | None, optional) –

    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! 4) List that is matched to the list of elements (can contain None, scale names or “full”).

  • table_name (Union[list[str], str, None] (default: None)) – 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 (Any) – Additional arguments to be passed to cmap and norm.

Return type:

SpatialData

Returns:

None

render_points(elements=None, color=None, alpha=1.0, groups=None, palette=None, na_color='lightgrey', cmap=None, norm=None, size=1.0, table_name=None, **kwargs)#

Render points elements in SpatialData.

Parameters:

  • 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 (list[str | None] | str | None) – Can either be string(s) representing a color-like or key(s) in 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[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. 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. 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 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

  • table_name (Union[list[str], str, None] (default: None)) – 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 (Any) – Additional arguments to be passed to cmap and norm.

Return type:

SpatialData

Returns:

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

render_shapes(elements=None, color=None, fill_alpha=1.0, groups=None, palette=None, na_color='lightgrey', outline=False, outline_width=1.5, outline_color='#000000ff', outline_alpha=1.0, cmap=None, norm=False, scale=1.0, table_name=None, **kwargs)#

Render shapes elements in SpatialData.

Parameters:

  • 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 (list[str | None] | str | None) – Can either be string(s) representing a color-like or key(s) in 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. 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. 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”.

  • 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 represent RGB/RGBA values (1.0, 0.0, 0.0, 1.0). When None, the values won’t be shown.

  • outline (bool, default False) – If True, a border around the shape elements is plotted.

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

  • outline_color (str | list[float], default "#000000ff") – Color of the border. 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).

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

  • 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.

  • table_name (Union[list[str], str, None] (default: None)) – 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 (Any) – Additional arguments to be passed to cmap and norm.

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 (Union[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 (Optional[tuple[float, float]] (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 (Optional[int] (default: None)) – Resolution of the plot in dots per inch (as in matplotlib). If None, the default of matplotlib is used (100.0).

  • ax (Union[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 (Union[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.

Contents