brainiak package¶

Brain Imaging Analysis Kit.

Subpackages¶

Submodules¶

brainiak.image module¶

Generic image functionality.

class brainiak.image.ConditionSpec¶

Bases: numpy.ndarray

One-hot representation of conditions across epochs and TRs.

The shape is (n_conditions, n_epochs, n_trs).

class brainiak.image.MaskedMultiSubjectData¶

Bases: numpy.ndarray

Array with shape n_TRs, n_voxels, n_subjects.

classmethod from_masked_images(masked_images: Iterable[numpy.ndarray], n_subjects: int) → T¶

Create a new instance of MaskedMultiSubjecData from masked images.

Parameters

masked_images (iterator) – Images from multiple subjects to stack along 3rd dimension
n_subjects (int) – Number of subjects; must match the number of images

Returns

A new instance of MaskedMultiSubjectData

Return type

T

Raises

ValueError – Images have different shapes. The number of images differs from n_subjects.

class brainiak.image.SingleConditionSpec¶

Bases: brainiak.image.ConditionSpec

ConditionSpec with a single condition applicable to an epoch.

extract_labels() → numpy.ndarray¶

Extract condition labels.

Returns: The condition label of each epoch.
Return type: np.ndarray

brainiak.image.mask_image(image: nibabel.spatialimages.SpatialImage, mask: numpy.ndarray, data_type: type = None) → numpy.ndarray¶

Mask image after optionally casting its type.

Parameters

image – Image to mask. Can include time as the last dimension.
mask – Mask to apply. Must have the same shape as the image data.
data_type – Type to cast image to.

Returns

Masked image.

Return type

np.ndarray

Raises

ValueError – Image data and masks have different shapes.

brainiak.image.mask_images(images: Iterable[nibabel.spatialimages.SpatialImage], mask: numpy.ndarray, image_type: type = None) → Iterable[numpy.ndarray]¶

Mask images.

Parameters

images – Images to mask.
mask – Mask to apply.
image_type – Type to cast images to.

Yields

np.ndarray – Masked image.

brainiak.image.multimask_images(images: Iterable[nibabel.spatialimages.SpatialImage], masks: Sequence[numpy.ndarray], image_type: type = None) → Iterable[Sequence[numpy.ndarray]]¶

Mask images with multiple masks.

Parameters

images – Images to mask.
masks – Masks to apply.
image_type – Type to cast images to.

Yields

Sequence[np.ndarray] – For each mask, a masked image.

brainiak.io module¶

I/O functionality.

brainiak.io.load_boolean_mask(path: Union[str, pathlib.Path], predicate: Callable[numpy.ndarray, numpy.ndarray] = None) → numpy.ndarray¶

Load boolean nibabel.SpatialImage mask.

Parameters

path – Mask path.
predicate – Callable used to create boolean values, e.g. a threshold function lambda x: x > 50.

Returns

Boolean array corresponding to mask.

Return type

np.ndarray

brainiak.io.load_images(image_paths: Iterable[Union[str, pathlib.Path]]) → Iterable[nibabel.spatialimages.SpatialImage]¶

Load images from paths.

For efficiency, returns an iterator, not a sequence, so the results cannot be accessed by indexing.

For every new iteration through the images, load_images must be called again.

Parameters: image_paths – Paths to images.
Yields: SpatialImage – Image.

brainiak.io.load_images_from_dir(in_dir: Union[str, pathlib.Path], suffix: str = 'nii.gz') → Iterable[nibabel.spatialimages.SpatialImage]¶

Load images from directory.

For efficiency, returns an iterator, not a sequence, so the results cannot be accessed by indexing.

For every new iteration through the images, load_images_from_dir must be called again.

Parameters

in_dir – Path to directory.
suffix – Only load images with names that end like this.

Yields

SpatialImage – Image.

Examples

>>> images = list(io.load_images_from_dir("face_scene", "bet.nii.gz"))

