mvpa2.datasets.mri.fmri_dataset

mvpa2.datasets.mri.fmri_dataset(samples, targets=None, chunks=None, mask=None, sprefix='voxel', tprefix='time', add_fa=None)

Create a dataset from an fMRI timeseries image.

The timeseries image serves as the samples data, with each volume becoming a sample. All 3D volume samples are flattened into one-dimensional feature vectors, optionally being masked (i.e. subset of voxels corresponding to non-zero elements in a mask image).

In addition to (optional) samples attributes for targets and chunks the returned dataset contains a number of additional attributes:

Samples attributes (per each volume):

  • volume index (time_indices)
  • volume acquisition time (time_coord)

Feature attributes (per each voxel):

  • voxel indices (voxel_indices), sometimes referred to as ijk

Dataset attributes:

  • dump of the image (e.g. NIfTI) header data (imghdr)
  • class of the image (e.g. Nifti1Image) (imgtype)
  • volume extent (voxel_dim)
  • voxel extent (voxel_eldim)

The default attribute name is listed in parenthesis, but may be altered by the corresponding prefix arguments. The validity of the attribute values relies on correct settings in the NIfTI image header.

Parameters:

samples : str or NiftiImage or list

fMRI timeseries, specified either as a filename (single file 4D image), an image instance (4D image), or a list of filenames or image instances (each list item corresponding to a 3D volume).

targets : scalar or sequence

Label attribute for each volume in the timeseries, or a scalar value that is assigned to all samples.

chunks : scalar or sequence

Chunk attribute for each volume in the timeseries, or a scalar value that is assigned to all samples.

mask : str or NiftiImage

Filename or image instance of a 3D volume mask. Voxels corresponding to non-zero elements in the mask will be selected. The mask has to be in the same space (orientation and dimensions) as the timeseries image

sprefix : str or None

Prefix for attribute names describing spatial properties of the timeseries. If None, no such attributes are stored in the dataset.

tprefix : str or None

Prefix for attribute names describing temporal properties of the timeseries. If None, no such attributes are stored in the dataset.

add_fa : dict or None

Optional dictionary with additional volumetric data that shall be stored as feature attributes in the dataset. The dictionary key serves as the feature attribute name. Each value might be of any type supported by the ‘mask’ argument of this function.
Returns:

Dataset