spateo.plotting.static.scatters =============================== .. py:module:: spateo.plotting.static.scatters Functions --------- .. autoapisummary:: spateo.plotting.static.scatters.scatters Module Contents --------------- .. py:function:: scatters(adata: anndata.AnnData, basis: Union[str, list] = 'umap', vf_key: Optional[str] = None, X_grid: Optional[numpy.ndarray] = None, V: Optional[numpy.ndarray] = None, x: int = 0, y: int = 1, z: int = 2, color: Union[str, list] = 'ntr', layer: Union[str, list] = 'X', highlights: Optional[list] = None, labels: Optional[list] = None, values: Optional[list] = None, theme: Optional[str] = None, cmap: Optional[str] = None, color_key: Union[dict, list] = None, color_key_cmap: Optional[str] = None, background: Optional[str] = None, ncols: int = 4, pointsize: Union[None, float] = None, figsize: tuple = (6, 4), show_legend='on data', use_smoothed: bool = True, aggregate: Optional[str] = None, show_arrowed_spines: bool = False, ax: Optional[matplotlib.axes.Axes] = None, sort: str = 'raw', save_show_or_return: typing_extensions.Literal[save, show, return, both, all] = 'show', save_kwargs: Optional[Dict] = None, return_all: bool = False, add_gamma_fit: bool = False, frontier: bool = False, contour: bool = False, ccmap: Optional[str] = None, alpha: float = 0.1, calpha: float = 0.4, sym_c: bool = False, smooth: bool = False, dpi: int = 100, inset_dict: dict = {}, marker: str = None, group: str = None, add_group_gamma_fit: bool = False, affine_transform_degree: int = None, affine_transform_A: Optional[numpy.ndarray] = None, affine_transform_b: Optional[numpy.ndarray] = None, stack_colors: bool = False, stack_colors_threshold: float = 0.001, stack_colors_title: str = 'stacked colors', stack_colors_legend_size: int = 2, stack_colors_cmaps: Optional[str] = None, despline: bool = True, deaxis: bool = True, despline_sides: Union[None, List[str]] = None, projection: str = '2d', geo: bool = False, boundary_width: float = 0.2, boundary_color: str = 'black', aspect: str = 'auto', slices: Optional[int] = None, img_layers: Optional[int] = None, vf_plot_method: typing_extensions.Literal[cell, grid, stream] = 'cell', vf_kwargs: Optional[Dict[str, Union[str, int, float]]] = None, **kwargs) -> Union[None, matplotlib.axes.Axes] Plot an embedding as points. Currently, this only works for 2D embeddings. While there are many optional parameters to further control and tailor the plotting, you need only pass in the trained/fit umap model to get results. This plot utility will attempt to do the hard work of avoiding overplotting issues, and make it easy to automatically colour points by a categorical labelling or numeric values. This method is intended to be used within a Jupyter notebook with ``%matplotlib inline``. :param adata: :class:`~anndata.AnnData` an Anndata object :param basis: `str` The reduced dimension. :param vf_key: Optional, key in .obsm containing vector field information :param X_grid: Optional, array containing grid points for vector field plots :param V: Optional, array containing vector fields :param x: `int` (default: `0`) The column index of the low dimensional embedding for the x-axis. :param y: `int` (default: `1`) The column index of the low dimensional embedding for the y-axis. :param color: `string` (default: `ntr`) Any column names or gene expression, etc. that will be used for coloring cells. :param layer: `str` (default: `X`) The layer of data to use for the scatter plot. :param highlights: `list` (default: None) Which color group will be highlighted. if highlights is a list of lists - each list is relate to each color element. :param labels: array, shape (n_samples,) (optional, default None) An array of labels (assumed integer or categorical), one for each data sample. This will be used for coloring the points in the plot according to their label. Note that this option is mutually exclusive to the ``values`` option. :param values: array, shape (n_samples,) (optional, default None) An array of values (assumed float or continuous), one for each sample. This will be used for coloring the points in the plot according to a colorscale associated to the total range of values. Note that this option is mutually exclusive to the ``labels`` option. :param theme: string (optional, default None) A color theme to use for plotting. A small set of predefined themes are provided which have relatively good aesthetics. Available themes are: * 'blue' * 'red' * 'green' * 'inferno' * 'fire' * 'viridis' * 'darkblue' * 'darkred' * 'darkgreen' :param cmap: string (optional, default 'Blues') The name of a matplotlib colormap to use for coloring or shading points. If no labels or values are passed this will be used for shading points according to density (largely only of relevance for very large datasets). If values are passed this will be used for shading according the value. Note that if theme is passed then this value will be overridden by the corresponding option of the theme. :param color_key: dict or array, shape (n_categories) (optional, default None) A way to assign colors to categoricals. This can either be an explicit dict mapping labels to colors (as strings of form '#RRGGBB'), or an array like object providing one color for each distinct category being provided in ``labels``. Either way this mapping will be used to color points according to the label. Note that if theme is passed then this value will be overridden by the corresponding option of the theme. :param color_key_cmap: The name of a matplotlib colormap to use for categorical coloring. If an explicit ``color_key`` is not given a color mapping for categories can be generated from the label list and selecting a matching list of colors from the given colormap. Note that if theme is passed then this value will be overridden by the corresponding option of the theme. :param background: string or None (optional, default 'None`) The color of the background. Usually this will be either 'white' or 'black', but any color name will work. Ideally one wants to match this appropriately to the colors being used for points etc. This is one of the things that themes handle for you. Note that if theme is passed then this value will be overridden by the corresponding option of the theme. :param ncols: int (optional, default `4`) Number of columns for the figure. :param pointsize: `None` or `float` (default: None) The scale of the point size. Actual point cell size is calculated as `500.0 / np.sqrt(adata.shape[0]) * pointsize` :param figsize: `None` or `[float, float]` (default: None) The width and height of a figure. :param show_legend: bool (optional, default True) Whether to display a legend of the labels :param use_smoothed: bool (optional, default True) Whether to use smoothed values (i.e. M_s / M_u instead of spliced / unspliced, etc.). :param aggregate: `str` or `None` (default: `None`) The column in adata.obs that will be used to aggregate data points. :param show_arrowed_spines: bool (optional, default False) Whether to show a pair of arrowed spines representing the basis of the scatter is currently using. :param ax: `matplotlib.Axis` (optional, default `None`) The matplotlib axes object where new plots will be added to. Only applicable to drawing a single component. :param sort: `str` (optional, default `raw`) The method to reorder data so that high values points will be on top of background points. Can be one of {'raw', 'abs', 'neg'}, i.e. sorted by raw data, sort by absolute values or sort by negative values. :param save_show_or_return: Whether to save, show or return the figure. If "both", it will save and plot the figure at the same time. If "all", the figure will be saved, displayed and the associated axis and other object will be return. :param save_kwargs: A dictionary that will be passed to the save_fig function. By default, it is an empty dictionary and the save_fig function will use the {"path": None, "prefix": 'scatter', "dpi": None, "ext": 'pdf', "transparent": True, "close": True, "verbose": True} as its parameters. Otherwise, you can provide a dictionary that properly modify those keys according to your needs. :param return_all: `bool` (default: `False`) Whether to return all the scatter related variables. Default is False. :param add_gamma_fit: `bool` (default: `False`) Whether to add the line of the gamma fitting. This will automatically turn on if `basis` points to gene names and those genes have went through gamma fitting. :param frontier: `bool` (default: `False`) Whether to add the frontier. Scatter plots can be enhanced by using transparency (alpha) in order to show area of high density and multiple scatter plots can be used to delineate a frontier. See matplotlib tips & tricks cheatsheet (https://github.com/matplotlib/cheatsheets). Originally inspired by figures from scEU-seq paper: https://science.sciencemag.org/content/367/6482/1151. If `contour` is set to be True, `frontier` will be ignored as `contour` also add an outlier for data points. :param contour: `bool` (default: `False`) Whether to add an countor on top of scatter plots. We use tricontourf to plot contour for non-gridded data. The shapely package was used to create a polygon of the concave hull of the scatters. With the polygon we then check if the mean of the triangulated points are within the polygon and use this as our condition to form the mask to create the contour. We also add the polygon shape as a frontier of the data point (similar to when setting `frontier = True`). When the color of the data points is continuous, we will use the same cmap as for the scatter points by default, when color is categorical, no contour will be drawn but just the polygon. cmap can be set with `ccmap` argument. See below. This has recently changed to use seaborn's kdeplot. :param ccmap: `str` or `None` (default: `None`) The name of a matplotlib colormap to use for coloring or shading points the contour. See above. :param calpha: `float` (default: `0.4`) Contour alpha value passed into sns.kdeplot. The value should be inbetween [0, 1] :param sym_c: `bool` (default: `False`) Whether do you want to make the limits of continuous color to be symmetric, normally this should be used for plotting velocity, jacobian, curl, divergence or other types of data with both positive or negative values. :param smooth: `bool` or `int` (default: `False`) Whether do you want to further smooth data and how much smoothing do you want. If it is `False`, no smoothing will be applied. If `True`, smoothing based on one step diffusion of connectivity matrix (`.uns['moment_cnn'] will be applied. If a number larger than 1, smoothing will based on `smooth` steps of diffusion. :param dpi: `float`, (default: 100.0) The resolution of the figure in dots-per-inch. Dots per inches (dpi) determines how many pixels the figure comprises. dpi is different from ppi or points per inches. Note that most elements like lines, markers, texts have a size given in points so you can convert the points to inches. Matplotlib figures use Points per inch (ppi) of 72. A line with thickness 1 point will be 1./72. inch wide. A text with fontsize 12 points will be 12./72. inch heigh. Of course if you change the figure size in inches, points will not change, so a larger figure in inches still has the same size of the elements.Changing the figure size is thus like taking a piece of paper of a different size. Doing so, would of course not change the width of the line drawn with the same pen. On the other hand, changing the dpi scales those elements. At 72 dpi, a line of 1 point size is one pixel strong. At 144 dpi, this line is 2 pixels strong. A larger dpi will therefore act like a magnifying glass. All elements are scaled by the magnifying power of the lens. see more details at answer 2 by @ImportanceOfBeingErnest: https://stackoverflow.com/questions/47633546/relationship-between-dpi-and-figure-size :param inset_dict: `dict` (default: {}) A dictionary of parameters in inset_ax. Example, something like {"width": "5%", "height": "50%", "loc": 'lower left', "bbox_to_anchor": (0.85, 0.90, 0.145, 0.145), "bbox_transform": ax.transAxes, "borderpad": 0} See more details at https://matplotlib.org/api/_as_gen/mpl_toolkits.axes_grid1.inset_locator.inset_axes.html or https://stackoverflow.com/questions/39803385/what-does-a-4-element-tuple-argument-for-bbox-to-anchor-mean -in-matplotlib :param marker: `str` (default: None) The marker style. marker can be either an instance of the class or the text shorthand for a particular marker. See matplotlib.markers for more information about marker styles. :param group: The key to the column in adata.obs that points to cell groups that will be used to include the gamma fittings. :param add_group_gamma_fit: Whether or not to add the gamma fitting line for each cell group. :param affine_transform_degree: Transform coordinates of points according to some degree. :param affine_transform_A: Coefficients in affine transformation Ax + b. 2D for now. :param affine_transform_b: Bias in affine transformation Ax + b. :param stack_colors: Whether to stack all color on the same ax passed above. Currently only support 18 sequential matplotlib default cmaps assigning to different color groups. (#colors should be smaller than 18, reuse if #colors > 18. To-do: generate cmaps according to #colors) :param stack_colors_threshold: A threshold for filtering points values < threshold when drawing each color. E.g. if you do not want points with values < 1 showing up on axis, set threshold to be 1 :param stack_colors_title: The title for the stack_color plot. :param stack_colors_legend_size: Control the legend size in stack color plot. :param stack_colors_cmaps: The colormap used to stack different genes in a single plot. :param despline: Whether to remove splines of the figure. :param despline_sides: Which side of splines should be removed. Can be any combination of `["bottom", "right", "top", "left"]`. :param deaxis: Whether to remove axis ticks of the figure. :param projection: The projection of the figure. Can be "2d", "3d", "polar", etc. :param geo: `bool` (default: `False`) Use geometry info or not. :param boundary_width: `float`, (default: 0.2) The line width of boundary. :param boundary_color: (default: "black") The color value of boundary. :param aspect: Set the aspect of the axis scaling, i.e. the ratio of y-unit to x-unit. In physical spatial plot, the default is 'equal'. See more details at: https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_aspect.html :param slices: The index to the tissue slice, will used in adata.uns["spatial"][slices]. :param img_layers: The index to the (staining) image of a tissue slice, will be used in adata.uns["spatial"][slices]["images"]. :param vf_plot_method: The method used to plot the vector field. Can be one of the following: 'cell': Plot the vector field at the center of each cell. 'grid': Plot the vector field on a grid. 'stream': Plot the vector field as stream lines. :param vf_kwargs: Optional dictionary containing parameters for vector field plotting :param kwargs: Additional arguments passed to plt functions (plt.scatters, plt.quiver, plt.streamplot). :returns: Either None or a matplotlib axis with the relevant plot displayed. If you are using a notbooks and have ``%matplotlib inline`` set then this will simply display inline. :rtype: result