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 (Union[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 (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 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 (Union[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 (Optional[str]) – 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 (Optional[Tuple[float, float]]) – Size of the figure.

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

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

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

Return type:

None

Returns:

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