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', 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={'arrow_length_ratio': 5, 'cmap': <matplotlib.colors.LinearSegmentedColormap object>, 'length': 2, 'linewidth': 5, 'norm': <matplotlib.colors.Normalize object>, 'zorder': 3}, grid_color=None, axis_label_prefix=None, axis_labels=None, elev=None, azim=None, alpha=None, show_magnitude=False, titles=None, **cell_wise_kwargs)[source]

Plot the velocity or acceleration vector of each cell.

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

  • 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_fig function. By default, it is an empty dictionary an the save_fig 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.


ValueError – invalid x, y, or z.

Return type:



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.