brainiak.io.load_labels(path: Union[str, pathlib.Path]) → List[brainiak.image.SingleConditionSpec]¶

Load labels files.

Parameters: path – Path of labels file.
Returns: List of SingleConditionSpec stored in labels file.
Return type: List[SingleConditionSpec]

brainiak.io.save_as_nifti_file(data: numpy.ndarray, affine: numpy.ndarray, path: Union[str, pathlib.Path]) → None¶

Create a Nifti file and save it.

Parameters

data – Brain data.
affine – Affine of the image, usually inherited from an existing image.
path – Output filename.

brainiak.isc module¶

Intersubject correlation (ISC) analysis

Functions for computing intersubject correlation (ISC) and related analyses (e.g., intersubject funtional correlations; ISFC), as well as statistical tests designed specifically for ISC analyses.

The implementation is based on the work in [Hasson2004], [Kauppi2014], [Simony2016], [Chen2016], and [Nastase2019].

Chen2016(1,2,3): “Untangling the relatedness among correlations, part I: nonparametric approaches to inter-subject correlation analysis at the group level.”, G. Chen, Y. W. Shin, P. A. Taylor, D. R. Glen, R. C. Reynolds, R. B. Israel, R. W. Cox, 2016, NeuroImage, 142, 248-259. https://doi.org/10.1016/j.neuroimage.2016.05.023
Hasson2004(1,2): “Intersubject synchronization of cortical activity during natural vision.”, U. Hasson, Y. Nir, I. Levy, G. Fuhrmann, R. Malach, 2004, Science, 303, 1634-1640. https://doi.org/10.1126/science.1089506
Kauppi2014(1,2): “A versatile software package for inter-subject correlation based analyses of fMRI.”, J. P. Kauppi, J. Pajula, J. Tohka, 2014, Frontiers in Neuroinformatics, 8, 2. https://doi.org/10.3389/fninf.2014.00002
Simony2016(1,2,3): “Dynamic reconfiguration of the default mode network during narrative comprehension.”, E. Simony, C. J. Honey, J. Chen, O. Lositsky, Y. Yeshurun, A. Wiesel, U. Hasson, 2016, Nature Communications, 7, 12141. https://doi.org/10.1038/ncomms12141
Nastase2019: “Measuring shared responses across subjects using intersubject correlation.” S. A. Nastase, V. Gazzola, U. Hasson, C. Keysers, 2019, Social Cognitive and Affective Neuroscience, 14, 667-685. https://doi.org/10.1093/scan/nsz037

brainiak.isc.bootstrap_isc(iscs, pairwise=False, summary_statistic='median', n_bootstraps=1000, ci_percentile=95, side='right', random_state=None)¶

One-sample group-level bootstrap hypothesis test for ISCs

For ISCs from one more voxels or ROIs, resample subjects with replacement to construct a bootstrap distribution. Input is a list or ndarray of ISCs for a single voxel/ROI, or an ISCs-by-voxels ndarray. ISC values should be either N ISC values for N subjects in the leave-one-out appraoch (pairwise=False), N(N-1)/2 ISC values for N subjects in the pairwise approach (pairwise=True). In the pairwise approach, ISC values should correspond to the vectorized upper triangle of a square correlation matrix (see scipy.stats.distance.squareform). Shifts bootstrap distribution by actual summary statistic (effectively to zero) for null hypothesis test (Hall & Wilson, 1991). Uses subject-wise (not pair-wise) resampling in the pairwise approach. Returns the observed ISC, the confidence interval, and a p-value for the bootstrap hypothesis test, as well as the bootstrap distribution of summary statistics. The p-value corresponds to either a ‘two-sided’, ‘left’-, or ‘right’-sided (default) test, as specified by side. According to Chen et al., 2016, this is the preferred nonparametric approach for controlling false positive rates (FPRs) for one-sample tests in the pairwise approach. Note that the bootstrap hypothesis test may not strictly control FPRs in the leave-one-out approach.

