PERF: Speed up permutation cluster tests via Numba union-find + compact graph

[sharifhsn]

Reference issue

Related: #5439, #7784, #8095, #12609

What does this implement/fix?

Speeds up spatio_temporal_cluster_1samp_test (and the other permutation_cluster_* functions) by replacing hot-path Python/SciPy calls with tighter NumPy and a Numba JIT kernel.

1. Compact-graph reindexing (_get_components): Before calling connected_components, build a subgraph containing only the supra-threshold vertices. This shrinks the CCL input from ~20K to ~200–1000 vertices — the single biggest win.

2. Numba union-find (_st_fused_ccl): For spatio-temporal neighbor-list adjacency, replaces the Python BFS in _get_clusters_st with a single compiled union-find pass over spatial + temporal edges. Avoids constructing a scipy.sparse matrix every permutation.

3. Skip cluster-list construction during permutations (_sums_only): The permutation loop only needs max cluster sums, not the cluster index arrays. A new _sums_only flag lets _find_clusters return sums directly via np.bincount on component labels, skipping argsort/split/concatenate.

4. Precomputed sum-of-squares for sign-flip t-tests: For the default ttest_1samp_no_p, the sign-flip identity s²=1 means sum(X²) is constant across permutations. Each permutation computes t with a single matrix-vector multiply (signs @ X) plus a few elementwise ops, replacing np.dot + np.var + multiple temporaries.

5. Smaller overhead reductions:

   • Vectorized cluster sums via np.add.reduceat (replaces per-cluster loop)
   • _pval_from_histogram via np.searchsorted instead of O(n·k) loop
   • Pre-computed CSR adjacency arrays (avoids redundant list→CSR rebuilds)
   • buffer_size verification skipped for built-in stat functions
   • Vectorized sign-order generation via bit-shifting

All optimizations are gated behind has_numba checks and fall back to the original code paths when Numba is not installed. No public API changes.

Benchmarks

Measured on AWS EC2 (AMD EPYC 9R14, 16 vCPU). Setup: spatio_temporal_cluster_1samp_test with 15 subjects, fsaverage ico-5 source space (20,484 vertices × 15 timepoints = 307,260 tests), tail=1, threshold=1.67.

End-to-end (before → after):

Permutations	Before	After	Speedup
256	3.09 s	0.55 s	5.6×
1024	7.49 s	1.72 s	4.4×
2048	13.8 s	3.29 s	4.2×

Per-permutation cost drops from ~6.3 ms to ~1.5 ms (single-threaded). Fixed overhead drops from ~880 ms to ~140 ms.

Bitwise parity verified (t_obs, H0, p-values, cluster counts) across all three tail modes.

Additional information

• The Numba JIT warmup happens once on the first call. Subsequent calls pay no warmup cost.
• TFCE (threshold=dict(...)) correctly falls back to the original code path — the Numba fast paths are bypassed when the threshold is a dict.
• Custom stat functions (anything other than ttest_1samp_no_p) also fall back to the original code path, still benefiting from the CCL and overhead optimizations but not the fused t-test.

[drammock]

this is a pretty large diff. Before we invest time in a review, a few questions:

1. is this ready for review? if not, please mark as draft until it is ready
2. have you run relevant tests and doc build locally? are they all passing?
3. please disclose the way(s) in which you used AI to assist in this contribution (if any)

tip: next time, if you name the changelog newfeature.rst instead of XXXXX.newfeature.rst then one of our CIs will automatically rename it to include the PR number for you.

[sharifhsn]

My bad, I meant to publish it as draft. Yes it's still in progress.

Tests are all passing.

AI was used to generate the code which was checked over manually to catch bugs.

I'm going to try to reduce the amount of code as much as possible while still maintaining the main speedups.