coco_pipe.dim_reduction.evaluation.velocity
===========================================

.. py:module:: coco_pipe.dim_reduction.evaluation.velocity

.. autoapi-nested-parse::

   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
---------

.. autoapisummary::

   coco_pipe.dim_reduction.evaluation.velocity.compute_velocity_fields


Module Contents
---------------

.. py:function:: compute_velocity_fields(X: numpy.ndarray, X_emb: numpy.ndarray, delta_t: int = 1, n_neighbors: int = 30, sigma: float = 0.1, groups: Optional[numpy.ndarray] = None, times: Optional[numpy.ndarray] = None) -> numpy.ndarray

   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.

   :param X: High-dimensional data ordered by sequence position.
   :type X: np.ndarray of shape (n_samples, n_features)
   :param X_emb: Low-dimensional embedding aligned with ``X`` row-wise.
   :type X_emb: np.ndarray of shape (n_samples, n_components)
   :param delta_t: 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.
   :type delta_t: int, default=1
   :param n_neighbors: Number of non-self neighbors used for local projection.
   :type n_neighbors: int, default=30
   :param sigma: Kernel width controlling the sharpness of transition probabilities.
   :type sigma: float, default=0.1
   :param groups: Group labels defining independent ordered sequences. Velocity vectors
                  are computed separately within each group to avoid cross-group
                  transitions and cross-group neighbor mixing.
   :type groups: np.ndarray of shape (n_samples,), optional
   :param times: 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.
   :type times: np.ndarray of shape (n_samples,), optional

   :returns: Velocity vectors in embedding space.
   :rtype: 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.

   .. rubric:: 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.

   .. rubric:: 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)