The implementation is based on the work in [Chen2016] and [HallWilson1991].

HallWilson1991: “Two guidelines for bootstrap hypothesis testing.”, P. Hall, S. R., Wilson, 1991, Biometrics, 757-762. https://doi.org/10.2307/2532163

Parameters

iscs (list or ndarray, ISCs by voxels array) – ISC values for one or more voxels
pairwise (bool, default: False) – Indicator of pairwise or leave-one-out, should match ISCs structure
summary_statistic (str, default: 'median') – Summary statistic, either ‘median’ (default) or ‘mean’
n_bootstraps (int, default: 1000) – Number of bootstrap samples (subject-level with replacement)
ci_percentile (int, default: 95) – Percentile for computing confidence intervals
side (str) – Perform one-sided (‘left’ or ‘right’) or ‘two-sided’ test
= int or None (random_state) – Initial random seed
default (None) – Initial random seed

Returns

observed (float, median (or mean) ISC value) – Summary statistic for actual ISCs
ci (tuple, bootstrap confidence intervals) – Confidence intervals generated from bootstrap distribution
p (float, p-value) – p-value based on bootstrap hypothesis test
distribution (ndarray, n_bootstraps by voxels) – Bootstrap distribution

brainiak.isc.compute_summary_statistic(iscs, summary_statistic='mean', axis=None)¶

Computes summary statistics for ISCs

Computes either the ‘mean’ or ‘median’ across a set of ISCs. In the case of the mean, ISC values are first Fisher Z transformed (arctanh), averaged, then inverse Fisher Z transformed (tanh).

The implementation is based on the work in [SilverDunlap1987].

SilverDunlap1987: “Averaging correlation coefficients: should Fisher’s z transformation be used?”, N. C. Silver, W. P. Dunlap, 1987, Journal of Applied Psychology, 72, 146-148. https://doi.org/10.1037/0021-9010.72.1.146

Parameters

iscs (list or ndarray) – ISC values
summary_statistic (str, default: 'mean') – Summary statistic, ‘mean’ or ‘median’
axis (None or int or tuple of ints, optional) – Axis or axes along which the means are computed. The default is to compute the mean of the flattened array.

Returns

statistic – Summary statistic of ISC values

Return type

float or ndarray

brainiak.isc.isc(data, pairwise=False, summary_statistic=None, tolerate_nans=True)¶

Intersubject correlation

For each voxel or ROI, compute the Pearson correlation between each subject’s response time series and other subjects’ response time series. If pairwise is False (default), use the leave-one-out approach, where correlation is computed between each subject and the average of the other subjects. If pairwise is True, compute correlations between all pairs of subjects. If summary_statistic is None, return N ISC values for N subjects (leave-one-out) or N(N-1)/2 ISC values for each pair of N subjects, corresponding to the upper triangle of the pairwise correlation matrix (see scipy.spatial.distance.squareform). Alternatively, use either ‘mean’ or ‘median’ to compute summary statistic of ISCs (Fisher Z will be applied if using mean). Input data should be a n_TRs by n_voxels by n_subjects array (e.g., brainiak.image.MaskedMultiSubjectData) or a list where each item is a n_TRs by n_voxels ndarray for a given subject. Multiple input ndarrays must be the same shape. If a 2D array is supplied, the last dimension is assumed to correspond to subjects. If only two subjects are supplied, simply compute Pearson correlation (precludes averaging in leave-one-out approach, and does not apply summary statistic). When using leave-one-out approach, NaNs are ignored when computing mean time series of N-1 subjects (default: tolerate_nans=True). Alternatively, you may supply a float between 0 and 1 indicating a threshold proportion of N subjects with non-NaN values required when computing the average time series for a given voxel. For example, if tolerate_nans=.8, ISCs will be computed for any voxel where >= 80% of subjects have non-NaN values, while voxels with < 80% non-NaN values will be assigned NaNs. If set to False, NaNs are not tolerated and voxels with one or more NaNs among the N-1 subjects will be assigned NaN. Setting tolerate_nans to True or False will not affect the pairwise approach; however, if a threshold float is provided, voxels that do not reach this threshold will be excluded. Note that accommodating NaNs may be notably slower than setting tolerate_nans to False. Output is an ndarray where the first dimension is the number of subjects or pairs and the second dimension is the number of voxels (or ROIs). If only two subjects are supplied or a summary statistic is invoked, the output is a ndarray n_voxels long.

