Skip to main content
v2026.11,986 entries · CC-BY 4.0

CellRank: Install, Run and Interpret Cell Fates

Follow a CellRank bone marrow workflow from pseudotime to macrostates and fate probabilities, with checks for endpoint selection and reproducibility.

Written and maintained by CASRAI Editorial Board

Published

On this page

CellRank is a Python framework for mapping cell fates from single-cell data. Its kernels turn biological information into cell-to-cell transition probabilities; its estimators use those transitions to identify macrostates, terminal states and fate probabilities. A useful starting point is the documented bone marrow example: follow an existing pseudotime into a fate model, then check which conclusions depend on the graph, direction and selected endpoints.

Ask CASRAI · free to tryQuestion about this guide? Ask CASRAI answers with linked sources. 2 free questions a day, no account.

Ask your first question freeSubscribe

What it is used for in research

CellRank addresses dynamic biological processes such as differentiation, regeneration and reprogramming. The CellRank 2 methods paper describes a framework that can combine different views of a biological process, including experimental time information. A single expression snapshot and a time-course experiment do not supply the same evidence about direction. CellRank separates that evidence from downstream fate analysis through its kernel and estimator interfaces.

The distinction matters when planning an analysis. A kernel specifies how cells can transition to one another. An estimator analyzes the resulting Markov model, rather than independently discovering experimental time. Changing the directional information changes the model being interpreted, even when the same expression matrix and visualization are retained. A convincing plot therefore needs a clear account of the input that supplied direction.

RNA velocity is one possible input, but it is not required for every CellRank workflow. The example below uses a neighbor graph and an existing pseudotime. This makes it useful for researchers who already have a cell ordering and want to investigate possible terminal outcomes. It does not turn pseudotime into a measured clock or replace an experimental test of a proposed differentiation mechanism.

Install or access

The official installation guide specifies Python 3.12 or newer and documents installation from PyPI:

pip install cellrank

Use an environment that meets that requirement before working through the notebook. The Python bioinformatics workflow guide provides broader context for organizing scripts and environments. Keep the environment associated with the analysis, rather than relying on whichever Python installation happens to launch a notebook.

The installation documentation also distinguishes optional dependencies from the basic package. Gene-trend fitting with the Python GAM model has a dedicated extra:

pip install "cellrank[gam]"

PETSc and SLEPc support larger linear-algebra problems. The documentation offers a pip extra, which compiles those libraries, and prebuilt conda packages. For the latter route, it gives:

mamba install -c conda-forge cellrank petsc4py slepc4py

Native Windows is a specific exception: the installation guide says conda-forge does not provide the required PETSc/SLEPc builds there. It recommends the basic pip installation, or WSL when those solvers are needed. Do not treat a Windows conda solver failure as evidence that every CellRank installation route is unavailable.

Step-by-step task

This walkthrough follows the official getting-started notebook’s human bone marrow example. It uses supplied annotations and pseudotime, rather than calculating a new biological ordering. The downloaded AnnData object contains 5,780 cells and 27,876 genes before the demonstrated filtering. Its existing t-SNE embedding supplies the visualization coordinates.

  1. Load the documented dataset. The notebook imports CellRank as cr and Scanpy as sc, then uses CellRank’s dataset loader. The clusters and palantir_pseudotime annotations are part of this example’s inputs.
import cellrank as cr
import scanpy as sc

adata = cr.datasets.bone_marrow()
  1. Prepare expression and build the neighbor graph. These are the notebook’s preprocessing calls and parameter values. They demonstrate one workflow; they are not a universal prescription for filtering every experiment.
sc.pp.filter_genes(adata, min_cells=5)
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, n_top_genes=3000)
sc.tl.pca(adata, random_state=0)
sc.pp.neighbors(adata, random_state=0)
  1. Construct transitions from the supplied pseudotime. PseudotimeKernel uses the neighbor graph and the named observation column. Its transition matrix describes movement between cells under that directional assumption.
from cellrank.kernels import PseudotimeKernel

