conninfpy.acceleration

Permutation acceleration methods for faster inference.

Implements tail approximation via Generalized Pareto Distribution (GPD) and gamma approximation, following Winkler et al. (2016) “Faster permutation inference in brain imaging”, NeuroImage.

These methods reduce the number of permutations needed for accurate p-value estimation from ~5000 to ~200, yielding 10-100x speedup while maintaining exact error rates for FWER-corrected inference.

References

Winkler et al. (2016). Faster permutation inference in brain imaging.

NeuroImage, doi:10.1016/j.neuroimage.2016.05.068

conninfpy.acceleration.fit_gpd_tail(null_dist: ndarray[tuple[Any, ...], dtype[float64]], observed: ndarray[tuple[Any, ...], dtype[float64]], n_thresholds: int = 5, ad_threshold: float = 2.5) → ndarray[tuple[Any, ...], dtype[float64]][source]

Compute p-values using GPD tail approximation.

Fits a GPD to the upper tail of the null distribution and uses the fitted distribution to compute p-values for the observed statistics. Falls back to empirical p-values when GPD fit is poor. This is a tail approximation, not an exact finite-permutation procedure.

Algorithm (Winkler et al., 2016, Section 2.2.3):

  1. Set initial threshold u at upper quartile of null_dist

  2. Fit GPD to exceedances y = T_star_j - u by method of moments

  3. Test fit with Anderson-Darling; if poor, increase u and retry

  4. Compute p = (k / J) * GPD_sf(T - u) where k = #exceedances

Parameters:

  • null_dist (ndarray of shape (J,)) – Max-statistic null distribution from permutations.

  • observed (ndarray of shape (*spatial_dims,)) – Observed statistics (e.g., shape (N, N) for connectivity).

  • n_thresholds (int, default=5) – Maximum number of threshold increases to try for good GPD fit.

  • ad_threshold (float, default=2.5) – Anderson-Darling threshold for acceptable fit.

Returns:

p_values – P-values. Uses GPD where fit is good, empirical otherwise. The empirical fallback uses tie-inclusive max-statistic counting and the Phipson-Smyth +1 correction.

Return type:

ndarray of same shape as observed

conninfpy.acceleration.fit_gamma_tail(null_dist: ndarray[tuple[Any, ...], dtype[float64]], observed: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Compute p-values using gamma (Pearson type III) approximation.

Fits a gamma distribution to the null distribution using method of moments (first three moments) and computes p-values from the fitted distribution. Simpler and more robust than GPD, but still an approximation to the finite-permutation tail.

Parameters:

  • null_dist (ndarray of shape (J,)) – Max-statistic null distribution.

  • observed (ndarray of shape (*spatial_dims,)) – Observed statistics.

Returns:

p_values – P-values from fitted gamma distribution, or tie-inclusive empirical p-values with the Phipson-Smyth +1 correction when gamma fitting is not possible.

Return type:

ndarray of same shape as observed

conninfpy.acceleration.compute_p_values_accelerated(emp_stat_dict: Dict[str, ndarray[tuple[Any, ...], dtype[_ScalarT]]], max_null_dict: Dict[str, ndarray[tuple[Any, ...], dtype[_ScalarT]]], method: str = 'gpd') → Dict[str, ndarray[tuple[Any, ...], dtype[_ScalarT]]][source]

Compute p-values using accelerated tail approximation.

Drop-in replacement for _compute_p_values_from_null that uses GPD or gamma fitting instead of pure empirical counting. Tail estimates are approximate; fallback empirical p-values use the same tie-inclusive max-statistic counting as the standard path.

Parameters:

  • emp_stat_dict (dict) – Dictionary with empirical statistic arrays (any keys).

  • max_null_dict (dict) – Dictionary with null distribution arrays.

  • method ({'gpd', 'gamma'}, default='gpd') – Acceleration method.

Returns:

Dictionary with p-value arrays for each key.

Return type:

dict