This content refers to the previous stable release of PyMVPA. Please visit www.pymvpa.org for the most recent version of PyMVPA and its documentation.

datasets.nifti

Module: datasets.nifti

Inheritance diagram for mvpa.datasets.nifti:

Dataset that gets its samples from a NIfTI file

Classes

ERNiftiDataset

class mvpa.datasets.nifti.ERNiftiDataset(samples=None, events=None, mask=None, evconv=False, storeoffset=False, tr=None, enforce_dim=4, scale_data=True, **kwargs)

Bases: mvpa.datasets.event.EventDataset

Dataset with event-defined samples from a NIfTI timeseries image.

This is a convenience dataset to facilitate the analysis of event-related fMRI datasets. Boxcar-shaped samples are automatically extracted from the full timeseries using Event definition lists. For each event all volumes covering that particular event in time (including partial coverage) are used to form the corresponding sample.

The class supports the conversion of events defined in ‘realtime’ into the descrete temporal space defined by the NIfTI image. Moreover, potentially varying offsets between true event onset and timepoint of the first selected volume can be stored as an additional feature in the dataset.

Additionally, the dataset supports masking. This is done similar to the masking capabilities of NiftiDataset. However, the mask can either be of the same shape as a single NIfTI volume, or can be of the same shape as the generated boxcar samples, i.e. a samples consisting of three volumes with 24 slices and 64x64 inplane resolution needs a mask with shape (3, 24, 64, 64). In the former case the mask volume is automatically expanded to be identical in a volumes of the boxcar.

Parameters:

• mask (str | NiftiImage | ndarray) – Filename of a NIfTI image or a NiftiImage instance or an ndarray of appropriate shape.
• evconv (bool) – Convert event definitions using onset and duration in some temporal unit into #sample notation.
• storeoffset (bool) – Whether to store temproal offset information when converting Events into descrete time. Only considered when evconv == True.
• tr (float) – Temporal distance of two adjacent NIfTI volumes. This can be used to override the corresponding value in the NIfTI header.
• enforce_dim (int or None) – If not None, it is the dimensionality of the data to be enforced, commonly 4D for the data, and 3D for the mask in case of fMRI.
• scale_data (bool) – NIfTI header specifies scl_slope and scl_inter for scaling and offsetting the data. By default those will get applied to the data (change in behavior post 0.4.6).

map2Nifti(data=None)

Maps a data vector into the dataspace and wraps it with a NiftiImage. The header data of this object is used to initialize the new NiftiImage (scl_slope and scl_inter are reset to 1.0 and 0.0 accordingly).

Note

Only the features corresponding to voxels are mapped back – not any additional features passed via the Event definitions.

Parameters:data (ndarray or Dataset) – The data to be wrapped into NiftiImage. If None (default), it would wrap samples of the current dataset. If it is a Dataset instance – takes its samples for mapping

niftihdr

Access to the NIfTI header dictionary.

NiftiDataset

class mvpa.datasets.nifti.NiftiDataset(samples=None, mask=None, dsattr=None, enforce_dim=4, scale_data=True, **kwargs)

Bases: mvpa.datasets.mapped.MappedDataset

Dataset loading its samples from a NIfTI image or file.

Samples can be loaded from a NiftiImage instance or directly from a NIfTI file. This class stores all relevant information from the NIfTI file header and provides information about the metrics and neighborhood information of all voxels.

Most importantly it allows to map data back into the original data space and format via map2Nifti().

This class allows for convenient pre-selection of features by providing a mask to the constructor. Only non-zero elements from this mask will be considered as features.

NIfTI files are accessed via PyNIfTI. See http://niftilib.sourceforge.net/pynifti/ for more information about pynifti.

Parameters:

• samples (str | NiftiImage) – Filename of a NIfTI image or a NiftiImage instance.
• mask (str | NiftiImage | ndarray) – Filename of a NIfTI image or a NiftiImage instance or an ndarray of appropriate shape.
• enforce_dim (int or None) – If not None, it is the dimensionality of the data to be enforced, commonly 4D for the data, and 3D for the mask in case of fMRI.
• scale_data (bool) – NIfTI header specifies scl_slope and scl_inter for scaling and offsetting the data. By default those will get applied to the data (change in behavior post 0.4.6).

dt

Time difference between two samples (in seconds). AKA TR in fMRI world.

getDt()

Return the temporal distance of two samples/volumes.

This method tries to be clever and always returns dt in seconds, by using unit information from the NIfTI header. If such information is not present the assumed unit will also be seconds.

map2Nifti(data=None)

Maps a data vector into the dataspace and wraps it with a NiftiImage. The header data of this object is used to initialize the new NiftiImage (scl_slope and scl_inter are reset to 1.0 and 0.0 accordingly).

Parameters:data (ndarray or Dataset) – The data to be wrapped into NiftiImage. If None (default), it would wrap samples of the current dataset. If it is a Dataset instance – takes its samples for mapping

niftihdr

Access to the NIfTI header dictionary.

samplingrate

Sampling rate (based on .dt).

Functions

mvpa.datasets.nifti.getNiftiData(nim)

Convenience function to extract the data array from a NiftiImage

This function will make use of advanced features of PyNIfTI to prevent unnecessary copying if a sufficent version is available.

mvpa.datasets.nifti.getNiftiFromAnySource(src, ensure=False, enforce_dim=None, scale_data=True)

Load/access NIfTI data from files or instances.

Parameters:

• src (str | NiftiImage) – Filename of a NIfTI image or a NiftiImage instance.
• ensure (bool) – If True, through ValueError exception if cannot be loaded.
• enforce_dim (int or None) – If not None, it is the dimensionality of the data to be enforced, commonly 4D for the data, and 3D for the mask in case of fMRI.
• scale_data (bool) – NIfTI header specifies scl_slope and scl_inter for scaling and offsetting the data. By default those will get applied to the data (change in behavior post 0.4.6).

Return type:

NiftiImage | None

Returns:

If the source is not supported None is returned.