dynamo.pl.phase_portraits
- dynamo.pl.phase_portraits(adata, genes, x=0, y=1, pointsize=None, vkey=None, ekey=None, basis='umap', log1p=True, color='cell_cycle_phase', use_smoothed=True, highlights=None, discrete_continous_div_themes=None, discrete_continous_div_cmap=None, discrete_continous_div_color_key=[None, None, None], discrete_continous_div_color_key_cmap=None, figsize=(6, 4), ncols=None, legend='upper left', background=None, show_quiver=False, quiver_size=None, quiver_length=None, no_vel_u=True, frontier=True, q_kwargs_dict={}, show_arrowed_spines=None, save_show_or_return='show', save_kwargs={}, **kwargs)[source]
Draw the phase portrait, expression values, velocity on the low dimensional embedding.
Note that this function allows to manually set the theme, cmap, color_key and color_key_cmap for the phase portrait, expression and velocity subplots. When the background is ‘black’, the default themes for each of those subplots are [“glasbey_dark”, “inferno”, “div_blue_black_red”], respectively. When the background is ‘black’, the default themes are “glasbey_white”, “viridis”, “div_blue_red”.
- Parameters:
adata (
AnnData) – an AnnData object.genes (
List[str]) – a list of gene names that are going to be visualized.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.pointsize (
Optional[float]) – the scale of the point size. Actual point cell size is calculated as 2500.0 / np.sqrt(adata.shape[0]) * pointsize. Defaults to None.vkey (
Optional[str]) – the velocity key used for visualizing the magnitude of velocity. Can be either velocity in the layers slot or the keys in the obsm slot. Defaults to None.ekey (
Optional[str]) – the layer of data to represent the gene expression level. Defaults to None.basis (
str) – the key of the low dimensional embedding will be used to visualize the cell. Defaults to “umap”.log1p (
bool) – whether to log1p transform the expression so that visualization can be robust to extreme values. Defaults to True.color (
str) – the group to be used to color cells. It would only be used for the phase portrait because the other two plots are colored by the velocity magnitude or the gene expression value respectively. Defaults to “cell_cycle_phase”.use_smoothed (
bool) – Whether to use smoothed 1/2-nd moments as gene expression for the first and third columns. This is useful for checking the confidence of transition genes. For example, you may see a very nice linear pattern for some genes with the smoothed expression but this could just be an artificially generated when the number of expressed cells is very low. This raises red flags for the quality of the velocity values we learned for those genes. And we recommend to set the higher values (for example, 10% of all cells) for min_cell_s, min_cell_u or shared_count of the fg_kwargs argument of the dyn.pl.receipe_monocle. Note that this is often related to the small single cell datasets (like plate-based scRNA-seq or scSLAM-seq/NASC-seq, etc). Defaults to True.highlights (
Optional[list]) – the color group to be highlighted. If highligts is a list of lists, each list is relate to each color element. Defaults to None.discrete_continous_div_themes (
Optional[list]) –the discrete, continous and divergent color themes to use for plotting, respectively. The description for each element in the list is as following. 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.
discrete_continous_div_cmap (
Optional[list]) – the names of discrete, continous and divergent matplotlib colormap to use for coloring or shading points. The description for each element in the list is as following. 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.discrete_continous_div_color_key (
list) – A list to assign discrete, continous and divergent 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, None, None].discrete_continous_div_color_key_cmap (
Optional[list]) – the names of discrete, continous and divergent 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.figsize (
Tuple[float,float]) – the width and height of each panel in the figure. Defaults to (6, 4).ncols (
Optional[int]) – number of columns in each facet grid. Defaults to None.legend (
str) – the position to draw the legend. Legend is drawn by seaborn with “brief” mode, numeric hue and size v ariables will be represented with a sample of evenly spaced values. By default, legend is drawn on top of cells. Defaults to “upper left”.background (
Optional[str]) – the background color. If set to None the face color of the figure would be used. Defaults to None.show_quiver (
bool) – Whether to show the quiver plot. If velocity for x component (corresponds to either spliced, total RNA, protein, etc.) or y component (corresponds to either unspliced, new RNA, protein, etc.) are both calculated, quiver represents velocity for both components otherwise the uncalculated component (usually y component) will be set to be 0. Defaults to False.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 before applying default_quiver_args velocity values are first rescaled via the quiver_autoscaler function. Scale of quiver indicates the number 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.no_vel_u (
bool) – whether to not show velocity U (velocity of unspliced RNAs). Defaults to True.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 True.q_kwargs_dict (
dict) – the dictionary of the quiver arguments. The default setting of quiver argument is identical to that used in the cell_wise_velocity and grid_velocity. Defaults to {}.show_arrowed_spines (
Optional[bool]) – whether to show a pair of arrowed spines represeenting the basis of the scatter is currently using. If None, only the first panel in the expression / velocity plot will have the arrowed spine. Defaults to None.save_show_or_return (
Literal['save','show','return']) – whether to save, show or return the figure. Defaults to “show”.save_kwargs (
dict) –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”: ‘phase_portraits’, “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 {}.
**kwargs – additional parameters that will be passed to plt.scatter function.
- Raises:
ValueError – missing velocity data in the AnnData object.
ValueError – cannot find layer with given v_key.
ValueError – missing velocity_gamma column in the AnnData object.
ValueError – missing velocity_gamma column in the AnnData object.
ValueError – corrupted AnnData object missing basic labeled/unlabeled or spliced/unspliced data.
NotImplementedError – invalid save_show_or_return.
- Return type:
- Returns:
None would be returned in default and the plotted figure would be shown directly. The matplotlib plot would show 1) the phase portrait of each category used in velocity embedding, cells’ low dimensional embedding, colored either by 2) the gene expression level or 3) the velocity magnitude values. If set save_show_or_return=’return’ as a kwarg, the axes of the plot would be returned.