The implementation is based on the work in [Hasson2004].

Parameters

data (list or ndarray (n_TRs x n_voxels x n_subjects)) – fMRI data for which to compute ISC
pairwise (bool, default: False) – Whether to use pairwise (True) or leave-one-out (False) approach
summary_statistic (None or str, default: None) – Return all ISCs or collapse using ‘mean’ or ‘median’
tolerate_nans (bool or float, default: True) – Accommodate NaNs (when averaging in leave-one-out approach)

Returns

iscs – ISC for each subject or pair (or summary statistic) per voxel

Return type

subjects or pairs by voxels ndarray

brainiak.isc.isfc(data, targets=None, pairwise=False, summary_statistic=None, vectorize_isfcs=True, tolerate_nans=True)¶

Intersubject functional correlation (ISFC)

For each input voxel or ROI, compute the Pearson correlation between each subject’s response time series and all input voxels or ROIs in other subjects. If a targets array is provided, instead compute ISFCs between each input voxel time series and each voxel time series in targets across subjects (resulting in asymmetric ISFC values). The targets array must have the same number TRs and subjects as the input data. If pairwise is False (default), use the leave-one-out approach, where correlation is computed between each subject and the average of the other subjects. If pairwise is True, compute correlations between all pairs of subjects. If a targets array is provided, only the leave-one-out approach is supported. If summary_statistic is None, return N ISFC values for N subjects (leave-one- out) or N(N-1)/2 ISFC values for each pair of N subjects, corresponding to the triangle of the correlation matrix (scipy.spatial.distance.squareform). Alternatively, use either ‘mean’ or ‘median’ to compute summary statistic of ISFCs (Fisher Z is applied if using mean). Input should be n_TRs by n_voxels by n_subjects array (e.g., brainiak.image.MaskedMultiSubjectData) or a list where each item is a n_TRs by n_voxels ndarray per subject. Multiple input ndarrays must be the same shape. If a 2D array is supplied, the last dimension is assumed to correspond to subjects. If only two subjects are supplied, simply compute ISFC between these two subjects (precludes averaging in leave-one-out approach, and does not apply summary statistic). Returns vectorized upper triangle of ISFC matrices for each subject or pair when vectorized_isfcs=True, or full (redundant) 2D ISFC matrices when vectorized_isfcs=False. When using leave-one-out approach, NaNs are ignored when computing mean time series of N-1 subjects (default: tolerate_nans=True). Alternatively, you may supply a float between 0 and 1 indicating a threshold proportion of N subjects with non-NaN values required when computing the average time series for a given voxel. For example, if tolerate_nans=.8, ISCs will be computed for any voxel where >= 80% of subjects have non-NaN values, while voxels with < 80% non-NaN values will be assigned NaNs. If set to False, NaNs are not tolerated and voxels with one or more NaNs among the N-1 subjects will be assigned NaN. Setting tolerate_nans to True or False will not affect the pairwise approach; however, if a threshold float is provided, voxels that do not reach this threshold will be excluded. Note that accommodating NaNs may be notably slower than setting tolerate_nans to False. Output is either a tuple comprising condensed off-diagonal ISFC values and the diagonal ISC values if vectorize_isfcs=True, or a single ndarray with shape n_subjects (or n_pairs) by n_voxels by n_voxels 3D array if vectorize_isfcs=False (see brainiak.isc.squareform_isfc). If targets array is provided (yielding asymmetric ISFCs), output ISFCs are not vectorized, resulting in an n_subjects by n_voxels by n_targets ISFC array. If summary_statistic is supplied, output is collapsed along first dimension.

