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)

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)

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')

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.mixed_effects_compare(values, fixed_effects, random_effect, *, formula=None, response_label='value', alpha=0.05)

Fit a linear mixed-effects model with one random intercept.

Wraps statsmodels.regression.mixed_linear_model.MixedLM. Typical use: compare a per-observation metric across treatments while accounting for repeated measurements within a recording, unit, or subject.

Parameters:

• values (array-like) – 1-D response variable, one entry per observation.

• fixed_effects (dict[str, array-like]) – Mapping of fixed-effect names to per-observation arrays. All arrays must have the same length as values. Categorical effects can be passed as string/object arrays — statsmodels will dummy-code them via the Patsy formula.

• random_effect (array-like) – Categorical group labels (one per observation) used as the random intercept group.

• formula (str or None) – Patsy formula for the fixed-effects part. When None (default), an additive formula "<response_label> ~ k1 + k2 + ..." is built from the keys of fixed_effects. Provide an explicit formula for interactions (e.g. "value ~ treatment * latency").

• response_label (str) – Name used for the response column in the constructed DataFrame and in the auto-built formula (default "value").

• alpha (float) – Significance threshold applied to coefficient p-values when building the significant flags. Default 0.05.

Returns:

Dictionary with keys:

• params (dict[str, float]): Estimated coefficients keyed by Patsy term name.

• pvalues (dict[str, float]): Two-sided p-values per term.

• conf_int (dict[str, tuple[float, float]]): Confidence intervals per term (using alpha).

• significant (dict[str, bool]): True where the term’s p-value is below alpha.

• random_effect_variance (float): Estimated variance of the random intercept.

• n_obs (int): Number of observations used.

• n_groups (int): Number of random-effect levels.

• converged (bool): Whether the optimizer converged.

• summary (str): Full statsmodels summary text.

• model: The fitted MixedLMResults object.

Return type:

result (dict)

Notes

• Requires both pandas and statsmodels (optional dependencies). Raises ImportError with installation instructions when either is missing.

• NaN observations (in values, any fixed effect, or the random effect column) are dropped before fitting.

• Tries the lbfgs, powell, and bfgs optimizers in turn; near- singular designs commonly break lbfgs’ gradient path.

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

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).