time_perm_cluster¶
- time_perm_cluster(sig1: ~typing.Any, sig2: ~typing.Any, p_thresh: float, p_cluster: float = None, n_perm: int = 1000, tails: int = 1, axis: int = 0, stat_func: callable = <function ttest>, ignore_adjacency: tuple[int] | int = None, permutation_type='independent', vectorized: bool = True, n_jobs: int = -1, seed: int = None, verbose: int = 40) -> (numpy.ndarray[bool], numpy.ndarray[float])[source][source]¶
Calculate significant clusters using permutation testing and cluster correction.
Takes two time series signals, finding clusters of activation defined as significant contiguous time points with a p value less than the p_thresh (greater if tails is -1, and both if tails is 2). The p value is the proportion of times that the difference in the statistic value for signal 1 with respect to signal 2 is greater than the statistic for a random sampling of signal 1 and 2 with respect to a random sampling of signal 1 and 2. The clusters are then corrected by only keeping clusters that are in the (1 - p_cluster)’th percentile of cluster lengths for signal 2.
- Parameters:
sig1 (
array,shape (trials,...,time)) – Active signal. The first dimension is assumed to be the trialssig2 (
array,shape (trials,...,time)) – Passive signal. The first dimension is assumed to be the trialsp_thresh (
float) – The p-value threshold to use for determining significant time points.p_cluster (
float, optional) – The p-value threshold to use for determining significant clusters.n_perm (
int, optional) – The number of permutations to perform.tails (
int, optional) – The number of tails to use. 1 for one-tailed, 2 for two-tailed.axis (
int, optional) – The axis to perform the permutation test across. Also known as the observations axisstat_func (
callable, optional) – The statistical function to use to compare populations. Requires an axis keyword input to denote observations (trials, for example). Default function ismean_diff, but may be substituted with other test functions found here: https://scipy.github.io/devdocs/reference/stats.html#independent -sample-testsignore_adjacency (
intortupleofints, optional) – The axis or axes to ignore when finding clusters. For example, if sig1.shape = (trials, channels, time), and you want to find clusters across time, but not channels, you would set ignore_adjacency = 1.permutation_type (
{‘independent’, ‘samples’, ‘pairings’}, optional) – The type of permutations to be performed, in accordance with the null hypothesis. The first two permutation types are for paired sample statistics, in which all samples contain the same number of observations and observations with corresponding indices along axis are considered to be paired; the third is for independent sample statistics. See: https://docs.scipy.org/doc/scipy/reference/generated/s cipy.stats.permutation_test.html#permutation-testvectorized (
bool, optional) – Whether to use the vectorized version of the permutation test. Default is True.n_jobs (
int, optional) – The number of jobs to run in parallel. -1 for all processors. Default is -1.seed (
int, optional) – The random seed to use for the permutation test. Default is None.verbose (int)
- Returns:
clusters (
array,shape (...,time)) – The binary array of significant clusters.p_obs (
array,shape (...,time)) – The p-value of the observed difference.
- Return type:
References
Examples
>>> import numpy as np >>> seed = 43; rng = np.random.default_rng(seed) >>> sig1 = np.array([[0,1,1,2,2,2.5,3,3,3,2.5,2,2,1,1,0] ... for _ in range(50)]) - rng.random((50, 15)) * 2.6 >>> sig2 = np.array([[0] * 15 for _ in range(100)]) + rng.random( ... (100, 15)) >>> time_perm_cluster(sig1, sig2, 0.05, n_perm=100000, seed=seed)[0] array([False, False, False, False, True, True, True, True, True, True, True, False, False, False, False]) >>> time_perm_cluster(sig1, sig2, 0.01, n_perm=100000, seed=seed)[0] array([False, False, False, False, False, True, True, True, True, True, False, False, False, False, False])