The implementation is based on the work in [Simony2016].

Parameters

data (list or ndarray (n_TRs x n_voxels x n_subjects)) – fMRI data for which to compute ISFC
targets (list or ndarray (n_TRs x n_voxels x n_subjects), optional) – fMRI data to use as targets for ISFC
pairwise (bool, default: False) – Whether to use pairwise (True) or leave-one-out (False) approach
summary_statistic (None or str, default: None) – Return all ISFCs or collapse using ‘mean’ or ‘median’
vectorize_isfcs (bool, default: True) – Return tuple of condensed ISFCs and ISCs (True) or square (redundant) ISFCs (False)
tolerate_nans (bool or float, default: True) – Accommodate NaNs (when averaging in leave-one-out approach)

Returns

isfcs – ISFCs for each subject or pair (or summary statistic) per voxel pair

Return type

ndarray or tuple of ndarrays

brainiak.isc.permutation_isc(iscs, group_assignment=None, pairwise=False, summary_statistic='median', n_permutations=1000, side='right', random_state=None)¶

Group-level permutation test for ISCs

For ISCs from one or more voxels or ROIs, permute group assignments to construct a permutation distribution. Input is a list or ndarray of ISCs for a single voxel/ROI, or an ISCs-by-voxels ndarray. In the leave-one-out approach, ISC values for two groups should be stacked along first dimension (vertically) and a group_assignment list (or 1d array) of same length as the number of subjects should be provided to indicate groups. In the pairwise approach, pairwise ISCs should have been computed across both groups at once; i.e. the pairwise ISC matrix should be shaped N x N where N is the total number of subjects across both groups, and should contain between-group ISC pairs. Pairwise ISC input should correspond to the vectorized upper triangle of the square pairwise ISC correlation matrix containing both groups. In the pairwise approach, group_assignment order should match the row/column order of the subject-by-subject square ISC matrix even though the input ISCs should be supplied as the vectorized upper triangle of the square ISC matrix. If no group_assignment is provided, one-sample test is performed using a sign- flipping procedure. Performs exact test if number of possible permutations (2**N for one-sample sign-flipping, N! for two-sample shuffling) is less than or equal to number of requested permutation; otherwise, performs approximate permutation test using Monte Carlo resampling. ISC values should either be N ISC values for N subjects in the leave-one-out approach (pairwise=False) or N(N-1)/2 ISC values for N subjects in the pairwise approach (pairwise=True). Returns the observed ISC and permutation-based p-value as well as the permutation distribution of summary statistic. The p-value corresponds to either a ‘two-sided’, ‘left’-, or ‘right’-sided (default) test, as specified by side. According to Chen et al., 2016, this is the preferred nonparametric approach for controlling false positive rates (FPRs) for two-sample tests. Note that the permutation test may not strictly control FPRs for one-sample tests.

The implementation is based on the work in [Chen2016].

Parameters

iscs (list or ndarray, correlation matrix of ISCs) – ISC values for one or more voxels
group_assignment (list or ndarray, group labels) – Group labels matching order of ISC input
pairwise (bool, default: False) – Indicator of pairwise or leave-one-out, should match ISCs variable
summary_statistic (str, default: 'median') – Summary statistic, either ‘median’ (default) or ‘mean’
n_permutations (int, default: 1000) – Number of permutation iteration (randomizing group assignment)
side (str) – Perform one-sided (‘left’ or ‘right’) or ‘two-sided’ test
= int (random_state) – Initial random seed
None (None) – Initial random seed
np.random.RandomState (or) – Initial random seed
default (None) – Initial random seed

Returns

