pegasus.spatial

pegasus.spatial(data, attrs=None, basis='spatial', resolution='hires', cmaps='viridis', restrictions=None, show_background=False, palettes=None, vmin=None, vmax=None, alpha=1.0, alpha_img=1.0, nrows=None, ncols=None, y_flip=True, margin_percent=0.05, aspect='equal', dpi=300.0, return_fig=False, **kwargs)[source]

Scatter plot on spatial coordinates. This function is inspired by SCANPY’s pl.spatial function.

Parameters

  • data (pegasusio.MultimodalData or pegasusio.UnimodalData or anndata.AnnData) – Use current selected modality in data.

  • attr (str, optional, default: None) – Color scatter plots by attribute ‘attr’. This attribute should be one key in data.obs, data.var_names (e.g. one gene) or data.obsm (attribute has the format of ‘obsm_key@component’, like ‘X_pca@0’). If it is categorical, a palette will be used to color each category separately. Otherwise, a color map will be used. If None, just plot data points of the same color.

  • basis (str, optional, default: spatial) – Basis to be used to generate spatial plots. Must be the 2D array showing the spatial coordinates of data points.

  • resolution (str, optional, default: hires) – Use the spatial image whose value is specified in data.img['image_id'] to show in background. For 10X Visium data, user can either specify hires or lowres to use High or Low resolution spatial images, respectively. Alternatively, if data.img does not exist, then no spatial image will be shown.

  • cmaps (str or List[str], optional, default: viridis) – The colormap(s) for plotting numeric attributes. The default viridis colormap theme follows the spatial plot function in SCANPY (scanpy.pl.spatial).

  • restrictions (str or List[str], optional, default: None) – A list of restrictions to subset data for plotting. There are two types of restrictions: global restriction and attribute-specific restriction. Global restriction appiles to all attributes in attrs and takes the format of ‘key:value,value…’, or ‘key:~value,value…’. This restriction selects cells with the data.obs[key] values belong to ‘value,value…’ (or not belong to if ‘~’ shows). Attribute-specific restriction takes the format of ‘attr:key:value,value…’, or ‘attr:key:~value,value…’. It only applies to one attribute ‘attr’. If ‘attr’ and ‘key’ are the same, one can use ‘.’ to replace ‘key’ (e.g. cluster_labels:.:value1,value2).

  • show_background (bool, optional, default: False) – Only applicable if restrictions is set. By default, only data points selected are shown. If show_background is True, data points that are not selected will also be shown.

  • palettes (str or List[str], optional, default: None) – Used for setting colors for every categories in categorical attributes. Each string in palettes takes the format of ‘attr:color1,color2,…,colorn’. ‘attr’ is the categorical attribute and ‘color1’ - ‘colorn’ are the colors for each category in ‘attr’ (e.g. ‘cluster_labels:black,blue,red,…,yellow’). If there is only one categorical attribute in ‘attrs’, palletes can be set as a single string and the ‘attr’ keyword can be omitted (e.g. “blue,yellow,red”).

  • vmin (float, optional, default: None) – Minimum value to show on a numeric scatter plot (feature plot).

  • vmax (float, optional, default: None) – Maximum value to show on a numeric scatter plot (feature plot).

  • alpha (float or List[float], optional, default: 1.0) – Alpha value for blending the attribute layers, from 0.0 (transparent) to 1.0 (opaque). If this is a list, the length must match attrs, which means we set a separate alpha value for each attribute.

  • alpha_img (float, optional, default: 1.0) – Alpha value for blending the background spatial image, from 0.0 (transparent) to 1.0 (opaque).

  • nrows (int, optional, default: None) – Number of rows in the figure. If not set, pegasus will figure it out automatically.

  • ncols (int, optional, default: None) – Number of columns in the figure. If not set, pegasus will figure it out automatically.

  • y_flip (bool, optional, default: False) – Set to True if flipping the y axis is needed. This is for the case when y-coordinate origin starts from the top. For 10x Visium data, if resolution is specified, this parameter is then ignored.

  • margin_percent (float, optional, default: 0.05) – The margin is set to ``margin_percent``*100% of the smaller edge of the image size in each of the 4 sides.

  • aspect (str, optional (default: equal)) – Set the aspect of the axis scaling, i.e. the ratio of y-unit to x-unit. Set auto to fill the position rectangle with data; equal for the same scaling for x and y. It applies to all subplots.

  • dpi (float, optional, default: 300.0) – The resolution of the figure in dots-per-inch.

  • return_fig (bool, optional, default: False) – Return a Figure object if True; return None otherwise.

Returns

A matplotlib.figure.Figure object containing the dot plot if return_fig == True

Return type

Figure object

Examples

>>> pg.spatial(data, attrs=['louvain_labels', 'Channel'])
>>> pg.spatial(data, attrs=['CD14', 'TRAC'], resolution='lowres')