cellrank.pl.circular_projection

cellrank.pl.circular_projection(adata, keys, backward=False, lineages=None, early_cells=None, lineage_order=None, metric='correlation', normalize_by_mean=True, ncols=4, space=0.25, use_raw=False, text_kwargs=mappingproxy({}), label_distance=1.25, label_rot='best', show_edges=True, key_added=None, figsize=None, dpi=None, save=None, **kwargs)

Visualize fate probabilities in a circular embedding [Jaitin et al., 2014, Velten et al., 2017].

We arrange all computed terminal states evenly spaced around the unit circle and place cells inside the unit circle in a way that reflects their fate probabilities. In other words, the more certain we are that a cell will transition towards a given terminal state, the closer we place it to that terminal state. Uncommitted cells thus reside in the middle of the circle.

Please refer to our manuscript [Lange et al., 2022] to learn more.

Parameters:

• adata (anndata.AnnData) – Annotated data object.

• keys (Union[str, Sequence[str]]) –

  Keys in anndata.AnnData.obs or anndata.AnnData.var_names. Additional keys are:

  • ’kl_divergence’ - as in [Velten et al., 2017], computes KL-divergence between the fate probabilities of a cell and the average fate probabilities. See early_cells for more information.

  • ’entropy’ - as in [Setty et al., 2019], computes entropy over a cells fate probabilities.

• backward (bool) – Direction of the process.

• lineages (Union[str, Sequence[str], None]) – Lineages to plot. If None, plot all lineages.

• early_cells (Union[Mapping[str, Sequence[str]], Sequence[str], None]) – Cell ids or a mask marking early cells used to define the average fate probabilities. If None, use all cells. Only used when ‘kl_divergence’ is in keys. If a dict, key specifies a cluster key in anndata.AnnData.obs and the values specify cluster labels containing early cells.

• lineage_order (Optional[Literal['default', 'optimal']]) –

  Can be one of the following:

  • None - it will determined automatically, based on the number of lineages.

  • ’optimal’ - order lineages optimally by solving the Traveling salesman problem (TSP). Recommended for <= 20 lineages.

  • ’default’ - use the order as specified by lineages.

• metric (Union[str, Callable, ndarray, DataFrame]) – Metric to use when constructing pairwise distance matrix when lineage_order = 'optimal'. For available options, see sklearn.metrics.pairwise_distances().

• normalize_by_mean (bool) – If True, normalize each lineage by its mean probability, as done in [Velten et al., 2017].

• ncols (int) – Number of columns when plotting multiple keys.

• space (float) – Horizontal and vertical space between for matplotlib.pyplot.subplots_adjust().

• use_raw (bool) – Whether to access anndata.AnnData.raw when there are keys in anndata.AnnData.var_names.

• text_kwargs (Mapping[str, Any]) – Keyword arguments for matplotlib.pyplot.text().

• label_distance (float) – Distance at which the lineage labels will be drawn.

• label_rot (Union[Literal['default', 'best'], float]) –

  How to rotate the labels. Valid options are:

  • ’best’ - rotate labels so that they are easily readable.

  • ’default’ - use matplotlib’s default.

  • None - same as ‘default’.

  If a float, all labels will be rotated by this many degrees.

• show_edges (bool) – Whether to show the edges surrounding the simplex.

• key_added (Optional[str]) – Key in anndata.AnnData.obsm where to add the circular embedding. If None, it will be set to ‘X_fate_simplex_{fwd,bwd}’, based on backward.

• figsize (Optional[Tuple[float, float]]) – Size of the figure.

• dpi (Optional[int]) – Dots per inch.

• save (Union[str, Path, None]) – Filename where to save the plot.

• kwargs (Any) – Keyword arguments for scvelo.pl.scatter().

Return type:

None

Returns:

: Nothing, just plots the figure. Optionally saves it based on save.

Also updates adata with the following fields:

• anndata.AnnData.obsm ['{key_added}'] - the circular projection.

• anndata.AnnData.obs ['to_{initial,terminal}_states_{method}'] - the priming degree, if a method is present in keys.