CFLARE.compute_absorption_probabilities(keys=None, check_irred=False, solver=None, use_petsc=None, time_to_absorption=None, n_jobs=None, backend='loky', show_progress_bar=True, tol=1e-05, preconditioner=None)

Compute absorption probabilities of a Markov chain.

For each cell, this computes the probability of it reaching any of the approximate recurrent classes defined by terminal_states. This also computes the entropy over absorption probabilities, which is a measure of cell plasticity, see [Setty19].

  • keys (Optional[Sequence[str]]) – Keys defining the recurrent classes.

  • check_irred (bool) – Check whether the transition matrix is irreducible.

  • solver (Optional[str]) –

    Solver to use for the linear problem. Options are ‘direct’, ‘gmres’, ‘lgmres’, ‘bicgstab’ or ‘gcrotmk’ when use_petsc=False or one of petsc4py.PETSc.KPS.Type otherwise.

    Information on the scipy iterative solvers can be found in scipy.sparse.linalg() or for petsc4py solver here.

    If is None, the solver is chosen automatically, depending on the problem size.

  • use_petsc (Optional[bool]) – Whether to use solvers from petsc4py or scipy. Recommended for large problems. If None, it is determined automatically. If no installation is found, defaults to scipy.sparse.linalg.gmres().

  • time_to_absorption (Union[str, Sequence[Union[str, Sequence[str]]], Dict[Union[str, Sequence[str]], str], None]) –

    Whether to compute mean time to absorption and its variance to specific absorbing states.

    If a dict, can be specified as {'Alpha': 'var', ...} to also compute variance. In case when states are a tuple, time to absorption will be computed to the subset of these states, such as [('Alpha', 'Beta'), ...] or {('Alpha', 'Beta'): 'mean', ...}. Can be specified as 'all' to compute it to any absorbing state in keys, which is more efficient than listing all absorbing states.

    It might be beneficial to disable the progress bar as show_progress_bar=False, because many linear systems are being solved.

  • n_jobs (Optional[int]) – Number of parallel jobs to use when using an iterative solver. When use_petsc=True or for quickly-solvable problems, we recommend higher number (>=8) of jobs in order to fully saturate the cores.

  • backend (str) – Which backend to use for multiprocessing. See joblib.Parallel for valid options.

  • show_progress_bar (bool) – Whether to show progress bar when the solver isn’t a direct one.

  • tol (float) – Convergence tolerance for the iterative solver. The default is fine for most cases, only consider decreasing this for severely ill-conditioned matrices.

  • preconditioner (Optional[str]) – Preconditioner to use, only available when use_petsc=True. For available values, see here or the values of petsc4py.PETSc.PC.Type. We recommended ‘ilu’ preconditioner for badly conditioned problems.


Nothing, but updates the following fields:

  • absorption_probabilities - probabilities of being absorbed into the terminal states.

  • diff_potential - differentiation potential of cells.

  • lineage_absorption_times - mean times until absorption to subset absorbing states and optionally their variances saved as '{lineage} mean' and '{lineage} var', respectively, for each subset of absorbing states specified in time_to_absorption.

Return type