Metrics (velot.metrics)

Metrics for evaluating velocity field quality.

Adapted from UniTVelo (Gao et al. 2022) and the original VelOT pipeline.

Usage:

import velot

# Cross-boundary direction correctness
edges = [("Root", "Branch_A"), ("Root", "Branch_B")]
scores = velot.metrics.cross_boundary_correctness(
    adata, edges, cluster_key="clusters",
)

# Inner-cluster coherence
scores = velot.metrics.inner_cluster_coherence(adata, cluster_key="clusters")
velot.metrics.cross_boundary_correctness(adata, cluster_edges, cluster_key='clusters', velocity_key='velocity_umap', embedding_key='X_umap', majority_vote=True, return_raw=False)[source]

Cross-Boundary Direction Correctness Score (CBDir).

For each directed edge A→B, measures whether cells of type A have velocity vectors pointing toward their neighbors of type B.

Adapted from UniTVelo (Gao et al. 2022).

Parameters:

  • adata (AnnData) – Annotated data matrix with velocity computed.

  • cluster_edges (Sequence[Tuple[str, str]]) – List of (source, target) cluster name pairs defining expected transitions. E.g., [("Root", "Branch_A")].

  • cluster_key (str) – Column in adata.obs with cluster labels.

  • velocity_key (str) – Key in adata.obsm with velocity vectors.

  • embedding_key (str) – Key in adata.obsm with cell coordinates (same space as velocity).

  • majority_vote (bool) – If True, score is fraction of neighbors with positive cosine. If False, score is mean cosine similarity.

  • return_raw (bool) – If True, return per-cell scores for each edge (for box plots). If False, return mean score per edge and global mean.

Return type:

dict

Returns:

  • If return_raw=True – dict mapping (source, target) to list of per-cell scores.

  • If return_raw=False – tuple of (dict mapping edges to mean scores, global mean score).

Example

edges = [("Root", "Branch_A"), ("Root", "Branch_B")]
scores, mean_score = velot.metrics.cross_boundary_correctness(
    adata, edges, cluster_key="clusters",
)
velot.metrics.inner_cluster_coherence(adata, cluster_key='clusters', velocity_key='velocity_umap', return_raw=False)[source]

Inner-Cluster Coherence Score (ICCoh).

For each cluster, measures how consistent the velocity vectors are among cells of the same type by computing mean pairwise cosine similarity within each cell’s same-type neighbors.

Adapted from UniTVelo (Gao et al. 2022).

Parameters:

  • adata (AnnData) – Annotated data matrix with velocity computed.

  • cluster_key (str) – Column in adata.obs with cluster labels.

  • velocity_key (str) – Key in adata.obsm with velocity vectors.

  • return_raw (bool) – If True, return per-cell scores per cluster. If False, return mean score per cluster and global mean.

Return type:

dict

Returns:

  • If return_raw=True – dict mapping cluster name to list of per-cell scores.

  • If return_raw=False – tuple of (dict of mean scores, global mean score).

Example

scores, mean = velot.metrics.inner_cluster_coherence(
    adata, cluster_key="clusters",
)
velot.metrics.summary(adata, cluster_edges=None, cluster_key='clusters', embedding_key='X_umap', velocity_key='velot_velocity_umap', print_results=True)[source]

Compute and print a summary of velocity metrics.

Returns both aggregated means and raw per-cell scores so that the output can be passed directly to velot.pl.metric_summary() for box plots.

Parameters:

  • adata (AnnData) – Annotated data matrix with velocity computed.

  • cluster_edges (Optional[Sequence[Tuple[str, str]]]) – Transition edges for CBDir. If None, CBDir is skipped.

  • cluster_key (str) – Cluster column.

  • velocity_key (str) – Velocity key.

  • embedding_key (str)

  • print_results (bool)

Returns:

  • "iccoh": dict of cluster → list of per-cell scores

  • "iccoh_mean": global mean ICCoh

  • "cbdir": dict of (src, tgt) → list of per-cell scores

  • "cbdir_mean": global mean CBDir

Return type:

Dictionary with

Example

results = velot.metrics.summary(adata, cluster_edges=edges)
velot.pl.metric_summary(results)