dynamo.pl.cell_wise_vectors_3d

dynamo.pl.cell_wise_vectors_3d(adata, basis='umap', x=0, y=1, z=2, ekey=None, vkey='velocity_S', X=None, V=None, color=None, layer='X', plot_method='pv', background='white', ncols=4, figsize=(6, 4), ax=None, inverse=False, cell_inds='all', vector='velocity', save_show_or_return='show', save_kwargs={}, quiver_3d_kwargs={'alpha': 1, 'arrow_length_ratio': 1, 'cmap': <matplotlib.colors.LinearSegmentedColormap object>, 'edgecolors': 'white', 'length': 8, 'linewidth': 1, 'norm': <matplotlib.colors.Normalize object>}, grid_color=None, axis_label_prefix=None, axis_labels=None, elev=None, azim=None, alpha=None, show_magnitude=True, titles=None, highlights=None, labels=None, values=None, theme=None, plotly_color='Reds', cmap=None, color_key=None, color_key_cmap=None, pointsize=None, use_smoothed=True, sort='raw', aggregate=None, show_arrowed_spines=False, frontier=False, s_kwargs_dict={}, **cell_wise_kwargs)[source]

Plot the velocity or acceleration vector of each cell.

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.

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

  • ekey (Optional[str]) – the expression key. Defaults to None.

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

  • X (Union[ndarray, spmatrix, None]) – the expression array. If None, the array would be determined by ekey provided. Defaults to None.

  • V (Union[ndarray, spmatrix, None]) – the velocity array. If None, the array would be determined by vkey provided. Defaults to None.

  • color (Union[str, List[str], None]) – 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”.

  • plot_method (Literal['pv', 'matplotlib']) – the method to plot 3D vectors. Options include pv (pyvista) and matplotlib.

  • background (Optional[str]) – the background color of the figure. Defaults to “white”.

  • ncols (int) – the number of sub-plot columns. Defaults to 4.

  • figsize (Tuple[float]) – the size of each sub-plot panel. Defaults to (6, 4).

  • ax (Optional[Axes]) – the axes to plot on. Only work when there is one graph to plot. If None, new axes would be created. Defaults to None.

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

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

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

  • save_show_or_return (str) – 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”: ‘cell_wise_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 {}.

  • quiver_3d_kwargs (Dict[str, Any]) – any other kwargs to be passed to pyplot.quiver. Defaults to { “zorder”: 3, “length”: 2, “linewidth”: 5, “arrow_length_ratio”: 5, “norm”: cm.colors.Normalize(), “cmap”: cm.PRGn, }.

  • grid_color (Optional[str]) – the color of the grid lines. Defaults to None.

  • axis_label_prefix (Optional[str]) – the prefix of the axis labels. Defaults to None.

  • axis_labels (Optional[List[str]]) – the axis labels. Defaults to None.

  • elev (Optional[float]) – the elevation angle in degrees rotates the camera above the plane pierced by the vertical axis, with a positive angle corresponding to a location above that plane. Defaults to None.

  • azim (Optional[float]) – the azimuthal angle in degrees rotates the camera about the vertical axis, with a positive angle corresponding to a right-handed rotation. Defaults to None.

  • alpha (Optional[float]) – the transparency of the colors. Defaults to None.

  • show_magnitude (bool) – whether to show original values or normalize the data. Defaults to False.

  • titles (Optional[List[str]]) – the titles of the subplots. Defaults to None.

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

  • plotly_color (str) – the color of the Plotly Cone plot. It must be an array containing arrays mapping a normalized value to a rgb, rgba, hex, hsl, hsv, or named color string.

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

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

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

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

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

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

Raises:

ValueError – invalid x, y, or z.

Return type:

ndarray

Returns:

None will be returned by default. If save_show_or_return is set to ‘return’, an array of axes of the subplots would be returned.