Statistical Utilities

Statistical helper functions for spike train analysis, including firing rate statistics, distribution fitting, and hypothesis testing utilities.

Statistical utilities for SpikeLab.

Provides reusable statistical functions (regression, confidence intervals, pairwise group comparisons, paired tests, omnibus tests) that can be used independently of plotting.

spikelab.spikedata.stat_utils.linear_regression(x, y, ci_level=0.95)[source]

Compute ordinary least-squares linear regression with optional confidence interval.

Parameters:

  • x (np.ndarray) – 1-D array of predictor values.

  • y (np.ndarray) – 1-D array of response values (same length as x).

  • ci_level (float) – Confidence level for the interval (default 0.95).

Returns:

Dictionary with keys:

  • slope (float): Fitted slope.

  • intercept (float): Fitted intercept.

  • r_squared (float): Coefficient of determination.

  • x_fit (np.ndarray): Sorted x values for plotting the fit line.

  • y_fit (np.ndarray): Predicted y values along x_fit.

  • ci_lower (np.ndarray): Lower confidence bound along x_fit.

  • ci_upper (np.ndarray): Upper confidence bound along x_fit.

Return type:

result (dict)

Notes

  • Uses pure numpy (no scipy/sklearn dependency).

  • NaN pairs are dropped automatically.

spikelab.spikedata.stat_utils.pairwise_tests(groups, test='welch_t', correction='bonferroni', alpha=0.05, labels=None)[source]

Run pairwise statistical tests across groups with multiple-comparison correction.

Parameters:

  • groups (dict[str, np.ndarray] or list[np.ndarray]) – Per-group data arrays. Dict keys are used as labels; for list input supply labels separately.

  • test (str) – Statistical test to use. "welch_t" (default) for Welch’s unequal-variance t-test, "student_t" for Student’s equal-variance t-test, "mann_whitney" for the Mann-Whitney U test. All require scipy.

  • correction (str or None) – Multiple-comparison correction. "bonferroni" (default) or None for uncorrected p-values.

  • alpha (float) – Significance threshold applied after correction. Default 0.05.

  • labels (list[str] or None) – Group labels. Required for list input; ignored for dict input (keys are used).

Returns:

Dictionary with keys:

  • pval_matrix (np.ndarray): (K, K) corrected p-values. Diagonal entries are NaN.

  • sig_matrix (np.ndarray): (K, K) boolean — True where corrected p < alpha.

  • n_comparisons (int): Number of pairwise comparisons.

  • labels (list[str]): Ordered group labels.

Return type:

result (dict)

Notes

  • Requires scipy (optional dependency). Raises ImportError with installation instructions if not available.

spikelab.spikedata.stat_utils.paired_test(a, b, test='wilcoxon', alternative='two-sided')[source]

Run a paired statistical test on two matched samples.

Parameters:

  • a (array-like) – First sample (1-D).

  • b (array-like) – Second sample (1-D, same length as a).

  • test (str) – "wilcoxon" (default) for the Wilcoxon signed-rank test, or "paired_t" for a paired Student’s t-test.

  • alternative (str) – "two-sided" (default), "less", or "greater". Passed directly to the underlying scipy test.

Returns:

Dictionary with keys:

  • statistic (float): Test statistic (W for Wilcoxon, t for paired t).

  • p_value (float): p-value for the test.

  • n (int): Number of valid (non-NaN, non-zero-difference) pairs used.

Return type:

result (dict)

Notes

  • NaN pairs (where either a or b is NaN) are dropped automatically.

  • Requires scipy (optional dependency).

spikelab.spikedata.stat_utils.omnibus_test(groups, test='anova', posthoc='tukey', labels=None)[source]

Run an omnibus test across groups with optional post-hoc comparisons.

Parameters:

  • groups (dict[str, array-like] or list[array-like]) – Per-group data. Dict keys are used as labels; for list input supply labels separately.

  • test (str) – "anova" (default) for one-way ANOVA (scipy.stats.f_oneway), or "kruskal" for the Kruskal-Wallis H test.

  • posthoc (str or None) – Post-hoc test to run when the omnibus test is significant. "tukey" (default) for Tukey HSD, "none"/None to skip post-hoc comparisons.

  • labels (list[str] or None) – Group labels for list input. Ignored for dict input (keys are used).

Returns:

Dictionary with keys:

  • statistic (float): F-statistic (ANOVA) or H-statistic (Kruskal-Wallis).

  • p_value (float): Omnibus p-value.

  • n_groups (int): Number of groups.

  • group_ns (list[int]): Sample sizes per group.

  • labels (list[str]): Ordered group labels.

  • posthoc (list[dict] or None): Post-hoc comparison results when posthoc is not None. Each dict contains: "group_a", "group_b", "p_value", "significant" (at alpha=0.05).

Return type:

result (dict)

Notes

  • NaN values are stripped from each group before testing.

  • Requires scipy (optional dependency).