observed (float, ISC summary statistic or difference) – Actual ISC or group difference (excluding between-group ISCs)
p (float, p-value) – p-value based on permutation test
distribution (ndarray, n_permutations by voxels) – Permutation distribution

brainiak.isc.phaseshift_isc(data, pairwise=False, summary_statistic='median', n_shifts=1000, side='right', tolerate_nans=True, random_state=None)¶

Phase randomization for one-sample ISC test

For each voxel or ROI, compute the actual ISC and p-values from a null distribution of ISCs where response time series are phase randomized prior to computing ISC. If pairwise, apply phase randomization to each subject and compute pairwise ISCs. If leave-one-out approach is used (pairwise=False), only apply phase randomization to the left-out subject in each iteration of the leave-one-out procedure. Input data should be a list where each item is a time-points by voxels ndarray for a given subject. Multiple input ndarrays must be the same shape. If a single ndarray is supplied, the last dimension is assumed to correspond to subjects. When using leave-one-out approach, NaNs are ignored when computing mean time series of N-1 subjects (default: tolerate_nans=True). Alternatively, you may supply a float between 0 and 1 indicating a threshold proportion of N subjects with non-NaN values required when computing the average time series for a given voxel. For example, if tolerate_nans=.8, ISCs will be computed for any voxel where >= 80% of subjects have non-NaN values, while voxels with < 80% non-NaN values will be assigned NaNs. If set to False, NaNs are not tolerated and voxels with one or more NaNs among the N-1 subjects will be assigned NaN. Setting tolerate_nans to True or False will not affect the pairwise approach; however, if a threshold float is provided, voxels that do not reach this threshold will be excluded. Note that accommodating NaNs may be notably slower than setting tolerate_nans to False. Returns the observed ISC and p-values, as well as the null distribution of ISCs computed on phase-randomized data. The p-value corresponds to either a ‘two-sided’, ‘left’-, or ‘right’-sided (default) test, as specified by side. Note that phase randomization may not strictly control false positive rates (FPRs).

The implementation is based on the work in [Lerner2011] and [Simony2016].

Lerner2011: “Topographic mapping of a hierarchy of temporal receptive windows using a narrated story.”, Y. Lerner, C. J. Honey, L. J. Silbert, U. Hasson, 2011, Journal of Neuroscience, 31, 2906-2915. https://doi.org/10.1523/jneurosci.3684-10.2011

Parameters

data (list or ndarray (n_TRs x n_voxels x n_subjects)) – fMRI data for which to compute ISFC
pairwise (bool, default: False) – Whether to use pairwise (True) or leave-one-out (False) approach
summary_statistic (str, default: 'median') – Summary statistic, either ‘median’ (default) or ‘mean’
n_shifts (int, default: 1000) – Number of randomly shifted samples
side (str) – Perform one-sided (‘left’ or ‘right’) or ‘two-sided’ test
tolerate_nans (bool or float, default: True) – Accommodate NaNs (when averaging in leave-one-out approach)
= int (random_state) – Initial random seed
None (None) – Initial random seed
np.random.RandomState (or) – Initial random seed
default (None) – Initial random seed

Returns

observed (float, observed ISC (without time-shifting)) – Actual ISCs
p (float, p-value) – p-value based on time-shifting randomization test
distribution (ndarray, n_shifts by voxels) – Phase-shifted null distribution

brainiak.isc.squareform_isfc(isfcs, iscs=None)¶

Converts square ISFCs to condensed ISFCs (and ISCs), and vice-versa

If input is a 2- or 3-dimensional array of square ISFC matrices, converts this to the condensed off-diagonal ISFC values (i.e., the vectorized triangle) and the diagonal ISC values. In this case, input must be a single array of shape either n_voxels x n_voxels or n_subjects (or n_pairs) x n_voxels x n_voxels. The condensed ISFC values are vectorized according to scipy.spatial.distance.squareform, yielding n_voxels * (n_voxels - 1) / 2 values comprising every voxel pair. Alternatively, if input is an array of condensed off-diagonal ISFC values and an array of diagonal ISC values, the square (redundant) ISFC values are returned. This function mimics scipy.spatial.distance.squareform, but is intended to retain the diagonal ISC values.

Parameters

isfcs (ndarray) – Either condensed or redundant ISFC values
iscs (ndarray, optional) – Diagonal ISC values, required when input is condensed

Returns

isfcs – If condensed ISFCs are passed, a single redundant ISFC array is returned; if redundant ISFCs are passed, both a condensed off- diagonal ISFC array and the diagonal ISC values are returned

Return type

ndarray or tuple of ndarrays

brainiak.isc.timeshift_isc(data, pairwise=False, summary_statistic='median', n_shifts=1000, side='right', tolerate_nans=True, random_state=None)¶

Circular time-shift randomization for one-sample ISC test

For each voxel or ROI, compute the actual ISC and p-values from a null distribution of ISCs where response time series are first circularly shifted by random intervals. If pairwise, apply time-shift randomization to each subjects and compute pairwise ISCs. If leave-one-out approach is used (pairwise=False), apply the random time-shift to only the left-out subject in each iteration of the leave-one-out procedure. Input data should be a list where each item is a time-points by voxels ndarray for a given subject. Multiple input ndarrays must be the same shape. If a single ndarray is supplied, the last dimension is assumed to correspond to subjects. When using leave-one-out approach, NaNs are ignored when computing mean time series of N-1 subjects (default: tolerate_nans=True). Alternatively, you may supply a float between 0 and 1 indicating a threshold proportion of N subjects with non-NaN values required when computing the average time series for a given voxel. For example, if tolerate_nans=.8, ISCs will be computed for any voxel where >= 80% of subjects have non-NaN values, while voxels with < 80% non-NaN values will be assigned NaNs. If set to False, NaNs are not tolerated and voxels with one or more NaNs among the N-1 subjects will be assigned NaN. Setting tolerate_nans to True or False will not affect the pairwise approach; however, if a threshold float is provided, voxels that do not reach this threshold will be excluded. Note that accommodating NaNs may be notably slower than setting tolerate_nans to False. Returns the observed ISC and p-values, as well as the null distribution of ISCs computed on randomly time-shifted data. The p-value corresponds to either a ‘two-sided’, ‘left’-, or ‘right’-sided (default) test, as specified by side. Note that circular time-shift randomization may not strictly control false positive rates (FPRs).

The implementation is based on the work in [Kauppi2010] and [Kauppi2014].

Kauppi2010: “Inter-subject correlation of brain hemodynamic responses during watching a movie: localization in space and frequency.”, J. P. Kauppi, I. P. Jääskeläinen, M. Sams, J. Tohka, 2010, Frontiers in Neuroinformatics, 4, 5. https://doi.org/10.3389/fninf.2010.00005

Parameters

data (list or ndarray (n_TRs x n_voxels x n_subjects)) – fMRI data for which to compute ISFC
pairwise (bool, default: False) – Whether to use pairwise (True) or leave-one-out (False) approach
summary_statistic (str, default: 'median') – Summary statistic, either ‘median’ (default) or ‘mean’
n_shifts (int, default: 1000) – Number of randomly shifted samples
side (str) – Perform one-sided (‘left’ or ‘right’) or ‘two-sided’ test
tolerate_nans (bool or float, default: True) – Accommodate NaNs (when averaging in leave-one-out approach)
= int (random_state) – Initial random seed
None (None) – Initial random seed
np.random.RandomState (or) – Initial random seed
default (None) – Initial random seed

Returns

observed (float, observed ISC (without time-shifting)) – Actual ISCs
p (float, p-value) – p-value based on time-shifting randomization test
distribution (ndarray, n_shifts by voxels) – Time-shifted null distribution