brainiak package

Brain Imaging Analysis Kit.

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.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.

class brainiak.image.MaskedMultiSubjectData

Bases: numpy.ndarray

Array in shape n_voxels, n_trs, n_subjects.

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

Create a new instance from masked images.

Parameters:
  • masked_images – Images to concatenate.
  • n_sub – Number of subjects. Must match the number of images.
Returns:

A new instance.

Return type:

T

Raises:

ValueError – Images have different shapes.

The number of images differs from n_sub.

brainiak.image.multimask_images(images: typing.Iterable[nibabel.spatialimages.SpatialImage], masks: typing.Sequence[numpy.ndarray], image_type: type = None) → typing.Iterable[typing.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: typing.Union[str, pathlib.Path], predicate: typing.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_from_dir(in_dir: typing.Union[str, pathlib.Path], suffix: str = 'nii.gz') → typing.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.

brainiak.io.load_labels(path: typing.Union[str, pathlib.Path]) → typing.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: typing.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.isfc module

Intersubject analyses (ISC/ISFC)

Functions for computing intersubject correlation (ISC) and intersubject functional correlation (ISFC)

Paper references: ISC: Hasson, U., Nir, Y., Levy, I., Fuhrmann, G. & Malach, R. Intersubject synchronization of cortical activity during natural vision. Science 303, 1634–1640 (2004).

ISFC: Simony E, Honey CJ, Chen J, Lositsky O, Yeshurun Y, Wiesel A, Hasson U (2016) Dynamic reconfiguration of the default mode network during narrative comprehension. Nat Commun 7.

brainiak.isfc.isc(D, collapse_subj=True, return_p=False, num_perm=1000, two_sided=False, random_state=0, float_type=<class 'numpy.float64'>)

Intersubject correlation

For each voxel, computes the correlation of each subject’s timecourse with the mean of all other subjects’ timecourses. By default the result is averaged across subjects, unless collapse_subj is set to False. A null distribution can optionally be computed using phase randomization, to compute a p value for each voxel.

Parameters:
  • D (voxel by time by subject ndarray) – fMRI data for which to compute ISC
  • collapse_subj (bool, default:True) – Whether to average across subjects before returning result
  • return_p (bool, default:False) – Whether to use phase randomization to compute a p value for each voxel
  • num_perm (int, default:1000) – Number of null samples to use for computing p values
  • two_sided (bool, default:False) – Whether the p value should be one-sided (testing only for being above the null) or two-sided (testing for both significantly positive and significantly negative values)
  • random_state (RandomState or an int seed (0 by default)) – A random number generator instance to define the state of the random permutations generator.
  • float_type (either float16, float32, or float64,) – Depends on the required precision and available memory in the system. All the arrays generated during the execution will be cast to specified float type in order to save memory.
Returns:

  • ISC (voxel ndarray (or voxel by subject ndarray, if collapse_subj=False)) – pearson correlation for each voxel, across subjects
  • p (ndarray the same shape as ISC (if return_p = True)) – p values for each ISC value under the null distribution

brainiak.isfc.isfc(D, collapse_subj=True, return_p=False, num_perm=1000, two_sided=False, random_state=0, float_type=<class 'numpy.float64'>)

Intersubject functional correlation

Computes the correlation between the timecoure of each voxel in each subject with the average of all other subjects’ timecourses in all voxels. By default the result is averaged across subjects, unless collapse_subj is set to False. A null distribution can optionally be computed using phase randomization, to compute a p value for each voxel-to- voxel correlation.

Uses the high performance compute_correlation routine from fcma.util

Parameters:
  • D (voxel by time by subject ndarray) – fMRI data for which to compute ISFC
  • collapse_subj (bool, default:True) – Whether to average across subjects before returning result
  • return_p (bool, default:False) – Whether to use phase randomization to compute a p value for each voxel
  • num_perm (int, default:1000) – Number of null samples to use for computing p values
  • two_sided (bool, default:False) – Whether the p value should be one-sided (testing only for being above the null) or two-sided (testing for both significantly positive and significantly negative values)
  • random_state (RandomState or an int seed (0 by default)) – A random number generator instance to define the state of the random permutations generator.
  • float_type (either float16, float32, or float64) – Depends on the required precision and available memory in the system. All the arrays generated during the execution will be cast to specified float type in order to save memory.
Returns:

  • ISFC (voxel by voxel ndarray) – (or voxel by voxel by subject ndarray, if collapse_subj=False) pearson correlation between all pairs of voxels, across subjects
  • p (ndarray the same shape as ISC (if return_p = True)) – p values for each ISC value under the null distribution