coco_pipe.dim_reduction.evaluation.stats#

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#

paired_condition_stats(scalar_df, conditions[, ...])

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

grouped_condition_stats(scalar_df, condition_sets[, ...])

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

permutation_null_separation_auc(result, group_a, group_b)

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

Module Contents#

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

Parameters:

  • scalar_df (pd.DataFrame) – Long-format table of scalar trajectory metrics. Must contain at least metric_col, condition_col, subject_col, and value_col.

  • conditions (list[str]) – Ordered list of condition labels to include in the comparisons.

  • metric_col (str, default="metric")

  • condition_col (str, default="condition")

  • subject_col (str, default="subject")

  • value_col (str, default="value")

  • min_pairs (int, default=3) – Minimum number of matched subject pairs required to run a t-test.

Returns:

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

Return type:

pd.DataFrame

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

Parameters:

  • scalar_df (pd.DataFrame) – Long-format table of scalar trajectory metrics.

  • condition_sets (dict[str, dict[str, list[str]]]) – Mapping {set_name: {group_label: [condition, ...]}} defining how conditions are grouped for each comparison set.

  • metric_col (str) – Column name overrides.

  • condition_col (str) – Column name overrides.

  • subject_col (str) – Column name overrides.

  • value_col (str) – Column name overrides.

  • min_pairs (int, default=3) – Minimum number of matched subject pairs required to run a t-test.

Returns:

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

Return type:

pd.DataFrame

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

Parameters:

  • result (TrajectoryResult) – The TrajectoryResult container holding trajectories and metadata.

  • group_a (Sequence[int]) – The condition labels to compare.

  • group_b (Sequence[int]) – The condition labels to compare.

  • n_perm (int, default=200)

  • rng (np.random.Generator, optional)

  • method (str, default="centroid")

  • window (tuple of float, optional) – Time window (tmin, tmax) to restrict the AUC calculation.

Returns:

  • observed_auc (float)

  • null_aucs (np.ndarray) – AUC values under n_perm random label shuffles.

Return type:

tuple[float, numpy.ndarray]