pk = PseudotimeKernel(adata, time_key="palantir_pseudotime")
pk.compute_transition_matrix()
  1. Inspect the spectrum and compute macrostates. GPCCA provides a coarser representation of the transition process. The notebook examines the spectrum before computing ten macrostates, associating their names with the existing cluster annotation.
from cellrank.estimators import GPCCA

g = GPCCA(pk)
g.compute_schur()
g.plot_spectrum(real_only=True)
g.compute_macrostates(n_states=10, cluster_key="clusters")
g.plot_macrostates(which="all", basis="tsne")
  1. Select terminal states and compute fate probabilities. The tutorial selects six terminal states using the top_n method. This selects macrostates by their self-transition values in the coarse-grained matrix. Ten macrostates and six endpoints belong to this example; neither number is a general default for another tissue.
g.predict_terminal_states(method="top_n", n_states=6)
g.plot_macrostates(which="terminal", basis="tsne")
g.compute_fate_probabilities()
g.plot_fate_probabilities(legend_loc="right", basis="tsne")
  1. Preserve the transition model. The documented kernel-writing interface stores the transition matrix and its parameters in AnnData before saving the object. A saved expression matrix alone does not describe all the choices behind a fate analysis.
pk.write_to_adata()
adata.write("hematopoiesis.h5ad")

For another dataset, replace the example-specific annotations with columns that actually exist and have an appropriate biological interpretation. Keep a record of how pseudotime was generated and rooted. Passing a column with the expected name satisfies a software interface; it does not establish that its ordering represents the process under study.

Output and how to read it

Interpret each output at its own level. GPCCA’s soft macrostate memberships describe how cells associate with the coarse states. The coarse transition matrix, available as coarse_T, describes movement among those states. Terminal-state annotations identify the endpoints selected for the subsequent absorption calculation. These objects answer different questions.

Fate probabilities describe the probability of eventual absorption into the specified terminal states under the fitted transition model. They are not the same as a cell’s macrostate membership or its probability of being classified as a terminal cell. A fate probability is conditional on both the transition matrix and the chosen terminal states; changing either means asking a different model-based question.

Illustrative interpretation, not an experimental result: suppose a transient cell has probabilities 0.7 and 0.3 for two selected endpoints. The model favors the first endpoint, while retaining support for the second. The values do not report that the individual cell was physically tracked twice, nor do they establish that 70% of an experimental population will reach that outcome. Keep the distinction between modeled paths and observed descendants explicit.

The tutorial’s combined fate plot colors cells by their most likely fate and uses color intensity to represent lineage priming. Read the endpoint labels together with the probability output, rather than interpreting a color patch in isolation. The PseudotimeKernel documentation specifically describes simulated random walks as qualitative views of transitions, so a visually persuasive walk is not an independent quantitative validation.

Driver-gene analysis is another distinct output. GPCCA’s compute_lineage_drivers correlates expression with lineage probabilities, with options to restrict the calculation to relevant clusters. These are candidate associations for follow-up. A high correlation does not demonstrate causal regulation. Likewise, the tutorial’s optional GAM expression trends are fitted patterns along a supplied pseudotime, weighted by fate probabilities.

Troubleshooting

Check graph direction before changing the estimator

PseudotimeKernel reads its time_key from adata.obs and relies on the neighbor graph. If the resulting direction is biologically implausible, inspect the ordering and graph before interpreting terminal-state labels. The API’s backward option reverses the ordering mathematically; it does not decide which direction an experiment supports.

The kernel offers hard and soft threshold schemes. Hard thresholding removes some backward-pointing edges while retaining close neighbors to help preserve connectivity. Soft thresholding downweights backward edges. The optional check_irreducibility parameter checks a property of the resulting transition matrix. These controls address graph construction, so they should be documented as modeling choices rather than used silently to obtain a preferred picture.

Separate endpoint selection from model fit

The top_n method deliberately selects the requested number of endpoints. It therefore cannot independently confirm that this number is biologically correct. GPCCA also documents a stability method, whose default threshold is 0.96, and methods based on eigengaps. Inspect the coarse transition matrix, macrostate assignments and the rationale for endpoint selection together.

