cellrank.kernels.VelocityKernel¶
 class cellrank.kernels.VelocityKernel(adata, backward=False, attr='layers', xkey='Ms', vkey='velocity', **kwargs)[source]¶
Kernel which computes a transition matrix based on RNA velocity.
See also
See CellRank Meets RNA Velocity on how to compute the
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 ofAnnData
to read from.xkey (
Optional
[str
]) – Key inlayers
orobsm
where expected gene expression counts are stored.vkey (
Optional
[str
]) – Key inlayers
orobsm
where velocities are stored.gene_subset – List of genes to be used to compute transition probabilities. If not specified, genes from
adata.var['{vkey}_genes']
are used. This feature is only available when reading fromanndata.AnnData.layers
and will be ignored otherwise.
Attributes table¶
Annotated data object. 

Direction of the process. 

Underlying connectivity matrix. 

Underlying base kernels. 

Array of shape 

Parameters which are used to compute the transition matrix. 



Rownormalized transition matrix. 
Methods table¶

Compute crossboundary correctness score between source and target cluster. 

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

Return a copy of self. 

Read the kernel saved using 

Plot 

Plot random walks in an embedding. 

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

Deserialize self from a file. 

Serialize self to a file using 

Write the transition matrix and parameters used for computation to the underlying 
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 the unnormalized 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¶
Rownormalized transition matrix.
Methods¶
cbc¶
 VelocityKernel.cbc(source, target, cluster_key, rep, graph_key='distances')¶
Compute crossboundary correctness score between source and target cluster.
 Parameters:
 Return type:
 Returns:
: Crossboundary correctness score for each observation.
compute_transition_matrix¶
 VelocityKernel.compute_transition_matrix(model='deterministic', backward_mode='transpose', similarity='correlation', softmax_scale=None, n_samples=1000, seed=None, **kwargs)[source]¶
Compute transition matrix based on velocity directions on the local manifold.
For each cell, infer transition probabilities based on the cell’s velocityextrapolated 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 whenjax
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. IfNone
, it will be estimated using1 / median(correlations)
. The idea behind this is to scale the softmax to counter everything tending to orthogonality in high dimensions.similarity (
Union
[Literal
['correlation'
,'cosine'
,'dot_product'
],Callable
[[ndarray
,ndarray
,float
],tuple
[ndarray
,ndarray
]]]) –Similarity measure between cells as described in [Li et al., 2021]. Valid options are:
'correlation'
Correlation
.'cosine'
Cosine
.'dot_product'
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 whenmode = 'monte_carlo'
.seed (
Optional
[int
]) – Random seed whenmode = '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
Parallel
for valid options.kwargs (
Any
) – Keyword arguments for the underlyingmodel
.model (Literal['deterministic', 'stochastic', 'monte_carlo'])
 Return type:
 Returns:
: Returns self and updates
transition_matrix
,logits
andparams
.
copy¶
 VelocityKernel.copy(*, deep=False)¶
Return a copy of self.
 Parameters:
deep (
bool
) – Whether to usedeepcopy()
. Return type:
 Returns:
: Copy of self.
from_adata¶
 classmethod VelocityKernel.from_adata(adata, key, copy=False)¶
Read the kernel saved using
write_to_adata()
. Parameters:
adata (
AnnData
) – Annotated data object.key (
str
) – Key inobsp
where the transition matrix is stored. The parameters should be stored inadata.uns['{key}_params']
.copy (
bool
) – Whether to copy the transition matrix.
 Return type:
 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:
key_added (
Optional
[str
]) – If notNone
, save the result toadata.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
) – IfTrue
, usevelocity_embedding_stream()
. Otherwise, usevelocity_embedding_grid()
.connectivities (
Optional
[spmatrix
]) – Connectivity matrix to use for projection. IfNone
, use ones from the underlying kernel, is possible.kwargs (
Any
) – Keyword argument for the abovementioned plotting function.
 Return type:
 Returns:
: Nothing, just plots and modifies
obsm
with a key based on thekey_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 afloat
, it can be specified as a fraction of the number of cells.successive_hits (
int
) – Number of successive hits in thestop_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 inobs
with values corresponding to either 1 or more clusters (if the column is categorical) or atuple
specifying \([min, max]\) interval from which to select the indices.
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 aftermax_iters
. Can be specified as:dict
 dictionary with 1 key inobs
with values corresponding to either 1 or more clusters (if the column is categorical) or atuple
specifying \([min, max]\) interval from which to select the indices.
For example
{'clusters': ['Alpha', 'Beta']}
andsuccessive_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.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. IfNone
or 1, the execution is sequential.backend (
str
) – Which backend to use for parallelization. SeeParallel
for valid options.figsize (
Optional
[tuple
[float
,float
]]) – Size of the figure.save (
Union
[Path
,str
,None
]) – Filename where to save the plot.
 Return type:
 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 ofcmap
.
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.time_key (
str
) – Key inobs
where experimental time is stored.clusters (
Optional
[Sequence
[Any
]]) – Visualize flow only for these clusters. IfNone
, use all clusters.time_points (
Optional
[Sequence
[Union
[float
,int
]]]) – Visualize flow only for these time points. IfNone
, 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 byclusters
.xticks_step_size (
Optional
[int
]) – Show only every other nth tick on the xaxis. IfNone
, don’t show any ticks.legend_loc (
Optional
[str
]) – Position of the legend. IfNone
, do not show the legend.figsize (
Optional
[tuple
[float
,float
]]) – Size of the figure.figsize – Size of the figure.
dpi – Dots per inch.
save (
Union
[Path
,str
,None
]) – Filename where to save the plot.
 Return type:
 Returns:
: The axes object, if
show = False
. Nothing, just plots the figure. Optionally saves it based onsave
.
Notes
This function is a Python reimplementation 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)¶
Deserialize self from a file.
 Parameters:
fname (
Union
[str
,Path
]) – Path from which to read the object.adata (
Optional
[AnnData
]) –AnnData
object to assign to the saved object. Only used when the saved object hasadata
and it was saved without it.copy (
bool
) – Whether to copyadata
before assigning it. Ifadata
is a view, it is always copied.
 Return type:
IOMixin
 Returns:
: The deserialized object.
write¶
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:
 Return type:
 Returns:
: Updates the
adata
with the following fields:obsp['{key}']
 the transition matrix.uns['{key}_params']
 parameters used for the calculation.