Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

nilearn.image.check_niimg_3d¶

nilearn.image.check_niimg_3d(niimg, dtype=None)[source]¶

Check that niimg is a proper 3D niimg-like object and load it.

Parameters:

niimgNiimg-like object: See Input and output: neuroimaging data representation. If niimg is a string, consider it as a path to Nifti image and call nibabel.load on it. If it is an object, check if the affine attribute present and that nilearn.image.get_data returns a result, raise TypeError otherwise.
dtypedtype like, “auto” or None, default=None: Data type toward which the data should be converted. If “auto”, the data will be converted to int32 if dtype is discrete and to float32 if it is continuous. If None, data will not be converted to a new data type. dtype=bool will raise an Exception.

Returns:

result3D Niimg-like object: Result can be nibabel.Nifti1Image or the input, as-is. It is guaranteed that the returned object has an affine attribute and that its data can be retrieved with nilearn.image.get_data.

Notes

In nilearn, special care has been taken to make image manipulation easy. This method is a kind of pre-requisite for any data processing method in Nilearn because it checks if data have a correct format and loads them if necessary.

Its application is idempotent.

Examples

>>> # Let's create a 3D Nifti1Image.
>>> import numpy as np
>>> from nibabel import Nifti1Image
>>> img_3d = Nifti1Image(
...     np.arange(24).reshape((2, 3, 4)), affine=np.eye(4), dtype=np.int32
... )
>>>
>>> # We can check if img_3d is a proper 3D image.
>>> from nilearn.image import check_niimg_3d
>>> checked_img = check_niimg_3d(img_3d)
>>>
>>> # We can get the data of the image.
>>> from nilearn.image import get_data
>>> data = get_data(checked_img)
>>> data
array([[[ 0,  1,  2,  3],
        [ 4,  5,  6,  7],
        [ 8,  9, 10, 11]],
       [[12, 13, 14, 15],
        [16, 17, 18, 19],
        [20, 21, 22, 23]]])
>>>
>>> # We can try it with a 4D image.
>>> img_4d = Nifti1Image(
...     np.arange(24).reshape((2, 3, 2, 2)),
...     affine=np.eye(4),
...     dtype=np.int32,
... )
>>>
>>> # Let's see the result for img_4d.
>>> checked_img = check_niimg_3d(img_4d)
Traceback (most recent call last):
  ...
nilearn.exceptions.DimensionError: Input data has incompatible
dimensionality: Expected dimension is 3D and you provided a 4D image.
See https://nilearn.github.io/stable/manipulating_images/input_output.html.