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

nilearn.image.check_niimg(niimg, ensure_ndim=None, atleast_4d=False, dtype=None, return_iterator=False, wildcards=True)

Check that niimg is a proper 3D/4D niimg.

Turn filenames into objects.

Parameters:

niimgNiimg-like object

See Input and output: neuroimaging data representation. If niimg is a string or pathlib.Path, consider it as a path to Nifti image and call nibabel.load on it. The '~' symbol is expanded to the user home folder. If it is an object, check if the affine attribute present and that nilearn.image.get_data returns a result, raise TypeError otherwise.

ensure_ndim{3, 4, None}, default=None

Indicate the dimensionality of the expected niimg. An error is raised if the niimg is of another dimensionality.

atleast_4dbool, default=False

Indicates if a 3d image should be turned into a single-scan 4d niimg.

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.

return_iteratorbool, default=False

Returns an iterator on the content of the niimg file input.

wildcardsbool, default=True

Use niimg as a regular expression to get a list of matching input filenames. If multiple files match, the returned list is sorted using an ascending order. If no file matches the regular expression, a ValueError exception is raised.

Returns:

result3D/4D 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.

See also

check_niimg_3d, check_niimg_4d

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 the image:

>>> from nilearn.image import check_niimg
>>> checked_img = check_niimg(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 also check the image specifying the expected dimension. For example for a 3D image:

>>> from nilearn.image import check_niimg
>>> checked_img = check_niimg(img_3d, ensure_ndim=3)

Let’s check to ensure the same image to be 4D:

>>> from nilearn.image import check_niimg
>>> checked_img = check_niimg(img_3d, ensure_ndim=4)
Traceback (most recent call last):
  ...
nilearn.exceptions.DimensionError: Input data has incompatible
dimensionality: Expected dimension is 4D and you provided a 3D image.
See https://nilearn.github.io/stable/manipulating_images/input_output.html.