coco_pipe.dim_reduction.evaluation.stats
========================================

.. py:module:: coco_pipe.dim_reduction.evaluation.stats

.. autoapi-nested-parse::

   Statistical tests for trajectory scalar metrics.

   Functions
   ---------
   paired_condition_stats
       Paired t-test across all condition pairs, with FDR correction.
   grouped_condition_stats
       Paired t-test across grouped condition sets, with FDR correction.



Functions
---------

.. autoapisummary::

   coco_pipe.dim_reduction.evaluation.stats.paired_condition_stats
   coco_pipe.dim_reduction.evaluation.stats.grouped_condition_stats
   coco_pipe.dim_reduction.evaluation.stats.permutation_null_separation_auc


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

.. py:function:: paired_condition_stats(scalar_df, conditions, metric_col = 'metric', condition_col = 'condition', subject_col = 'subject', value_col = 'value', min_pairs = 3)

   Run a paired t-test for every (metric, condition pair) combination.

   :param scalar_df: Long-format table of scalar trajectory metrics.  Must contain at
                     least ``metric_col``, ``condition_col``, ``subject_col``, and
                     ``value_col``.
   :type scalar_df: pd.DataFrame
   :param conditions: Ordered list of condition labels to include in the comparisons.
   :type conditions: list[str]
   :param metric_col:
   :type metric_col: str, default="metric"
   :param condition_col:
   :type condition_col: str, default="condition"
   :param subject_col:
   :type subject_col: str, default="subject"
   :param value_col:
   :type value_col: str, default="value"
   :param min_pairs: Minimum number of matched subject pairs required to run a t-test.
   :type min_pairs: int, default=3

   :returns: Columns: ``metric``, ``comparison``, ``n``, ``mean_diff``, ``t``,
             ``p_uncorrected``, ``p_fdr``.
             Empty DataFrame if no valid pairs are found.
   :rtype: pd.DataFrame


.. py:function:: grouped_condition_stats(scalar_df, condition_sets, metric_col = 'metric', condition_col = 'condition', subject_col = 'subject', value_col = 'value', min_pairs = 3)

   Run paired t-tests across grouped condition sets with FDR correction.

   Conditions within each group are averaged per subject before testing,
   allowing multi-condition groups (e.g. "Positive = [happy, excited]").

   :param scalar_df: Long-format table of scalar trajectory metrics.
   :type scalar_df: pd.DataFrame
   :param condition_sets: Mapping ``{set_name: {group_label: [condition, ...]}}`` defining how
                          conditions are grouped for each comparison set.
   :type condition_sets: dict[str, dict[str, list[str]]]
   :param metric_col: Column name overrides.
   :type metric_col: str
   :param condition_col: Column name overrides.
   :type condition_col: str
   :param subject_col: Column name overrides.
   :type subject_col: str
   :param value_col: Column name overrides.
   :type value_col: str
   :param min_pairs: Minimum number of matched subject pairs required to run a t-test.
   :type min_pairs: int, default=3

   :returns: Columns: ``set``, ``metric``, ``comparison``, ``n``, ``mean_diff``,
             ``t``, ``p_uncorrected``, ``p_fdr``.
             Empty DataFrame if no valid pairs are found.
   :rtype: pd.DataFrame


.. py:function:: permutation_null_separation_auc(result, group_a, group_b, n_perm = 200, rng = None, method = 'centroid', window = None)

   Label-shuffle null on between-group centroid separation AUC.

   :param result: The TrajectoryResult container holding trajectories and metadata.
   :type result: TrajectoryResult
   :param group_a: The condition labels to compare.
   :type group_a: Sequence[int]
   :param group_b: The condition labels to compare.
   :type group_b: Sequence[int]
   :param n_perm:
   :type n_perm: int, default=200
   :param rng:
   :type rng: np.random.Generator, optional
   :param method:
   :type method: str, default="centroid"
   :param window: Time window (tmin, tmax) to restrict the AUC calculation.
   :type window: tuple of float, optional

   :returns: * **observed_auc** (*float*)
             * **null_aucs** (*np.ndarray*) -- AUC values under ``n_perm`` random label shuffles.