repository·main·Indexed 19 days ago
https://github.com/scverse/cellrankA modular framework for studying cellular dynamics through Markov state modeling of multi-view single-cell data. CellRank is used for fate mapping and trajectory inference, enabling the estimation of differentiation direction, computation of macrostates, and inference of fate probabilities and driver genes. It features a decoupled two-step workflow consisting of kernels (cellrank.kernels) to estimate transition matrices and estimators (cellrank.estimators), such as GPCCA, to analyze dynamics.
pyGPCCA.The cellrank.pl module provides plotting functions to visualize results computed by CellRank kernels, estimators, or models. These functions are designed to interpret fate mapping, gene expression trends, and probability distributions across single-cell datasets.
import cellrank.pl as plSignals identify the observation-aligned quantity that a model is fit on. They are used to specify what data the model should track (e.g., a specific gene, a covariate in .obs, or a matrix in .obsm).
You can pass Signals to cellrank.pl.gene_trends or cellrank.models.BaseModel.prepare to plot or prepare data for modeling.
Supported Signal types:
Signal: The base class for signals.Gene: Represents a specific gene's expression.Obs: Represents a covariate found in AnnData.obs (e.g., a gene module score).Obsm: Represents a column from an AnnData.obsm array.CellRank's API is organized into several functional modules that work together to perform fate mapping:
cellrank.kernels): These are the foundation of the analysis. They compute cell-cell transition matrices based on various data modalities, such as RNA velocity, pseudotime, developmental potential, or experimental time points.cellrank.estimators): These modules consume the transition matrices produced by kernels to derive biological insights. They are used to compute terminal states, initial states, fate probabilities, and driver genes. The recommended estimator for most workflows is cellrank.estimators.GPCCA.cellrank.models): Used for fitting gene trends over time.cellrank.pl): Provides visualization tools for the results of the analysis.cellrank.datasets): Provides sample data to help you get started.CellRank follows a decoupled two-step modeling framework that allows you to separate the estimation of cellular transitions from the analysis of those transitions:
Step 1: Estimating transitions with cellrank.kernels
You use kernels to take multi-view single-cell input data and estimate a sparse transition matrix $T$. In this matrix, row $i$ contains the transition probabilities from cell $i$ towards its putative descendants. All entries are between 0 and 1, and rows sum to one.
Step 2: Analyzing dynamics with cellrank.estimators
You take the transition matrix $T$ produced by a kernel and apply Markov chain theory to derive biological insights. This includes identifying initial, terminal, and intermediate macrostates, and computing fate probabilities.
Because these steps are decoupled, you can change how you derive transition probabilities (e.g., switching from RNA velocity to pseudotime) without changing how you infer terminal states or fate probabilities.
CellRank can be used for several downstream tasks in single-cell analysis, including:
When modifying the codebase, pay special attention to these high-risk components where regressions are most likely to occur:
src/cellrank/kernels/_base_kernel.py): Watch for weight normalization issues in KernelAdd and direction flipping in bidirectional kernels.write_to_adata, from_adata, or estimator shadow AnnData can break saved analyses and downstream notebooks if the round-trip behavior changes.RealTimeKernel (src/cellrank/kernels/_real_time_kernel.py): This is a complex path involving assembling per-timepoint couplings (via from_moscot or from_wot) into a global block transition matrix.src/cellrank/estimators/mixins/): Mixins for Schur, eigen, fate-probability, and lineage-driver are highly sensitive to correctness.Lineage (src/cellrank/_utils/_lineage.py): This ndarray subclass has specific public slicing and coloring semantics.jax, moscot, petsc4py, slepc4py, rpy2, wot, scvelo, or adjusttext must use existing guards to prevent leaking into top-level imports.src/cellrank/__init__.py or within kernels, estimators, models, pl, or datasets.Estimators in CellRank are used to perform quantitative analysis on Markov transition matrices (kernels). They enable tasks such as:
While several estimators exist, the recommended estimator for most use cases is GPCCA.
Plotting tests in tests/test_plotting.py use three strategies:
tests/_ground_truth_figures/. Use sparingly.Figure/Axes properties (e.g., title, colormap). Preferred for parameter checks.Figure. Use for non-critical paths.Important: Baselines must be produced by the Linux CI environment (hatch-test.py3.12-stable). Do not commit figures rendered on macOS or other OSs. To update a baseline:
rendered-figures artifact from the Linux hatch-test.py3.12-stable job.tests/_ground_truth_figures/ and commit them.CellRank describes cellular dynamics using Markov chains, where each cell represents a state in the chain. This approach assumes:
Transitions are summarized in a transition matrix $T$, where $T_{ij}$ is the probability of transitioning from state $i$ to state $j$ in one step.
In CellRank, a Kernel is a class that takes multi-view single-cell data as input and outputs a cell-cell transition matrix. These matrices represent the probabilities of transitioning from one cell to another based on various data modalities.
Kernels are used to compute transition probabilities based on:
Kernels also provide methods for qualitative visualization, such as vector field or random walk plots. For quantitative analysis of the resulting transition matrices, you should use the estimators instead.
To accommodate various data modalities, CellRank 2 has moved away from the high-level cellrank.tl functions in favor of a modular estimator-based workflow.
Every estimator in cellrank.estimators now implements a consistent two-step interface:
.fit(): Computes macrostates (such as initial and terminal states)..predict(): Classifies macrostates as terminal states.This workflow is designed to be easier to use than the previous low-level interaction modes while remaining more flexible than the deprecated cellrank.tl functions.