`dataobj_images`¶

File-based images that have data arrays

The class:DataObjImage class defines an image that extends the FileBasedImage by adding an array-like object, named dataobj. This can either be an actual numpy array, or an object that:

returns an array from numpy.asanyarray(obj);
has an attribute or property shape.

DataobjImage(dataobj[, header, extra, file_map])

Template class for images that have dataobj data stores

`DataobjImage`¶

class nibabel.dataobj_images.DataobjImage(dataobj: ArrayLike, header: Optional[Union[FileBasedHeader, Mapping]] = None, extra: Optional[Mapping] = None, file_map: Optional[Mapping[str, FileHolder]] = None)¶

Bases: FileBasedImage

Template class for images that have dataobj data stores

Initialize dataobj image

The datobj image is a combination of (dataobj, header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.

Parameters:

dataobjobject: Object containing image data. It should be some object that returns an array from np.asanyarray. It should have shape and ndim attributes or properties
headerNone or mapping or header instance, optional: metadata for this image format
extraNone or mapping, optional: metadata to associate with image that cannot be stored in the metadata of this image type
file_mapmapping, optional: mapping giving file information for this image format

__init__(dataobj: ArrayLike, header: Optional[Union[FileBasedHeader, Mapping]] = None, extra: Optional[Mapping] = None, file_map: Optional[Mapping[str, FileHolder]] = None)¶

Initialize dataobj image

The datobj image is a combination of (dataobj, header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.

Parameters:

dataobjobject: Object containing image data. It should be some object that returns an array from np.asanyarray. It should have shape and ndim attributes or properties
headerNone or mapping or header instance, optional: metadata for this image format
extraNone or mapping, optional: metadata to associate with image that cannot be stored in the metadata of this image type
file_mapmapping, optional: mapping giving file information for this image format

property dataobj: ArrayLike¶

classmethod from_file_map(file_map: Mapping[str, FileHolder], *, mmap: Union[bool, Literal['c', 'r']] = True, keep_file_open: bool | None = None)¶

Class method to create image from mapping in file_map

Parameters:

file_mapdict: Mapping with (kay, value) pairs of (file_type, FileHolder instance giving file-likes for each file needed for this image type.
mmap{True, False, ‘c’, ‘r’}, optional, keyword only: mmap controls the use of numpy memory mapping for reading image array data. If False, do not try numpy memmap for data array. If one of {‘c’, ‘r’}, try numpy memmap with mode=mmap. A mmap value of True gives the same behavior as mmap='c'. If image data file cannot be memory-mapped, ignore mmap value and read array from file.
keep_file_open{ None, True, False }, optional, keyword only: keep_file_open controls whether a new file handle is created every time the image is accessed, or a single file handle is created and used for the lifetime of this ArrayProxy. If True, a single file handle is created and used. If False, a new file handle is created every time the image is accessed. If file_map refers to an open file handle, this setting has no effect. The default value (None) will result in the value of nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT being used.

Returns:

imgDataobjImage instance

classmethod from_filename(filename: Union[str, PathLike], *, mmap: Union[bool, Literal['c', 'r']] = True, keep_file_open: bool | None = None)¶

Class method to create image from filename filename

Parameters:

filenamestr: Filename of image to load
mmap{True, False, ‘c’, ‘r’}, optional, keyword only: mmap controls the use of numpy memory mapping for reading image array data. If False, do not try numpy memmap for data array. If one of {‘c’, ‘r’}, try numpy memmap with mode=mmap. A mmap value of True gives the same behavior as mmap='c'. If image data file cannot be memory-mapped, ignore mmap value and read array from file.
keep_file_open{ None, True, False }, optional, keyword only: keep_file_open controls whether a new file handle is created every time the image is accessed, or a single file handle is created and used for the lifetime of this ArrayProxy. If True, a single file handle is created and used. If False, a new file handle is created every time the image is accessed. The default value (None) will result in the value of nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT being used.

Returns:

imgDataobjImage instance

get_data(caching='fill')¶

Return image data from image with any necessary scaling applied

get_data() is deprecated in favor of get_fdata(), which has a more predictable return type. To obtain get_data() behavior going forward, use numpy.asanyarray(img.dataobj).

deprecated from version: 3.0
Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 5.0

Warning

We recommend you use the get_fdata method instead of the get_data method, because it is easier to predict the return data type. get_data will be deprecated around November 2019 and removed around November 2021.

If you don’t care about the predictability of the return data type, and you want the minimum possible data size in memory, you can replicate the array that would be returned by img.get_data() by using np.asanyarray(img.dataobj).

The image dataobj property can be an array proxy or an array. An array proxy is an object that knows how to load the image data from disk. An image with an array proxy dataobj is a proxy image; an image with an array in dataobj is an array image.

The default behavior for get_data() on a proxy image is to read the data from the proxy, and store in an internal cache. Future calls to get_data will return the cached array. This is the behavior selected with caching == “fill”.

Once the data has been cached and returned from an array proxy, if you modify the returned array, you will also modify the cached array (because they are the same array). Regardless of the caching flag, this is always true of an array image.

Parameters:

caching{‘fill’, ‘unchanged’}, optional: See the Notes section for a detailed explanation. This argument specifies whether the image object should fill in an internal cached reference to the returned image data array. “fill” specifies that the image should fill an internal cached reference if currently empty. Future calls to get_data will return this cached reference. You might prefer “fill” to save the image object from having to reload the array data from disk on each call to get_data. “unchanged” means that the image should not fill in the internal cached reference if the cache is currently empty. You might prefer “unchanged” to “fill” if you want to make sure that the call to get_data does not create an extra (cached) reference to the returned array. In this case it is easier for Python to free the memory from the returned array.

Returns:

dataarray: array of image data

See also

uncache: empty the array data cache

Notes

All images have a property dataobj that represents the image array data. Images that have been loaded from files usually do not load the array data from file immediately, in order to reduce image load time and memory use. For these images, dataobj is an array proxy; an object that knows how to load the image array data from file.

By default (caching == “fill”), when you call get_data on a proxy image, we load the array data from disk, store (cache) an internal reference to this array data, and return the array. The next time you call get_data, you will get the cached reference to the array, so we don’t have to load the array data from disk again.

Array images have a dataobj property that already refers to an array in memory, so there is no benefit to caching, and the caching keywords have no effect.

For proxy images, you may not want to fill the cache after reading the data from disk because the cache will hold onto the array memory until the image object is deleted, or you use the image uncache method. If you don’t want to fill the cache, then always use get_data(caching='unchanged'); in this case get_data will not fill the cache (store the reference to the array) if the cache is empty (no reference to the array). If the cache is full, “unchanged” leaves the cache full and returns the cached array reference.

The cache can affect the behavior of the image, because if the cache is full, or you have an array image, then modifying the returned array will modify the result of future calls to get_data(). For example you might do this:

>>> import os
>>> import nibabel as nib
>>> from nibabel.testing import data_path
>>> img_fname = os.path.join(data_path, 'example4d.nii.gz')

>>> img = nib.load(img_fname) # This is a proxy image
>>> nib.is_proxy(img.dataobj)
True

The array is not yet cached by a call to “get_data”, so:

>>> img.in_memory
False

After we call get_data using the default caching == ‘fill’, the cache contains a reference to the returned array data:

>>> data = img.get_data()
>>> img.in_memory
True

We modify an element in the returned data array:

>>> data[0, 0, 0, 0]
0
>>> data[0, 0, 0, 0] = 99
>>> data[0, 0, 0, 0]
99

The next time we call ‘get_data’, the method returns the cached reference to the (modified) array:

>>> data_again = img.get_data()
>>> data_again is data
True
>>> data_again[0, 0, 0, 0]
99

If you had initially used caching == ‘unchanged’ then the returned data array would have been loaded from file, but not cached, and:

>>> img = nib.load(img_fname)  # a proxy image again
>>> data = img.get_data(caching='unchanged')
>>> img.in_memory
False
>>> data[0, 0, 0] = 99
>>> data_again = img.get_data(caching='unchanged')
>>> data_again is data
False
>>> data_again[0, 0, 0, 0]
0

get_fdata(caching: ty.Literal['fill', 'unchanged'] = 'fill', dtype: npt.DTypeLike = <class 'numpy.float64'>) → np.ndarray¶

Return floating point image data with necessary scaling applied

The default behavior for get_fdata() on a proxy image is to read the data from the proxy, and store in an internal cache. Future calls to get_fdata will return the cached array. This is the behavior selected with caching == “fill”.

Parameters:

caching{‘fill’, ‘unchanged’}, optional: See the Notes section for a detailed explanation. This argument specifies whether the image object should fill in an internal cached reference to the returned image data array. “fill” specifies that the image should fill an internal cached reference if currently empty. Future calls to get_fdata will return this cached reference. You might prefer “fill” to save the image object from having to reload the array data from disk on each call to get_fdata. “unchanged” means that the image should not fill in the internal cached reference if the cache is currently empty. You might prefer “unchanged” to “fill” if you want to make sure that the call to get_fdata does not create an extra (cached) reference to the returned array. In this case it is easier for Python to free the memory from the returned array.
dtypenumpy dtype specifier: A numpy dtype specifier specifying a floating point type. Data is returned as this floating point type. Default is np.float64.

Returns:

fdataarray: Array of image data of data type dtype.

See also

uncache: empty the array data cache

Notes

By default (caching == “fill”), when you call get_fdata on a proxy image, we load the array data from disk, store (cache) an internal reference to this array data, and return the array. The next time you call get_fdata, you will get the cached reference to the array, so we don’t have to load the array data from disk again.

Array images have a dataobj property that already refers to an array in memory, so there is no benefit to caching, and the caching keywords have no effect.

For proxy images, you may not want to fill the cache after reading the data from disk because the cache will hold onto the array memory until the image object is deleted, or you use the image uncache method. If you don’t want to fill the cache, then always use get_fdata(caching='unchanged'); in this case get_fdata will not fill the cache (store the reference to the array) if the cache is empty (no reference to the array). If the cache is full, “unchanged” leaves the cache full and returns the cached array reference.

The cache can effect the behavior of the image, because if the cache is full, or you have an array image, then modifying the returned array will modify the result of future calls to get_fdata(). For example you might do this:

>>> import os
>>> import nibabel as nib
>>> from nibabel.testing import data_path
>>> img_fname = os.path.join(data_path, 'example4d.nii.gz')

>>> img = nib.load(img_fname) # This is a proxy image
>>> nib.is_proxy(img.dataobj)
True

The array is not yet cached by a call to “get_fdata”, so:

>>> img.in_memory
False

After we call get_fdata using the default caching == ‘fill’, the cache contains a reference to the returned array data:

>>> data = img.get_fdata()
>>> img.in_memory
True

We modify an element in the returned data array:

>>> data[0, 0, 0, 0]
0.0
>>> data[0, 0, 0, 0] = 99
>>> data[0, 0, 0, 0]
99.0

The next time we call ‘get_fdata’, the method returns the cached reference to the (modified) array:

>>> data_again = img.get_fdata()
>>> data_again is data
True
>>> data_again[0, 0, 0, 0]
99.0

If you had initially used caching == ‘unchanged’ then the returned data array would have been loaded from file, but not cached, and:

>>> img = nib.load(img_fname)  # a proxy image again
>>> data = img.get_fdata(caching='unchanged')
>>> img.in_memory
False
>>> data[0, 0, 0] = 99
>>> data_again = img.get_fdata(caching='unchanged')
>>> data_again is data
False
>>> data_again[0, 0, 0, 0]
0.0

property in_memory: bool¶

True when any array data is in memory cache

There are separate caches for get_data reads and get_fdata reads. This property is True if either of those caches are set.

classmethod load(filename: Union[str, PathLike], *, mmap: Union[bool, Literal['c', 'r']] = True, keep_file_open: bool | None = None)¶

Class method to create image from filename filename

Parameters:

filenamestr: Filename of image to load
mmap{True, False, ‘c’, ‘r’}, optional, keyword only: mmap controls the use of numpy memory mapping for reading image array data. If False, do not try numpy memmap for data array. If one of {‘c’, ‘r’}, try numpy memmap with mode=mmap. A mmap value of True gives the same behavior as mmap='c'. If image data file cannot be memory-mapped, ignore mmap value and read array from file.
keep_file_open{ None, True, False }, optional, keyword only: keep_file_open controls whether a new file handle is created every time the image is accessed, or a single file handle is created and used for the lifetime of this ArrayProxy. If True, a single file handle is created and used. If False, a new file handle is created every time the image is accessed. The default value (None) will result in the value of nibabel.arrayproxy.KEEP_FILE_OPEN_DEFAULT being used.

Returns:

imgDataobjImage instance

property ndim: int¶

property shape: tuple[int, ...]¶

uncache() → None¶

Delete any cached read of data from proxied data

Remember there are two types of images:

array images where the data img.dataobj is an array
proxy images where the data img.dataobj is a proxy object

If you call img.get_fdata() on a proxy image, the result of reading from the proxy gets cached inside the image object, and this cache is what gets returned from the next call to img.get_fdata(). If you modify the returned data, as in:

data = img.get_fdata()
data[:] = 42

then the next call to img.get_fdata() returns the modified array, whether the image is an array image or a proxy image:

assert np.all(img.get_fdata() == 42)

When you uncache an array image, this has no effect on the return of img.get_fdata(), but when you uncache a proxy image, the result of img.get_fdata() returns to its original value.

NiBabel

Access a cacophony of neuro-imaging file formats

Table of Contents

Previous topic

Next topic

`dataobj_images`¶

`DataobjImage`¶

NiBabel

Access a cacophony of neuro-imaging file formats

dataobj_images¶

DataobjImage¶

`dataobj_images`¶

`DataobjImage`¶