If a collaborator reports a different fate map, first compare the directional input, macrostate settings and terminal states. This is a practical diagnostic sequence derived from the kernel/estimator separation: agreement on preprocessing alone does not establish that two analyses used the same fate model.

Distinguish numerical checks from biological support

The GPCCA API exposes solver tolerance and a check that fate probabilities sum to one within tolerance. It documents numerical adjustments for poorly conditioned problems and precision-related failures. A converged linear solve supports the numerical calculation; it does not validate pseudotime, the biological endpoints or a causal interpretation. Investigate the reported numerical issue on its own terms before changing biological assumptions.

For installation problems, match the environment to the official platform guidance. PETSc/SLEPc compilation and native Windows conda limitations have different remedies from a missing pseudotime column or an inappropriate endpoint choice. Keeping those categories separate makes troubleshooting more reproducible.

Free alternatives

Scanpy and Palantir provide related analysis routes through open-source software. The table describes the task each official source documents; it does not rank tools or imply that their outputs are interchangeable with every CellRank analysis.

Tool Documented task Distinction for this workflow
Scanpy DPT and PAGA DPT computes diffusion pseudotime; its API recommends PAGA for branch detection. DPT requires a root cell, neighbors and a diffusion map. It supplies an ordering rather than the GPCCA endpoint analysis shown above. Scanpy uses the BSD 3-Clause license.
Palantir Models differentiation as a stochastic process along a phenotypic manifold. Offers a Python route to differentiation and fate modeling. Its documentation describes AnnData integration and identifies an MIT license in its release notes.

For an R workflow that learns a trajectory graph and orders cells from selected roots, see the Monocle 3 trajectory and pseudotime guide. Monocle’s documentation explains that cells in partitions without a reachable root can receive infinite pseudotime. That illustrates why the origin and meaning of an ordering need attention before it becomes an input to another method.

The downloadable data table below compares the inputs, direction assumptions and outputs of these approaches with CellRank. It is a crosswalk between documented analysis objects, not a benchmark of accuracy or speed.

Preserve a reproducible research handoff

A practical handoff should distinguish supplied information from inferred results. Record the dataset, preprocessing, pseudotime method and root choice, kernel settings, macrostate count, endpoint-selection method and solver configuration. Keep those choices alongside the saved analysis object and code. These recommendations follow the dependencies in the documented workflow: a fate matrix without its generating assumptions is difficult to interpret.

The kernel API documents where write_to_adata stores the transition matrix and calculation parameters. Preserve those with the analysis, and identify any additional files needed to reconstruct later steps. The computational reproducibility definition explains the broader aim of obtaining results again from the same data and computational methods. For CellRank, the useful unit of explanation is the entire path from directional evidence to endpoint-specific probabilities.

Sources

Data: Cell fate and pseudotime workflow crosswalk

Original compilation comparing documented input objects, direction assumptions and output objects in CellRank, Scanpy DPT, Palantir and Monocle 3. Compiled from each project’s official tutorial or API reference; this is a method crosswalk, not a performance benchmark.

Cell fate and pseudotime workflow crosswalk
MethodInput used in documented workflowHow direction or origin is suppliedOutput object or analysisSource
CellRank PseudotimeKernel + GPCCAAnnData, neighbor graph, observation pseudotime columnExisting pseudotime; terminal states selected from macrostatesCell-cell transitions, macrostates and terminal-state fate probabilitiesCellRank getting-started tutorial; PseudotimeKernel and GPCCA APIs
Scanpy DPTAnnData with neighbors and diffusion mapRoot cell annotation in uns[iroot]Diffusion pseudotime per cell; API recommends PAGA for branchingScanpy DPT API
PalantirMultidimensional single-cell data; AnnData workflow supportedDifferentiation modeled from stem cells toward terminal cellsDifferentiation trajectories and cell-fate modelingPalantir official documentation
Monocle 3Cell data set from expression, cell metadata and gene annotationsRoot nodes selected on learned trajectory graphTrajectory graph and pseudotime; unreachable cells have infinite pseudotimeMonocle 3 trajectory tutorial

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about CellRank: Install, Run and Interpret Cell Fates

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →