cellrank.kernels.VelocityKernel

class cellrank.kernels.VelocityKernel(adata, backward=False, attr='layers', xkey='Ms', vkey='velocity', **kwargs)

Kernel which computes a transition matrix based on RNA velocity.

This borrows ideas from both [La Manno et al., 2018] and [Bergen et al., 2020]. In short, for each cell i, we compute transition probabilities \(T_{i, j}\) to each cell \(j\) in the neighborhood of \(i\). We quantify how much the velocity vector \(v_i\) of cell \(i\) points towards each of its nearst neighbors. For this comparison, we support various schemes including cosine similarity and pearson correlation.

Parameters:

• adata (AnnData) – Annotated data object.

• backward (bool) – Direction of the process.

• attr (Optional[Literal['layers', 'obsm']]) – Attribute of AnnData to read from.

• xkey (Optional[str]) – Key in anndata.AnnData.layers or anndata.AnnData.obsm where expected gene expression counts are stored.

• vkey (Optional[str]) – Key in anndata.AnnData.layers or anndata.AnnData.obsm where velocities are stored.

• gene_subset – List of genes to be used to compute transition probabilities. If not specified, genes from anndata.AnnData.var ['{vkey}_genes'] are used. This feature is only available when reading from anndata.AnnData.layers and will be ignored otherwise.

• kwargs (Any) – Keyword arguments for the parent class.

Attributes table

adata	Annotated data object.
backward	Direction of the process.
connectivities	Underlying connectivity matrix.
kernels	Underlying base kernels.
logits	Array of shape (n_cells, n_cells) containing not row-normalized transition matrix.
params	Parameters which are used to compute the transition matrix.
shape	(n_cells, n_cells).
transition_matrix	Row-normalized transition matrix.

Methods table

compute_transition_matrix([model, ...])	Compute transition matrix based on velocity directions on the local manifold.
copy(*[, deep])	Return a copy of self.
from_adata(adata, key[, copy])	Read kernel object saved using write_to_adata().
plot_projection([basis, key_added, ...])	Plot transition_matrix as a stream or a grid plot.
plot_random_walks([n_sims, max_iter, seed, ...])	Plot random walks in an embedding.
plot_single_flow(cluster, cluster_key, time_key)	Visualize outgoing flow from a cluster of cells [Mittnenzweig et al., 2021].
read(fname[, adata, copy])	De-serialize self from a file.
write(fname[, write_adata, ext])	Serialize self to a file.
write_to_adata([key, copy])	Write the transition matrix and parameters used for computation to the underlying adata object.

Attributes

adata

VelocityKernel.adata

Annotated data object.

backward

VelocityKernel.backward

Direction of the process.

connectivities

VelocityKernel.connectivities

Underlying connectivity matrix.

kernels

VelocityKernel.kernels

Underlying base kernels.

logits

VelocityKernel.logits

Array of shape (n_cells, n_cells) containing not row-normalized transition matrix.

params

VelocityKernel.params

Parameters which are used to compute the transition matrix.

shape

VelocityKernel.shape

(n_cells, n_cells).

transition_matrix

VelocityKernel.transition_matrix

Row-normalized transition matrix.

Methods

compute_transition_matrix

VelocityKernel.compute_transition_matrix(model=VelocityModel.DETERMINISTIC, backward_mode=BackwardMode.TRANSPOSE, similarity=Similarity.CORRELATION, softmax_scale=None, n_samples=1000, seed=None, **kwargs)

Compute transition matrix based on velocity directions on the local manifold.

For each cell, infer transition probabilities based on the cell’s velocity-extrapolated cell state and the cell states of its K nearest neighbors.

Parameters:

• mode –

  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.

• backward_mode (Literal['transpose', 'negate']) –

  Only matters if initialized as backward = True. Valid options are:

  • ’transpose’ - compute transitions from neighboring cells \(j\) to cell \(i\).

  • ’negate’ - negate the velocity vector.

• softmax_scale (Optional[float]) – Scaling parameter for the softmax. If None, it will be estimated using 1 / median(correlations). The idea behind this is to scale the softmax to counter everything tending to orthogonality in high dimensions.

• scheme –

  Similarity measure between cells as described in [Li et al., 2021]. Can be one of the following:

  • ’correlation’ - cellrank.kernels.utils.Correlation.

  • ’cosine’ - cellrank.kernels.utils.Cosine.

  • ’dot_product’ - cellrank.kernels.utils.DotProduct.

  Alternatively, any function can be passed as long as it follows the signature of cellrank.kernels.utils.SimilarityABC.__call__().

• n_samples (int) – Number of samples when mode = 'monte_carlo'.

• seed (Optional[int]) – Random seed when mode = 'monte_carlo'.

• show_progress_bar – Whether to show a progress bar. Disabling it may slightly improve performance.

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

• backend – Which backend to use for parallelization. See joblib.Parallel for valid options.

• kwargs (Any) – Keyword arguments for the underlying model.

Return type:

VelocityKernel

Returns:

: Self and updates transition_matrix, logits and params.

copy

VelocityKernel.copy(*, deep=False)

Return a copy of self.

Return type:

Kernel

from_adata

classmethod VelocityKernel.from_adata(adata, key, copy=False)

Read kernel object saved using write_to_adata().

Parameters:

• adata (AnnData) – Annotated data object.

• key (str) – Key in anndata.AnnData.obsp where the transition matrix is stored. The parameters should be stored in anndata.AnnData.uns ['{key}_params'].

• copy (bool) – Whether to copy the transition matrix.

Return type:

Kernel

Returns:

: The kernel with explicitly initialized properties:

• transition_matrix - the transition matrix.

• params - parameters used for computation.

plot_projection

VelocityKernel.plot_projection(basis='umap', key_added=None, recompute=False, stream=True, connectivities=None, **kwargs)

Plot transition_matrix as a stream or a grid plot.

Parameters:

• basis (str) – Key in anndata.AnnData.obsm containing the basis.

• key_added (Optional[str]) – If not None, save the result to anndata.AnnData.obsm ['{key_added}']. Otherwise, save the result to ‘T_fwd_{basis}’ or T_bwd_{basis}, depending on the direction.

• recompute (bool) – Whether to recompute the projection if it already exists.

• stream (bool) – If True, use scvelo.pl.velocity_embedding_stream(). Otherwise, use scvelo.pl.velocity_embedding_grid().

• connectivities (Optional[spmatrix]) – Connectivity matrix to use for projection. If None, use ones from the underlying kernel, is possible.

• kwargs (Any) – Keyword argument for the chosen plotting function.

Return type:

None

Returns:

: Nothing, just plots and modifies anndata.AnnData.obsm with a key based on key_added.

plot_random_walks

VelocityKernel.plot_random_walks(n_sims=100, max_iter=0.25, seed=None, successive_hits=0, start_ixs=None, stop_ixs=None, basis='umap', cmap='gnuplot', linewidth=1.0, linealpha=0.3, ixs_legend_loc=None, n_jobs=None, backend='loky', show_progress_bar=True, figsize=None, dpi=None, save=None, **kwargs)

Plot random walks in an embedding.

This method simulates random walks on the Markov chain defined though the corresponding transition matrix. The method is intended to give qualitative rather than quantitative insights into the transition matrix. Random walks are simulated by iteratively choosing the next cell based on the current cell’s transition probabilities.

Parameters:

• n_sims (int) – Number of random walks to simulate.

• max_iter (Union[int, float]) – Maximum number of steps of a random walk. If a float, it can be specified as a fraction of the number of cells.

• seed (Optional[int]) – Random seed.

• successive_hits (int) – Number of successive hits in the stop_ixs required to stop prematurely.

• start_ixs (Union[Sequence[str], Mapping[str, Union[str, Sequence[str], Tuple[float, float]]], None]) –

  Cells from which to sample the starting points. If None, use all cells. Can be specified as:

  • dict - dictionary with 1 key in anndata.AnnData.obs with values corresponding to either 1 or more clusters (if the column is categorical) or a tuple specifying [min, max] interval from which to select the indices.

  • typing.Sequence - sequence of cell ids in anndata.AnnData.obs_names.

  For example {'dpt_pseudotime': [0, 0.1]} means that starting points for random walks will be sampled uniformly from cells whose pseudotime is in [0, 0.1].

• stop_ixs (Union[Sequence[str], Mapping[str, Union[str, Sequence[str], Tuple[float, float]]], None]) –

  Cells which when hit, the random walk is terminated. If None, terminate after max_iters. Can be specified as:

  • dict - dictionary with 1 key in anndata.AnnData.obs with values corresponding to either 1 or more clusters (if the column is categorical) or a tuple specifying [min, max] interval from which to select the indices.

  • typing.Sequence - sequence of cell ids in anndata.AnnData.obs_names.

  For example {'clusters': ['Alpha', 'Beta']} and successive_hits = 3 means that the random walk will stop prematurely after cells in the above specified clusters have been visited successively 3 times in a row.

• basis (str) – Basis in anndata.AnnData.obsm to use as an embedding.

• cmap (Union[str, LinearSegmentedColormap]) – Colormap for the random walk lines.

• linewidth (float) – Width of the random walk lines.

• linealpha (float) – Alpha value of the random walk lines.

• ixs_legend_loc (Optional[str]) – Legend location for the start/top indices.

• show_progress_bar (bool) – Whether to show a progress bar. Disabling it may slightly improve performance.

• n_jobs (Optional[int]) – Number of parallel jobs. If -1, use all available cores. If None or 1, the execution is sequential.

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

• figsize (Optional[Tuple[float, float]]) – Size of the figure.

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

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

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

Return type:

None

Returns:

: Nothing, just plots the figure. Optionally saves it based on save. For each random walk, the first/last cell is marked by the start/end colors of cmap.

plot_single_flow

VelocityKernel.plot_single_flow(cluster, cluster_key, time_key, clusters=None, time_points=None, min_flow=0, remove_empty_clusters=True, ascending=False, legend_loc='upper right out', alpha=0.8, xticks_step_size=1, figsize=None, dpi=None, save=None, show=True)

Visualize outgoing flow from a cluster of cells [Mittnenzweig et al., 2021].

Parameters:

• cluster (str) – Cluster for which to visualize outgoing flow.

• cluster_key (str) – Key in anndata.AnnData.obs where clustering is stored.

• time_key (str) – Key in anndata.AnnData.obs where experimental time is stored.

• clusters (Optional[Sequence[Any]]) – Visualize flow only for these clusters. If None, use all clusters.

• time_points (Optional[Sequence[Union[int, float]]]) – Visualize flow only for these time points. If None, use all time points.

• min_flow (float) – Only show flow edges with flow greater than this value. Flow values are always in [0, 1].

• remove_empty_clusters (bool) – Whether to remove clusters with no incoming flow edges.

• ascending (Optional[bool]) – Whether to sort the cluster by ascending or descending incoming flow. If None, use the order as in defined by clusters.

• alpha (Optional[float]) – Alpha value for cell proportions.

• xticks_step_size (Optional[int]) – Show only every other n-th tick on the x-axis. If None, don’t show any ticks.

• legend_loc (Optional[str]) – Position of the legend. If None, do not show the legend.

• figsize (Optional[Tuple[float, float]]) – Size of the figure.

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

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

• show (bool) – If False, return matplotlib.pyplot.Axes.

Return type:

Optional[Axes]

Returns:

: The axes object, if show = False. Nothing, just plots the figure. Optionally saves it based on save.

Notes

This function is a Python re-implementation of the following original R function with some minor stylistic differences. This function will not recreate the results from [Mittnenzweig et al., 2021], because there, the Metacell model [Baran et al., 2019] was used to compute the flow, whereas here the transition matrix is used.

read

static VelocityKernel.read(fname, adata=None, copy=False)

De-serialize self from a file.

Parameters:

• fname (Union[str, Path]) – Filename from which to read the object.

• adata (Optional[AnnData]) – anndata.AnnData object to assign to the saved object. Only used when the saved object has adata and it was saved without it.

• copy (bool) – Whether to copy adata before assigning it or not. If adata is a view, it is always copied.

Return type:

IOMixin

Returns:

: The de-serialized object.

write

VelocityKernel.write(fname, write_adata=True, ext='pickle')

Serialize self to a file.

Parameters:

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

• write_adata (bool) – Whether to save adata object or not, if present.

• ext (Optional[str]) – Filename extension to use. If None, don’t append any extension.

Return type:

None

Returns:

: Nothing, just writes itself to a file using pickle.

write_to_adata

VelocityKernel.write_to_adata(key=None, copy=False)

Write the transition matrix and parameters used for computation to the underlying adata object.

Parameters:

key (Optional[str]) – Key used when writing transition matrix to adata. If None, the key will be determined automatically.

Return type:

None

Returns:

: Updates the adata with the following fields:

• .obsp['{key}'] - the transition matrix.

• .uns['{key}_params'] - parameters used for the calculation.