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)[source]#

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.

Parameters:
adata AnnData

Annotated data object.

keys str | Sequence[str]

Keys in obs or 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 str | Sequence[str] | None

Lineages to plot. If None, plot all lineages.

early_cells 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 the keys. If a dict, key specifies a cluster key in 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 be 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 str | Callable | ndarray | DataFrame

Metric to use when constructing pairwise distance matrix when lineage_order = 'optimal'. For available options, see 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 subplots_adjust().

use_raw bool

Whether to access raw when there are keys in var_names.

text_kwargs Mapping[str, Any]

Keyword arguments for 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'.

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

show_edges bool

Whether to show the edges surrounding the simplex.

key_added str | None

Key in obsm where to add the circular embedding. If None, it will be set to 'X_fate_simplex_{fwd,bwd}', based on the backward.

figsize tuple[float, float] | None

Size of the figure.

dpi int | None

Dots per inch.

save str | Path | None

Filename where to save the plot.

kwargs Any

Keyword arguments for embedding().

Return type:

None

Returns:

Nothing, just plots the figure. Optionally saves it based on save. Also updates adata with the following fields: