`isc`¶

Intersubject Correlation (ISC) with GPU-Accelerated Permutation Testing.

This module provides both leave-one-out (LOO) and pairwise ISC computation with efficient CPU-parallel and GPU-batched implementations. Follows the statistical methods from Chen et al. (2016) for correct bootstrap resampling of correlation matrices.

Methods:

Name	Description
`isc_group_permutation_test`	Compute ISC difference between groups with permutation testing.
`isc_permutation_test`	Compute intersubject correlation with permutation testing.

Methods¶

`isc_group_permutation_test`¶

isc_group_permutation_test(group1: np.ndarray, group2: np.ndarray, *, n_permute: int = 5000, summary: Literal['median', 'mean'] = 'median', method: Literal['permute', 'bootstrap'] = 'permute', summary_statistic: Literal['leave-one-out', 'pairwise'] = 'pairwise', ci_percentile: float = 95, tail: int | str = 2, device: Literal['cpu', 'gpu'] | None = 'cpu', n_jobs: int = -1, random_state: int | None = None, return_null: bool = False, progress_bar: bool = False, exclude_self_corr: bool = True, metric: str = 'correlation') -> dict[str, Any]

Compute ISC difference between groups with permutation testing.

Supports both subject-wise permutation and bootstrap methods with efficient CPU-parallel and optional GPU acceleration. Follows the statistical methods from Chen et al. (2016) for correct group comparison inference.

Parameters:

Name	Type	Description	Default
`group1`	`ndarray`	First group data with one of the following shapes: - (n_observations, n_subjects1): Single feature - (n_observations, n_subjects1, n_voxels): Voxel-wise	required
`group2`	`ndarray`	Second group data with one of the following shapes: - (n_observations, n_subjects2): Single feature - (n_observations, n_subjects2, n_voxels): Voxel-wise	required
`n_permute`	`int`	Number of permutations/bootstrap iterations. Defaults to 5000.	`5000`
`summary`	`Literal [‘median’, ‘mean’]`	Summary statistic for aggregating ISC values: - ‘median’: Direct median (robust to outliers) - ‘mean’: Fisher z-transformed mean (unbiased averaging) Defaults to ‘median’.	`‘median’`
`method`	`Literal [‘permute’, ‘bootstrap’]`	Resampling method for p-value computation: - ‘permute’: Subject-wise permutation (combines groups, permutes labels) - ‘bootstrap’: Subject-wise bootstrap (resamples within each group) Defaults to ‘permute’.	`‘permute’`
`summary_statistic`	`Literal [‘leave-one-out’, ‘pairwise’]`	ISC computation method: - ‘pairwise’: Average all pairwise correlations - ‘leave-one-out’: Correlate each subject with mean of others Defaults to ‘pairwise’.	`‘pairwise’`
`ci_percentile`	`float`	Confidence interval percentile (e.g., 95 for 95% CI). Defaults to 95.	`95`
`tail`	`int \| str`	Two-tailed (2 or ‘two’, default) or one-tailed (1 or ‘one’, positive direction) p-value.	`2`
`device`	`Literal [‘cpu’, ‘gpu’] \| None`	Parallelization method: - ‘cpu’: CPU parallelization via joblib (default, 4-8× speedup) - ‘gpu’: GPU acceleration via PyTorch (10-30× speedup for voxel-wise LOO) - None: Single-threaded NumPy (for debugging/small problems) Defaults to ‘cpu’.	`‘cpu’`
`n_jobs`	`int`	Number of CPU cores for parallelization (-1 = all cores). Only used when device=‘cpu’. Defaults to -1.	`-1`
`random_state`	`int \| None`	Random seed for reproducibility.	`None`
`return_null`	`bool`	If True, return null distribution in result dict. Defaults to False.	`False`
`progress_bar`	`bool`	Show progress bar during bootstrap/permutation. Defaults to False.	`False`
`exclude_self_corr`	`bool`	Mask self-correlations in bootstrap (pairwise only). Defaults to True.	`True`
`metric`	`str`	Similarity metric for pairwise ISC computation. See sklearn.metrics.pairwise_distances for valid options. Only applies when summary_statistic=‘pairwise’. Defaults to ‘correlation’.	`‘correlation’`

Returns:

Type	Description
`dict [ str , Any ]`	Dictionary with the following keys:
`dict [ str , Any ]`	- ‘isc_group_difference’: Observed ISC difference (float or array per voxel)
`dict [ str , Any ]`	- ‘p’: P-value (Phipson-Smyth corrected)
`dict [ str , Any ]`	- ‘ci’: Confidence interval tuple (lower, upper)
`dict [ str , Any ]`	- ‘device’: Parallelization method used
`dict [ str , Any ]`	- ‘null_dist’: (optional) Bootstrap/permutation distribution

Examples:

>>> # Single-feature ISC group comparison
>>> group1 = np.random.randn(100, 10)  # 10 subjects
>>> group2 = np.random.randn(100, 10)
>>> result = isc_group_permutation_test(group1, group2, n_permute=1000)
>>> print(f"ISC difference: {result['isc_group_difference']:.3f}, p: {result['p']:.3f}")

>>> # Voxel-wise ISC group comparison with GPU acceleration
>>> group1_voxels = np.random.randn(100, 10, 5000)  # 5K voxels
>>> group2_voxels = np.random.randn(100, 10, 5000)
>>> result = isc_group_permutation_test(
...     group1_voxels,
...     group2_voxels,
...     summary_statistic='leave-one-out',
...     device='gpu',  # GPU for LOO computation
...     n_permute=5000
... )
>>> print(f"Significant voxels: {(result['p'] < 0.05).sum()}")

`isc_permutation_test`¶

isc_permutation_test(data: np.ndarray, *, n_permute: int = 5000, summary: Literal['median', 'mean'] = 'median', summary_statistic: Literal['leave-one-out', 'pairwise'] = 'pairwise', method: Literal['bootstrap', 'circle_shift', 'phase_randomize'] = 'bootstrap', ci_percentile: float = 95, tail: int | str = 2, return_null: bool = False, progress_bar: bool = False, exclude_self_corr: bool = True, metric: str = 'correlation', device: Literal['cpu', 'gpu'] | None = 'cpu', n_jobs: int = -1, max_gpu_memory_gb: float | None = None, random_state: int | None = None) -> dict[str, Any]

Compute intersubject correlation with permutation testing.

Supports both leave-one-out and pairwise ISC computation modes with GPU acceleration for large voxel-wise problems and CPU-parallel bootstrap resampling.