coco_pipe.dim_reduction.evaluation.result
=========================================

.. py:module:: coco_pipe.dim_reduction.evaluation.result

.. autoapi-nested-parse::

   Results Container.



Classes
-------

.. autoapisummary::

   coco_pipe.dim_reduction.evaluation.result.TrajectoryResult
   coco_pipe.dim_reduction.evaluation.result.EmbeddingQualityResult
   coco_pipe.dim_reduction.evaluation.result.VelocityResult


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

.. py:class:: 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.


   .. py:attribute:: trajectories


   .. py:attribute:: times


   .. py:attribute:: subjects


   .. py:attribute:: conditions


   .. py:method:: get_per_trial_scalars()

      Compute per-trial scalar metrics in long format.

      :returns: Columns: ``subject``, ``condition``, ``trial``, ``metric``, ``value``.
      :rtype: pd.DataFrame



   .. py:method:: get_per_condition_scalars()

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

      :returns: Columns: ``subject``, ``condition``, ``metric``, ``value``.
      :rtype: pd.DataFrame



   .. py:method:: 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``.
      :rtype: pd.DataFrame



   .. py:method:: 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``.
      :rtype: dict



   .. py:method:: slice_time(tmin, tmax)

      Return a new TrajectoryResult restricted to a time window.



   .. py:method:: filter(subjects = None, conditions = None)

      Return a new TrajectoryResult containing only specified
      subjects/conditions.



   .. py:method:: get_kinematic_timecourses(metrics)

      Compute and return continuous kinematic timecourses.

      :returns: Columns: subject, condition, trial, time, metric, value.
      :rtype: pd.DataFrame



   .. py:method:: save(path)

      Save the TrajectoryResult object to disk.



   .. py:method:: load(path)
      :classmethod:


      Load a TrajectoryResult object from disk.



.. py:class:: EmbeddingQualityResult(X, Z)

   Unified Container for Embedding Quality Metrics.

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


   .. py:attribute:: X


   .. py:attribute:: Z


   .. py:property:: Q
      :type: numpy.ndarray


      The co-ranking matrix, computed lazily.


   .. py:method:: get_trustworthiness(k_values)

      Compute trustworthiness for various neighborhood sizes.



   .. py:method:: get_continuity(k_values)

      Compute continuity for various neighborhood sizes.



   .. py:method:: get_lcmc(k_values)

      Compute LCMC for various neighborhood sizes.



   .. py:method:: get_mrre(k_values)

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



   .. py:method:: summary(k_values)

      Compute all quality metrics across all provided k values.



   .. py:method:: get_shepard_diagram_data(sample_size = 1000, random_state = None)

      Return (d_orig, d_emb) sampled pairwise distances.



   .. py:method:: save(path)

      Save the EmbeddingQualityResult object to disk.



   .. py:method:: load(path)
      :classmethod:


      Load an EmbeddingQualityResult object from disk.



.. py:class:: VelocityResult(X, Z, times = None, groups = None)

   Unified Container for Velocity Dynamics Results.


   .. py:attribute:: X


   .. py:attribute:: Z


   .. py:attribute:: times
      :value: None



   .. py:attribute:: groups
      :value: None



   .. py:method:: get_velocity_fields(delta_t = 1, n_neighbors = 30, sigma = 0.1)

      Compute and return the velocity vectors in the embedding space.



   .. py:method:: save(path)

      Save the VelocityResult object to disk.



   .. py:method:: load(path)
      :classmethod:


      Load a VelocityResult object from disk.