coco_pipe.dim_reduction.evaluation¶

Submodules¶

Classes¶

MethodSelector

Compare and rank already-scored dimensionality reduction methods.

Functions¶

`moving_average`(→ numpy.ndarray)	Smooth a one-dimensional array with a valid-mode moving average.
`trajectory_acceleration`(→ numpy.ndarray)	Calculate instantaneous acceleration magnitude.
`trajectory_curvature`(→ numpy.ndarray)	Calculate geometric curvature of a trajectory.
`trajectory_dispersion`(→ Dict[str, ...)	Calculate within-group trajectory dispersion across time.
`trajectory_displacement`(→ numpy.ndarray)	Calculate displacement from the initial state across time.
`trajectory_path_length`(→ numpy.ndarray)	Calculate trajectory path length.
`trajectory_separation`(→ Dict[Tuple[str, str], ...)	Calculate time-resolved separation between labeled trajectory groups.
`trajectory_speed`(→ numpy.ndarray)	Calculate instantaneous trajectory speed.
`trajectory_tortuosity`(→ numpy.ndarray)	Calculate trajectory tortuosity.
`trajectory_turning_angle`(→ numpy.ndarray)	Calculate local turning angles between consecutive trajectory segments.
`compute_coranking_matrix`(→ numpy.ndarray)	Compute the co-ranking matrix between two sample spaces.
`compute_mrre`(→ Tuple[float, float])	Compute mean relative rank errors (MRRE).
`continuity`(→ float)	Compute continuity from a co-ranking matrix.
`lcmc`(→ float)	Compute the local continuity meta-criterion (LCMC).
`shepard_diagram_data`(→ Tuple[numpy.ndarray, numpy.ndarray])	Compute sampled pairwise distances for a Shepard diagram.
`trustworthiness`(→ float)	Compute trustworthiness from a co-ranking matrix.
`compute_velocity_fields`(→ numpy.ndarray)	Compute velocity-like vectors in embedding space.

Package Contents¶

class coco_pipe.dim_reduction.evaluation.MethodSelector(reducers: Dict[str, coco_pipe.dim_reduction.core.DimReduction] | List[coco_pipe.dim_reduction.core.DimReduction])[source]¶

Compare and rank already-scored dimensionality reduction methods.

MethodSelector is intentionally post-hoc. It does not fit reducers or compute embeddings. Each reducer must already be a scored DimReduction instance with cached metric_records_.

Parameters:: reducers (dict or list of DimReduction) – Scored DimReduction objects to compare. Lists are converted to a method-keyed mapping using reducer.method.

reducers¶

Compared reductions keyed by method name.

Type:: dict of str to DimReduction

metric_records_¶

Cached long-form metric records populated by collect().

Type:: list of dict

See also

evaluate_embedding: Pure evaluator used upstream by DimReduction.score.
coco_pipe.dim_reduction.core.DimReduction.score: Scores a fitted reduction and populates the records consumed here.

Examples

>>> import numpy as np
>>> from coco_pipe.dim_reduction import DimReduction
>>> X = np.random.RandomState(0).randn(30, 4)
>>> reducers = [
...     DimReduction("PCA", n_components=2),
...     DimReduction("Isomap", n_components=2, n_neighbors=5),
... ]
>>> for reducer in reducers:
...     embedding = reducer.fit_transform(X)
...     reducer.score(embedding, X=X, k_values=[5])
>>> selector = MethodSelector(reducers).collect()
>>> frame = selector.to_frame()
>>> not frame.empty
True

metric_records_ = []¶

classmethod from_records(records: List[Dict[str, Any]]) → MethodSelector[source]¶: Create a selector directly from long-form metric records.

classmethod from_frame(frame: pandas.DataFrame) → MethodSelector[source]¶: Create a selector directly from a metric-record DataFrame.

collect() → MethodSelector[source]¶

Collect cached metric records from already-scored reducers.

Returns:: The selector populated with comparison-ready metric records.
Return type:: MethodSelector
Raises:: ValueError – If a reducer has not been scored yet.

See also

coco_pipe.dim_reduction.core.DimReduction.score: Populates the metric_records_ consumed by this method.
to_frame: Materialize the collected long-form records as a DataFrame.

Notes

collect() does not fit reducers or recompute evaluation metrics. It only gathers cached metric observations from reducers that were already scored explicitly.

Examples

>>> import numpy as np
>>> from coco_pipe.dim_reduction import DimReduction
>>> X = np.random.RandomState(0).randn(20, 4)
>>> reducer = DimReduction("PCA", n_components=2)
>>> embedding = reducer.fit_transform(X)
>>> reducer.score(embedding, X=X, k_values=[5])
>>> selector = MethodSelector([reducer]).collect()
>>> len(selector.metric_records_) > 0
True

to_frame() → pandas.DataFrame[source]¶

Return the cached long-form metric table.

Returns:: Tidy metric table with columns method, metric, value, scope, and scope_value.
Return type:: pandas.DataFrame

Notes

This method only materializes a DataFrame at the public export boundary. Internally, MethodSelector stores metric records as plain Python dictionaries.

See also

collect: Gather cached metric records from scored reducers.
rank_methods: Rank reducers from the collected metric table.

Examples

>>> import numpy as np
>>> from coco_pipe.dim_reduction import DimReduction
>>> X = np.random.RandomState(0).randn(20, 4)
>>> reducer = DimReduction("PCA", n_components=2)
>>> embedding = reducer.fit_transform(X)
>>> reducer.score(embedding, X=X, k_values=[5])
>>> frame = MethodSelector([reducer]).collect().to_frame()
>>> set(["method", "metric", "value"]).issubset(frame.columns)
True

rank_methods(selection_metric: str, *, selection_k: int | None = None, tie_breakers: Sequence[str] | None = None) → pandas.DataFrame[source]¶

Rank methods using one primary metric and optional tie-breakers.

Parameters:

selection_metric (str) – Metric to optimize.
selection_k (int, optional) – Neighborhood size to compare for k-scoped metrics.
tie_breakers (sequence of str, optional) – Additional metrics used in order when primary values tie.

Returns:

Ranked comparison table. The first row is the best-scoring method under the requested ranking policy.

Return type:

pandas.DataFrame

Raises:

ValueError – If the requested metrics are unsupported, unavailable in the cached records, or missing the requested selection_k observations.

Notes

Ranking is based on mean metric values per method. For k-scoped metrics, selection_k restricts comparison to a single neighborhood size when requested.

See also

collect: Gather cached metric observations before ranking.
to_frame: Inspect the underlying long-form metric observations directly.
coco_pipe.dim_reduction.core.DimReduction.score: Produces the metric records that feed into ranking.

Examples

>>> import numpy as np
>>> from coco_pipe.dim_reduction import DimReduction
>>> X = np.random.RandomState(0).randn(20, 4)
>>> reducers = [DimReduction("PCA", n_components=2)]
>>> reducer = reducers[0]
>>> embedding = reducer.fit_transform(X)
>>> reducer.score(embedding, X=X, k_values=[5])
>>> ranked = MethodSelector(reducers).collect().rank_methods(
...     "trustworthiness",
...     selection_k=5,
... )
>>> ranked.iloc[0]["method"] == reducer.method
True

coco_pipe.dim_reduction.evaluation.moving_average(arr: numpy.ndarray, window: int) → numpy.ndarray[source]¶

Smooth a one-dimensional array with a valid-mode moving average.

Parameters:

arr (np.ndarray of shape (n_samples,)) – Input array to smooth.
window (int) – Size of the smoothing window. Must be a positive integer no larger than the array length.

Returns:

Smoothed array. The output length is n_samples - window + 1. If window == 1, a copy of the input is returned.

Return type:

np.ndarray

Raises:

ValueError – If arr is not one-dimensional, if window is not positive, or if window is larger than the input length.

See also

trajectory_speed: First-order trajectory dynamics without smoothing.
trajectory_turning_angle: Local directional changes along a trajectory.

Examples

>>> import numpy as np
>>> moving_average(np.array([1, 2, 3, 4, 5]), window=3)
array([2., 3., 4.])

coco_pipe.dim_reduction.evaluation.trajectory_acceleration(traj: numpy.ndarray, dt: float = 1.0) → numpy.ndarray[source]¶

Calculate instantaneous acceleration magnitude.

Parameters:

traj (np.ndarray of shape (..., n_times, n_dims)) – Trajectory array. The second-to-last axis is interpreted as time and the last axis as coordinates.
dt (float, default=1.0) – Uniform time step between consecutive samples.

Returns:

Acceleration-magnitude timecourse aligned with the input time axis.

Return type:

np.ndarray of shape (…, n_times)

Raises:

ValueError – If traj has fewer than two dimensions, contains fewer than three time points, or if dt <= 0.

See also

trajectory_speed: First-order trajectory dynamics.
trajectory_curvature: Geometric bending of a trajectory.
trajectory_turning_angle: Local directional changes between segments.

Examples

>>> import numpy as np
>>> t = np.linspace(0.0, 2.0, 3)
>>> traj = np.stack([t**2, np.zeros_like(t)], axis=1)
>>> trajectory_acceleration(traj, dt=1.0).shape
(3,)

coco_pipe.dim_reduction.evaluation.trajectory_curvature(traj: numpy.ndarray) → numpy.ndarray[source]¶

Calculate geometric curvature of a trajectory.

Parameters:: traj (np.ndarray of shape (..., n_times, n_dims)) – Trajectory array. The second-to-last axis is interpreted as time and the last axis as coordinates.
Returns:: Curvature timecourse aligned with the input time axis.
Return type:: np.ndarray of shape (…, n_times)
Raises:: ValueError – If traj has fewer than two dimensions or fewer than two time points.

Notes

For vector-valued trajectories, curvature is computed from first and second derivatives using the generalized formula

sqrt(||v||^2 ||a||^2 - (v . a)^2) / ||v||^3.

The implementation assumes uniformly spaced samples.

See also

trajectory_turning_angle: Discrete local directional change.
trajectory_tortuosity: Path inefficiency relative to net displacement.
trajectory_speed: First-order trajectory dynamics.

Examples

>>> import numpy as np
>>> t = np.linspace(0, 2 * np.pi, 100)
>>> traj = np.stack([np.cos(t), np.sin(t)], axis=1)
>>> k = trajectory_curvature(traj)
>>> k.shape
(100,)

coco_pipe.dim_reduction.evaluation.trajectory_dispersion(traj: numpy.ndarray, labels: numpy.ndarray | None = None) → Dict[str, numpy.ndarray] | numpy.ndarray[source]¶

Calculate within-group trajectory dispersion across time.

Parameters:

traj (np.ndarray of shape (n_trials, n_times, n_dims)) – Trial trajectory tensor.
labels (np.ndarray of shape (n_trials,), optional) – Optional group label for each trial. If omitted, a single global dispersion timecourse is returned.

Returns:

Global dispersion timecourse when labels is omitted, otherwise a mapping from label to dispersion timecourse.

Return type:

np.ndarray or dict[str, np.ndarray]

See also

trajectory_separation: Unified separation entrypoint.
trajectory_separation: Use method="within_between_ratio" for normalized separation.

Examples

>>> import numpy as np
>>> traj = np.zeros((2, 3, 2))
>>> traj[1, :, 0] = 1.0
>>> trajectory_dispersion(traj)
array([0.5, 0.5, 0.5])

coco_pipe.dim_reduction.evaluation.trajectory_displacement(traj: numpy.ndarray) → numpy.ndarray[source]¶

Calculate displacement from the initial state across time.

Parameters:: traj (np.ndarray of shape (..., n_times, n_dims)) – Trajectory array. The second-to-last axis is interpreted as time and the last axis as coordinates.
Returns:: Euclidean displacement from the first time point at each time index.
Return type:: np.ndarray of shape (…, n_times)

See also

trajectory_path_length: Total or cumulative traveled distance.
trajectory_tortuosity: Ratio of traveled distance to final displacement.

Examples

>>> import numpy as np
>>> traj = np.array([[0.0, 0.0], [1.0, 0.0], [1.0, 1.0]])
>>> trajectory_displacement(traj)
array([0.        , 1.        , 1.41421356])

coco_pipe.dim_reduction.evaluation.trajectory_path_length(traj: numpy.ndarray, *, cumulative: bool = False) → numpy.ndarray[source]¶

Calculate trajectory path length.

Parameters:

traj (np.ndarray of shape (..., n_times, n_dims)) – Trajectory array. The second-to-last axis is interpreted as time and the last axis as coordinates.
cumulative (bool, default=False) – If True, return cumulative path length aligned with the input time axis. Otherwise return total path length for each trajectory.

Returns:

Total path length with shape (...) when cumulative=False, or cumulative path length with shape (..., n_times) when cumulative=True.

Return type:

np.ndarray

See also

trajectory_displacement: Distance from the initial state across time.
trajectory_tortuosity: Ratio of path length to net displacement.
trajectory_speed: First-order local motion magnitude.

Examples

>>> import numpy as np
>>> traj = np.array([[0.0, 0.0], [1.0, 0.0], [2.0, 0.0]])
>>> trajectory_path_length(traj)
np.float64(2.0)

coco_pipe.dim_reduction.evaluation.trajectory_separation(traj: numpy.ndarray, labels: numpy.ndarray, method: str = 'centroid', **kwargs) → Dict[Tuple[str, str], numpy.ndarray][source]¶

Calculate time-resolved separation between labeled trajectory groups.

Parameters:

traj (np.ndarray of shape (n_trials, n_times, n_dims)) – Trajectory tensor containing one trajectory per trial.
labels (np.ndarray of shape (n_trials,)) – Class label for each trial.
method ({"centroid", "within_between_ratio", "mahalanobis",) – “distributional”, “margin”}, default=”centroid” Separation definition to compute.
**kwargs (dict) – Additional keyword arguments forwarded to the selected separation method.

Returns:

Mapping from label pairs to separation timecourses of shape (n_times,).

Return type:

dict[tuple[str, str], np.ndarray]

Raises:

ValueError – If the inputs are invalid or if an unsupported separation method is requested.

Notes

This is the high-level separation entrypoint for trajectory-group comparison. It dispatches to the more specific separation primitives in this module.

Supported methods:

"centroid": Euclidean distance between label centroids.
"within_between_ratio": Between-centroid distance normalized by within-group dispersion.
"mahalanobis": Covariance-aware centroid separation.
"distributional": Energy-distance separation between trial clouds.
"margin": Nearest-cross minus nearest-within margin separation.

See also

trajectory_dispersion: Within-group spread used by some separation methods.

Examples

>>> import numpy as np
>>> traj = np.zeros((4, 5, 2))
>>> labels = np.array(["A", "A", "B", "B"])
>>> sep = trajectory_separation(traj, labels, method="centroid")
>>> list(sep.keys())
[('A', 'B')]

coco_pipe.dim_reduction.evaluation.trajectory_speed(traj: numpy.ndarray, dt: float = 1.0) → numpy.ndarray[source]¶

Calculate instantaneous trajectory speed.

Parameters:

traj (np.ndarray of shape (..., n_times, n_dims)) – Trajectory array. The second-to-last axis is interpreted as time and the last axis as coordinates.
dt (float, default=1.0) – Uniform time step between consecutive samples.

Returns:

Instantaneous speed timecourse. The final value is padded with the last computed speed so that the output length matches the number of time points.

Return type:

np.ndarray of shape (…, n_times)

Raises:

ValueError – If traj has fewer than two dimensions, contains fewer than two time points, or if dt <= 0.

Notes

This function computes the norm of the first difference along the time axis, divided by dt.

See also

trajectory_acceleration: Second-order trajectory dynamics.
trajectory_path_length: Total or cumulative traveled distance.
trajectory_displacement: Distance from the initial state across time.

Examples

>>> import numpy as np
>>> traj = np.array([[0.0, 0.0], [1.0, 0.0], [2.0, 0.0]])
>>> trajectory_speed(traj)
array([1., 1., 1.])

coco_pipe.dim_reduction.evaluation.trajectory_tortuosity(traj: numpy.ndarray, eps: float = 1e-08) → numpy.ndarray[source]¶

Calculate trajectory tortuosity.

Tortuosity is defined as total path length divided by net displacement from the initial to the final state.

Parameters:

traj (np.ndarray of shape (..., n_times, n_dims)) – Trajectory array. The second-to-last axis is interpreted as time and the last axis as coordinates.
eps (float, default=1e-8) – Small constant used to identify near-zero displacement.

Returns:

Tortuosity for each trajectory. Stationary trajectories return 1.0; trajectories with nonzero path length but near-zero net displacement return np.inf.

Return type:

np.ndarray of shape (…)

See also

trajectory_path_length: Total traveled distance along the path.
trajectory_displacement: Net displacement from start to end.
trajectory_curvature: Local geometric bending.

Examples

>>> import numpy as np
>>> traj = np.array([[0.0, 0.0], [1.0, 0.0], [2.0, 0.0]])
>>> trajectory_tortuosity(traj)
np.float64(1.0)

coco_pipe.dim_reduction.evaluation.trajectory_turning_angle(traj: numpy.ndarray) → numpy.ndarray[source]¶

Calculate local turning angles between consecutive trajectory segments.

Parameters:: traj (np.ndarray of shape (..., n_times, n_dims)) – Trajectory array. The second-to-last axis is interpreted as time and the last axis as coordinates.
Returns:: Turning-angle timecourse in radians. The first and last time points are padded with the nearest interior angle to preserve length.
Return type:: np.ndarray of shape (…, n_times)

See also

trajectory_curvature: Continuous geometric bending.
trajectory_speed: Local motion magnitude.
trajectory_path_length: Total or cumulative traveled distance.

Examples

>>> import numpy as np
>>> traj = np.array([[0.0, 0.0], [1.0, 0.0], [1.0, 1.0]])
>>> trajectory_turning_angle(traj)
array([1.57079633, 1.57079633, 1.57079633])

coco_pipe.dim_reduction.evaluation.compute_coranking_matrix(X: numpy.ndarray, X_emb: numpy.ndarray) → numpy.ndarray[source]¶

Compute the co-ranking matrix between two sample spaces.

The co-ranking matrix Q counts how often each point pair appears with high-dimensional rank k and low-dimensional rank l. Self-neighbors are excluded from the rank construction.

Parameters:

X (np.ndarray of shape (n_samples, n_features)) – Original high-dimensional data.
X_emb (np.ndarray of shape (n_samples, n_components)) – Low-dimensional embedding of the same samples.

Returns:

Integer co-ranking matrix where Q[k, l] corresponds to ranks k + 1 and l + 1 in the original and embedded spaces.

Return type:

np.ndarray of shape (n_samples - 1, n_samples - 1)

Raises:

ValueError – If the inputs are not two-dimensional, do not share the same sample count, or contain fewer than two samples.

See also

trustworthiness: Compute intrusion-based neighborhood preservation.
continuity: Compute extrusion-based neighborhood preservation.
lcmc: Compute the local continuity meta-criterion.

Examples

>>> import numpy as np
>>> X = np.array([[0.0], [1.0], [2.0]])
>>> X_emb = np.array([[0.0], [2.0], [4.0]])
>>> Q = compute_coranking_matrix(X, X_emb)
>>> Q.shape
(2, 2)

coco_pipe.dim_reduction.evaluation.compute_mrre(Q: numpy.ndarray, k: int) → Tuple[float, float][source]¶

Compute mean relative rank errors (MRRE).

Both intrusion and extrusion MRRE are returned. These are error metrics, so lower values are better and 0 indicates perfect rank preservation.

Parameters:

Q (np.ndarray of shape (n_samples - 1, n_samples - 1)) – Co-ranking matrix.
k (int) – Neighborhood size.

Returns:

(mrre_intrusion, mrre_extrusion).

Return type:

tuple[float, float]

Raises:

ValueError – If Q is invalid or if k falls outside the valid domain.

See also

trustworthiness: Intrusion-sensitive preservation score.
continuity: Extrusion-sensitive preservation score.

Examples

>>> import numpy as np
>>> Q = np.diag([1, 1, 1, 1])
>>> compute_mrre(Q, k=1)
(0.0, 0.0)

coco_pipe.dim_reduction.evaluation.continuity(Q: numpy.ndarray, k: int) → float[source]¶

Compute continuity from a co-ranking matrix.

Continuity penalizes extrusions, i.e. points that are among the k nearest neighbors in the original space but are pushed farther away in the embedding.

Parameters:

Q (np.ndarray of shape (n_samples - 1, n_samples - 1)) – Co-ranking matrix.
k (int) – Neighborhood size. The normalization used by continuity requires 2 * n_samples - 3 * k - 1 > 0.

Returns:

Continuity score in [0, 1]. Higher is better.

Return type:

float

Raises:

ValueError – If Q is invalid or if k falls outside the valid domain.

See also

trustworthiness: Complementary intrusion-based metric.
compute_coranking_matrix: Construct the required co-ranking matrix.

Examples

>>> import numpy as np
>>> Q = np.diag([1, 1, 1, 1])
>>> continuity(Q, k=1)
1.0

coco_pipe.dim_reduction.evaluation.lcmc(Q: numpy.ndarray, k: int) → float[source]¶

Compute the local continuity meta-criterion (LCMC).

Parameters:

Q (np.ndarray of shape (n_samples - 1, n_samples - 1)) – Co-ranking matrix.
k (int) – Neighborhood size.

Returns:

LCMC score. Higher is better.

Return type:

float

Raises:

ValueError – If Q is invalid or if k falls outside the valid domain.

See also

trustworthiness: Neighbor-preservation metric.
continuity: Neighbor-consistency metric.

Examples

>>> import numpy as np
>>> Q = np.diag([1, 1, 1, 1])
>>> isinstance(lcmc(Q, k=1), float)
True

coco_pipe.dim_reduction.evaluation.shepard_diagram_data(X: numpy.ndarray, X_embedded: numpy.ndarray, sample_size: int = 1000, random_state: int | None = None) → Tuple[numpy.ndarray, numpy.ndarray][source]¶

Compute sampled pairwise distances for a Shepard diagram.

Parameters:

X (np.ndarray of shape (n_samples, n_features)) – Original high-dimensional data.
X_embedded (np.ndarray of shape (n_samples, n_components)) – Low-dimensional embedding of the same samples.
sample_size (int, default=1000) – Number of samples to keep before computing pairwise distances. If sample_size is at least n_samples, all samples are used.
random_state (int, optional) – Random seed used when subsampling.

Returns:

Pairwise distances in the original and embedded spaces.

Return type:

tuple[np.ndarray, np.ndarray]

Raises:

ValueError – If the inputs are invalid or if sample_size <= 1.

See also

compute_coranking_matrix: Rank-based global quality summary.

Examples

>>> import numpy as np
>>> X = np.random.RandomState(0).rand(10, 3)
>>> X_emb = X[:, :2]
>>> d_orig, d_emb = shepard_diagram_data(X, X_emb, sample_size=5, random_state=0)
>>> len(d_orig) == len(d_emb)
True

coco_pipe.dim_reduction.evaluation.trustworthiness(Q: numpy.ndarray, k: int) → float[source]¶

Compute trustworthiness from a co-ranking matrix.

Trustworthiness penalizes intrusions, i.e. points that appear among the k nearest neighbors in the embedding but were farther away in the original space.

Parameters:

Q (np.ndarray of shape (n_samples - 1, n_samples - 1)) – Co-ranking matrix.
k (int) – Neighborhood size. The normalization used by trustworthiness requires 2 * n_samples - 3 * k - 1 > 0.

Returns:

Trustworthiness score in [0, 1]. Higher is better.

Return type:

float

Raises:

ValueError – If Q is invalid or if k falls outside the valid domain.

See also

continuity: Complementary extrusion-based metric.
compute_coranking_matrix: Construct the required co-ranking matrix.

Examples

>>> import numpy as np
>>> Q = np.diag([1, 1, 1, 1])
>>> trustworthiness(Q, k=1)
1.0

coco_pipe.dim_reduction.evaluation.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)