dynamo.pl.grid_vectors

dynamo.pl.grid_vectors(adata, basis='umap', x=0, y=1, ekey='M_s', vkey='velocity_S', color='ntr', layer='X', highlights=None, labels=None, values=None, theme=None, cmap=None, color_key=None, color_key_cmap=None, background='white', ncols=4, pointsize=None, figsize=(6, 4), show_legend='on data', use_smoothed=True, ax=None, sort='raw', aggregate=None, show_arrowed_spines=False, inverse=False, cell_inds='all', method='gaussian', xy_grid_nums=(50, 50), cut_off_velocity=True, quiver_size=None, quiver_length=None, vector='velocity', frontier=False, save_show_or_return='show', save_kwargs={}, s_kwargs_dict={}, q_kwargs_dict={}, **grid_kwargs)[source]

Plot the velocity or acceleration vector of each cell on a grid.

Parameters:

  • adata (AnnData) – an AnnData object.

  • basis (str) – the reduced dimension stored in adata.obsm. The specific basis key will be constructed in the following priority if exits: 1) specific layer input + basis 2) X_ + basis 3) basis. E.g. if basis is PCA, scatters is going to look for 1) if specific layer is spliced, spliced_pca 2) X_pca (dynamo convention) 3) pca. Defaults to “umap”.

  • x (int) – the column index of the low dimensional embedding for the x-axis. Defaults to 0.

  • y (int) – the column index of the low dimensional embedding for the y-axis. Defaults to 1.

  • ekey (str) – the expression key. Defaults to “M_s”.

  • vkey (str) – the velocity key. Defaults to “velocity_S”.

  • color (Union[str, List[str]]) – any column names or gene expression, etc. that will be used for coloring cells. Defaults to “ntr”.

  • layer (str) – the layer of data to use for the scatter plot. Defaults to “X”.

  • highlights (Optional[list]) – the color group that will be highlighted. If highligts is a list of lists, each list is relate to each color element. Defaults to None.

  • labels (Optional[list]) – 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. Defaults to None.

  • values (Optional[list]) – 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. Defaults to None.

  • theme (Optional[Literal['blue', 'red', 'green', 'inferno', 'fire', 'viridis', 'darkblue', 'darkred', 'darkgreen']]) – 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’}. Defaults to None.

  • cmap (Optional[str]) – 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. Defaults to None.

  • color_key (Union[Dict[str, str], List[str], None]) – the method 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. Defaults to None.

  • color_key_cmap (Optional[str]) – 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. Defaults to None.

  • background (Optional[str]) – 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. Defaults to None.

  • ncols (int) – the number of columns for the figure. Defaults to 4.

  • pointsize (Optional[float]) – the scale of the point size. Actual point cell size is calculated as 500.0 / np.sqrt(adata.shape[0]) * pointsize. Defaults to None.

  • figsize (Tuple[float]) – the width and height of a figure. Defaults to (6, 4).

  • show_legend (str) – whether to display a legend of the labels. Defaults to “on data”.

  • use_smoothed (bool) – whether to use smoothed values (i.e. M_s / M_u instead of spliced / unspliced, etc.). Defaults to True.

  • ax (Optional[Axes]) – the matplotlib axes object where new plots will be added to. Only applicable to drawing a single component. Defaults to None.

  • sort (Literal['raw', 'abs', 'neg']) – 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. Defaults to “raw”.

  • aggregate (Optional[str]) – the column in adata.obs that will be used to aggregate data points. Defaults to None.

  • show_arrowed_spines (bool) – whether to show a pair of arrowed spines representing the basis of the scatter is currently using. Defaults to False.

  • inverse (bool) – whether to inverse the direction of the velocity vectors. Defaults to False.

  • cell_inds (Union[str, list]) – the cell index that will be chosen to draw velocity vectors. Can be a list of integers (cell integer indices) or str (Cell names). Defaults to “all”.

  • method (Literal['SparseVFC', 'gaussian']) – method to reconstruct the vector field. Currently it supports either SparseVFC (default) or the empirical method Gaussian kernel method from RNA velocity (Gaussian). Defaults to “gaussian”.

  • xy_grid_nums (Tuple[int, int]) – the number of grids in either x or y axis. Defaults to (50, 50).

  • cut_off_velocity (bool) – whether to remove small velocity vectors from the recovered the vector field grid, either through the simple Gaussian kernel (applicable to 2D) or the powerful sparseVFC approach. Defaults to True.

  • quiver_size (Optional[float]) – the size of quiver. If None, we will use set quiver_size to be 1. Note that quiver quiver_size is used to calculate the head_width (10 x quiver_size), head_length (12 x quiver_size) and headaxislength (8 x quiver_size) of the quiver. This is done via the default_quiver_args function which also calculate the scale of the quiver (1 / quiver_length). Defaults to None.

  • quiver_length (Optional[float]) – the length of quiver. The quiver length which will be used to calculate scale of quiver. Note that befoe applying default_quiver_args velocity values are first rescaled via the quiver_autoscaler function. Scale of quiver indicates the nuumber of data units per arrow length unit, e.g., m/s per plot width; a smaller scale parameter makes the arrow longer. Defaults to None.

  • vector (str) – which vector type will be used for plotting, one of {‘velocity’, ‘acceleration’} or either velocity field or acceleration field will be plotted. Defaults to “velocity”.

  • frontier (bool) – 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. Defaults to False.

  • save_show_or_return (Literal['save', 'show', 'return']) – whether to save, show, or return the generated figure. Defaults to “show”.

  • save_kwargs (Dict[str, Any]) – a dictionary that will be passed to the save_show_ret function. By default, it is an empty dictionary and the save_show_ret function will use the {“path”: None, “prefix”: ‘grid_velocity’, “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.. Defaults to {}.

  • s_kwargs_dict (Dict[str, Any]) – any other kwargs that would be passed to dynamo.pl.scatters. Defaults to {}.

  • q_kwargs_dict (Dict[str, Any]) – any other kwargs that would be passed to pyplot.quiver. Defaults to {}.

  • **grid_kwargs – any other kwargs that would be passed to dynamo.tl.grid_velocity_filter.

Raises:
Return type:

Union[List[Axes], Axes, None]

Returns:

None would be returned by default. If save_show_or_return is set to be return, the matplotlib axes of the generated subplots would be returned.