two_sample¶
Two-sample permutation test implementations.
This module provides CPU-parallel and GPU-batched implementations of the two-sample permutation test (group permutation test).
Methods:
| Name | Description |
|---|---|
two_sample_permutation_test | Two-sample permutation test using group label shuffling. |
Classes¶
Methods¶
two_sample_permutation_test¶
two_sample_permutation_test(data1: np.ndarray, data2: np.ndarray, *, n_permute: int = 5000, tail: int | str = 2, return_null: bool = False, device: str | None = 'cpu', n_jobs: int = -1, max_gpu_memory_gb: float | None = None, random_state: int | None = None, progress_bar: bool = False) -> dictTwo-sample permutation test using group label shuffling.
Tests whether two independent groups have different means by randomly permuting group labels. This is the permutation test equivalent of an independent samples t-test.
Assumption: Exchangeability under the null hypothesis (group assignments are arbitrary). Valid for independent samples from similar distributions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data1 | ndarray | Group 1 data - shape (n_samples1,) for single feature - shape (n_samples1, n_features) for multi-feature (voxel-wise) | required |
data2 | ndarray | Group 2 data - shape (n_samples2,) for single feature - shape (n_samples2, n_features) for multi-feature (voxel-wise) | required |
n_permute | int | Number of permutations (default: 5000) | 5000 |
tail | int | str | Test type — 2 | ‘two’ (two-tailed, default) or 1 |
return_null | bool | If True, return full null distribution (default: False) | False |
device | str | Parallelization method (default: ‘cpu’) - None: Single-threaded NumPy (for debugging/small problems) - ‘cpu’: CPU parallelization via joblib (default, 4-8× speedup) - ‘gpu’: GPU acceleration via PyTorch (fastest for large problems) | ‘cpu’ |
n_jobs | int | Number of CPU cores for parallelization (default: -1 = all cores) Only used when device=‘cpu’ | -1 |
max_gpu_memory_gb | float | Explicit GPU memory budget in GB. None (default) measures the device’s available memory. Controls automatic batching to prevent OOM errors. Only used with device=‘gpu’. Larger values allow more permutations per batch but risk OOM on smaller GPUs. | None |
random_state | int | Random seed for reproducibility | None |
Returns:
| Name | Type | Description |
|---|---|---|
dict | dict | Dictionary with keys: - ‘mean_diff’ (float or np.ndarray): Observed mean difference (data1 - data2) - ‘p’ (float or np.ndarray): P-value(s) - ‘null_dist’ (np.ndarray): Null distribution (if return_null=True) - ‘device’ (str): Parallelization method used |
Examples:
>>> # Single feature (default CPU parallelization)
>>> data1 = np.random.randn(20) # Group 1: 20 subjects
>>> data2 = np.random.randn(25) # Group 2: 25 subjects
>>> result = two_sample_permutation_test(data1, data2, n_permute=5000)
>>> result['p']
0.45>>> # Voxel-wise test with GPU
>>> data1 = np.random.randn(20, 10000) # 20 subjects, 10K voxels
>>> data2 = np.random.randn(25, 10000) # 25 subjects, 10K voxels
>>> result = two_sample_permutation_test(data1, data2, n_permute=5000, device='gpu')
>>> result['mean_diff'].shape
(10000,)
>>> result['p'].shape
(10000,)>>> # Single-threaded (for debugging)
>>> result = two_sample_permutation_test(data1, data2, n_permute=5000, device=None)Notes
Default (device=‘cpu’): CPU parallelization with joblib (4-8× speedup)
GPU parallelization (‘gpu’): Fastest for large problems with automatic batching
Single-threaded (device=None): Use for small problems or debugging
For voxel-wise tests, each voxel tested independently
Group sizes can be unequal