dynamo.pl.state_graph

dynamo.pl.state_graph(adata, group=None, transition_threshold=0.001, keep_only_one_direction=True, edge_scale=1, state_graph=None, edgecolor=None, facecolor=None, graph_alpha=None, basis='umap', x=0, y=1, color='ntr', layer='X', highlights=None, labels=None, values=None, theme=None, cmap=None, color_key=None, color_key_cmap=None, background=None, ncols=4, pointsize=None, figsize=(6, 4), show_legend=True, use_smoothed=True, show_arrowed_spines=False, ax=None, sort='raw', frontier=False, save_show_or_return='show', save_kwargs={}, s_kwargs_dict={'alpha': 1}, **kwargs)

Plot a summarized cell type (state) transition graph. This function tries to create a model that summarizes the possible cell type transitions based on the reconstructed vector field function.

Parameters:

• adata (AnnData) – an AnnData object.

• group (Optional[str]) – the column in adata.obs that will be used to aggregate data points for the purpose of creating a cell type transition model. Defaults to None.

• transition_threshold (float) – the threshold of cell fate transition. Transition will be ignored if below this threshold. Defaults to 0.001.

• keep_only_one_direction (bool) – whether to only keep the higher transition between two cell type. That is if the transition rate from A to B is higher than B to A, only edge from A to B will be plotted. Defaults to True.

• edge_scale (float) – the scaler that can be used to scale the edge width of drawn transition graph. Defaults to 1.

• state_graph (Optional[ndarray]) – the lumped transition graph between cell states (e.g. cell clusters or types). Defaults to None.

• edgecolor (Union[None, ndarray, DataFrame]) – the edge color of the arcs that corresponds to the lumped transition graph between cell states. Defaults to None.

• facecolor (Union[None, ndarray, DataFrame]) – the edge color of the arcs that corresponds to the lumped transition graph between cell states. Defaults to None.

• graph_alpha (Union[None, ndarray, DataFrame]) – the alpha of the arcs that corresponds to the lumped transition graph between cell states. Defaults to None.

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

• color (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, float]) – the width and height of a figure. Defaults to (6, 4).

• show_legend (bool) – 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.

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

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

• 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. If contour is set to be True, frontier will be ignored as contour also add an outlier for data points. 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”: ‘state_graph’, “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 {“alpha”: 1}.

Return type:

Union[Tuple[Axes, List[str], Literal['white', 'black']], Tuple[List[Axes], List[str], Literal['white', 'black']], None]

Returns:

None would be returned by default. If save_show_or_return is set to be return, the matplotlib axes object of the generated plots, the list of colors used and the font color would be returned.