coco_pipe.dim_reduction.evaluation.velocity

Dynamics visualization utilities for velocity-like embedding fields.

This module provides evaluation-adjacent helpers for estimating low-dimensional velocity vectors from ordered high-dimensional samples. The implementation is inspired by scVelo-style transition weighting, but it operates on generic sample-feature matrices rather than a specific single-cell pipeline.

Functions

compute_velocity_fields

Estimate low-dimensional velocity vectors from ordered samples and an aligned embedding.

Author: Hamza Abdelhedi (hamza.abdelhedi@umontreal.ca)

Functions

compute_velocity_fields(→ numpy.ndarray)

Compute velocity-like vectors in embedding space.

Module Contents

coco_pipe.dim_reduction.evaluation.velocity.compute_velocity_fields(X: numpy.ndarray, X_emb: numpy.ndarray, delta_t: int = 1, n_neighbors: int = 30, sigma: float = 0.1, groups: numpy.ndarray | None = None, times: numpy.ndarray | None = None) → numpy.ndarray[source]

Compute velocity-like vectors in embedding space.

The function estimates a forward transition direction in the original feature space, then projects that direction into the embedding by weighting low-dimensional neighbor displacements with cosine-aligned transition probabilities.

Parameters:

  • X (np.ndarray of shape (n_samples, n_features)) – High-dimensional data ordered by sequence position.

  • X_emb (np.ndarray of shape (n_samples, n_components)) – Low-dimensional embedding aligned with X row-wise.

  • delta_t (int, default=1) – Forward lag in samples used to compute the high-dimensional transition vector. This is a sample lag, not a physical time unit. When times is provided, the high-dimensional transition is additionally divided by the elapsed time between the lagged observations.

  • n_neighbors (int, default=30) – Number of non-self neighbors used for local projection.

  • sigma (float, default=0.1) – Kernel width controlling the sharpness of transition probabilities.

  • groups (np.ndarray of shape (n_samples,), optional) – Group labels defining independent ordered sequences. Velocity vectors are computed separately within each group to avoid cross-group transitions and cross-group neighbor mixing.

  • times (np.ndarray of shape (n_samples,), optional) – Optional ordering variable. When provided, samples are sorted within each group before computing forward transitions. The same ordering is also used to derive elapsed time scaling for the high-dimensional transition vector.

Returns:

Velocity vectors in embedding space.

Return type:

np.ndarray of shape (n_samples, n_components)

Raises:

ValueError – If the inputs are misaligned, not two-dimensional, contain invalid parameter values, or define non-increasing times within a sequence.

Notes

Samples without a valid forward lagged observation keep a zero velocity vector in the output. This typically affects the final delta_t samples in each independent sequence.

Examples

>>> import numpy as np
>>> X = np.random.rand(100, 10)
>>> X_emb = np.random.rand(100, 2)
>>> V = compute_velocity_fields(X, X_emb, delta_t=1, n_neighbors=10)
>>> V.shape
(100, 2)