cellrank.tl.terminal_states(adata, estimator=<class 'cellrank.tl.estimators.terminal_states._gpcca.GPCCA'>, mode=VelocityMode.DETERMINISTIC, n_states=None, cluster_key=None, key=None, force_recompute=False, show_plots=False, copy=False, return_estimator=False, fit_kwargs=mappingproxy({}), **kwargs)[source]

Find terminal states of a dynamic process of single cells based on RNA velocity [La Manno et al., 2018].

The function models dynamic cellular processes as a Markov chain, where the transition matrix is computed based on the velocity vector of each individual cell. Based on this Markov chain, we provide two estimators to compute terminal states, both of which are based on spectral methods.

For the estimator cellrank.tl.estimators.GPCCA, cells are fuzzily clustered into macrostates, using Generalized Perron Cluster Cluster Analysis [Reuter et al., 2018]. In short, this coarse-grains the Markov chain into a set of macrostates representing the slow time-scale dynamics, i.e. transitions between these macrostates are rare. The most stable ones of these will represent terminal, while the others represent intermediate macrostates.

For the estimator cellrank.tl.estimators.CFLARE, cells are filtered into transient/recurrent cells using the left eigenvectors of the transition matrix and clustered into distinct groups of terminal states using the right eigenvectors of the transition matrix of the Markov chain.

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

  • estimator (ABCMeta) – Estimator class to use to compute the terminal states.

  • mode (str) –

    How to compute transition probabilities. Valid options are:

    • ’deterministic’ - deterministic computation that doesn’t propagate uncertainty.

    • ’monte_carlo’ - Monte Carlo average of randomly sampled velocity vectors.

    • ’stochastic’ - second order approximation, only available when jax is installed.

    • ’sampling’ - sample 1 transition matrix from the velocity distribution.

  • n_states (Optional[int]) – If you know how many terminal states you are expecting, you can provide this number. Otherwise, an eigengap heuristic is used.

  • cluster_key (Optional[str]) – Key from adata.obs where cluster annotations are stored. These are used to give names to the terminal states.

  • key (Optional[str]) – Key in adata.obsp where the transition matrix is saved. If not found, compute a new one using cellrank.tl.transition_matrix().

  • force_recompute (bool) – Whether to always recompute the transition matrix even if one exists.

  • show_plots (bool) – Whether to show plots of the spectrum and eigenvectors in the embedding.

  • n_jobs – Number of parallel jobs. If -1, use all available cores. If None or 1, the execution is sequential.

  • copy (bool) – Whether to update the existing adata object or to return a copy.

  • return_estimator (bool) – Whether to return the estimator. Only available when copy=False.

  • fit_kwargs (Mapping) – Keyword arguments for cellrank.tl.BaseEstimator.fit(), such as n_cells.

  • kwargs – Keyword arguments for cellrank.tl.transition_matrix(), such as weight_connectivities or softmax_scale.

Return type

Union[AnnData, BaseEstimator, None]


Depending on copy and return_estimator, either updates the existing adata object, returns its copy or returns the estimator.

Marked cells are added to adata.obs['terminal_states'].