coco_pipe.dim_reduction.evaluation.result

Results Container.

Classes

TrajectoryResult	Unified Container for Trajectory Geometry Results.
EmbeddingQualityResult	Unified Container for Embedding Quality Metrics.
VelocityResult	Unified Container for Velocity Dynamics Results.

Module Contents

class coco_pipe.dim_reduction.evaluation.result.TrajectoryResult(trajectories, times, subjects, conditions)

Unified Container for Trajectory Geometry Results.

Provides tidy data views for easier analysis, visualization, and statistical assessment of trajectory dynamics across subjects and conditions.

Parameters:

• trajectories (numpy.ndarray)

• times (numpy.ndarray)

• subjects (numpy.ndarray)

• conditions (numpy.ndarray)

trajectories

times

subjects

conditions

get_per_trial_scalars()

Compute per-trial scalar metrics in long format.

Returns:

Columns: subject, condition, trial, metric, value.

Return type:

pd.DataFrame

get_per_condition_scalars()

Compute within-condition spread metrics (cohesion, intra_spread).

Returns:

Columns: subject, condition, metric, value.

Return type:

pd.DataFrame

get_separation_pair_scalars(methods=('centroid', 'mahalanobis'))

Per-subject, per-condition-pair separation peak / peak-time / AUC.

For each method in methods, calls trajectory_separation on the trials for one subject and extracts scalar summaries per condition pair.

Returns:

Columns: subject, method, pair (string "A_vs_B"), label_a, label_b, metric, value. Metric values: peak_separation, peak_separation_time, auc_separation.

Return type:

pd.DataFrame

Parameters:

methods (collections.abc.Sequence[str])

get_separation_timecourses(methods=('centroid', 'mahalanobis'))

Pooled-across-subjects separation timecourses per condition pair.

Returns:

{method: {(a, b): timecourse_array}}. Use the result directly with coco_pipe.viz.interactive.plot_trajectory_separation.

Return type:

dict

Parameters:

methods (collections.abc.Sequence[str])

slice_time(tmin, tmax)

Return a new TrajectoryResult restricted to a time window.

Parameters:

• tmin (float)

• tmax (float)

Return type:

TrajectoryResult

filter(subjects=None, conditions=None)

Return a new TrajectoryResult containing only specified subjects/conditions.

Parameters:

• subjects (collections.abc.Sequence | None)

• conditions (collections.abc.Sequence[int] | None)

Return type:

TrajectoryResult

get_kinematic_timecourses(metrics)

Compute and return continuous kinematic timecourses.

Returns:

Columns: subject, condition, trial, time, metric, value.

Return type:

pd.DataFrame

Parameters:

metrics (collections.abc.Sequence[str])

save(path)

Save the TrajectoryResult object to disk.

Parameters:

path (str | pathlib.Path)

classmethod load(path)

Load a TrajectoryResult object from disk.

Parameters:

path (str | pathlib.Path)

Return type:

TrajectoryResult

class coco_pipe.dim_reduction.evaluation.result.EmbeddingQualityResult(X, Z)

Unified Container for Embedding Quality Metrics.

Provides tidy data views for rank-based dimensionality reduction quality criteria (Trustworthiness, Continuity, LCMC, MRRE).

Parameters:

• X (numpy.ndarray)

• Z (numpy.ndarray)

X

Z

property Q: numpy.ndarray

The co-ranking matrix, computed lazily.

Return type:

numpy.ndarray

get_trustworthiness(k_values)

Compute trustworthiness for various neighborhood sizes.

Parameters:

k_values (collections.abc.Sequence[int])

Return type:

pandas.DataFrame

get_continuity(k_values)

Compute continuity for various neighborhood sizes.

Parameters:

k_values (collections.abc.Sequence[int])

Return type:

pandas.DataFrame

get_lcmc(k_values)

Compute LCMC for various neighborhood sizes.

Parameters:

k_values (collections.abc.Sequence[int])

Return type:

pandas.DataFrame

get_mrre(k_values)

Compute MRRE (intrusion and extrusion) for various neighborhood sizes.

Parameters:

k_values (collections.abc.Sequence[int])

Return type:

pandas.DataFrame

summary(k_values)

Compute all quality metrics across all provided k values.

Parameters:

k_values (collections.abc.Sequence[int])

Return type:

pandas.DataFrame

get_shepard_diagram_data(sample_size=1000, random_state=None)

Return (d_orig, d_emb) sampled pairwise distances.

Parameters:

• sample_size (int)

• random_state (int | None)

Return type:

tuple[numpy.ndarray, numpy.ndarray]

save(path)

Save the EmbeddingQualityResult object to disk.

Parameters:

path (str | pathlib.Path)

classmethod load(path)

Load an EmbeddingQualityResult object from disk.

Parameters:

path (str | pathlib.Path)

Return type:

EmbeddingQualityResult

class coco_pipe.dim_reduction.evaluation.result.VelocityResult(X, Z, times=None, groups=None)

Unified Container for Velocity Dynamics Results.

Parameters:

• X (numpy.ndarray)

• Z (numpy.ndarray)

• times (numpy.ndarray | None)

• groups (numpy.ndarray | None)

X

Z

times = None

groups = None

get_velocity_fields(delta_t=1, n_neighbors=30, sigma=0.1)

Compute and return the velocity vectors in the embedding space.

Parameters:

• delta_t (int)

• n_neighbors (int)

• sigma (float)

Return type:

numpy.ndarray

save(path)

Save the VelocityResult object to disk.

Parameters:

path (str | pathlib.Path)

classmethod load(path)

Load a VelocityResult object from disk.

Parameters:

path (str | pathlib.Path)

Return type:

VelocityResult