BIAP8 - Always load image data as floating point

Author:

Matthew Brett

Status:

Accepted

Type:

Standards

Created:

2018-04-18

get_fdata shipped as of nibabel 2.2.0.

See this mailing list thread for discussion on an earlier version of this proposal.

Background

Summary

The problem with our current get_data method is that the returned data type is difficult to predict, and can switch between integer and floating point types depending on values in the image header.

The underlying problem is that the author and the user of a given NIfTI image would be unlikely to expect that the scalefactors of the NIfTI header (which the user will probably not be aware of) will affect the calculations done on the image data after loading into memory.

In detail

At the moment, if you do this:

img = nib.load('my_image.nii')
data = img.get_data()

then the data type (dtype) of the returned data array depends on the values in the header of my_image.nii. Specifically, if the raw on-disk data type is np.int16 (it often is) and the header scalefactor values are default (1 for slope, 0 for intercept) then you will get back an array of the on-disk data type - here np.int16.

This is very efficient in terms of memory, but it can be a real trap unless you are careful.

For example, let’s say you had a pipeline where you did this:

sum = img.get_data().sum()

That would work fine most of the time, when the data on disk is floating point, or the scalefactors are not default (1, 0). Then one day, you get an image with int16 data type on disk and (1, 0) scalefactors, and your sum calculation is now being done in int16, and silently overflows. I (MB) ran into this when teaching - I had to cast some image arrays to floating point to get sensible answers.

Current implementation

get_data has the following implementation, at time of writing:

def get_data(self):
    """ Return image data from image with any necessary scalng applied

    If the image data is a array proxy (data not yet read from disk) then
    read the data, and store in an internal cache.  Future calls to
    ``get_data`` will return the cached copy.

    Returns
    -------
    data : array
        array of image data
    """
    if self._data_cache is None:
        self._data_cache = np.asanyarray(self._dataobj)
    return self._data_cache

Note that:

  • self._dataobj may well be an array proxy object;

  • np.asanyarray forces the read of an array proxy object into a numpy array;

  • the read also fills an internal cache.

Proposal - add, prefer get_fdata method

The future default behavior of nibabel should be to do the thing least likely to trip you up by accident. But - we do not want the result of get_data to change silently between nibabel versions.

  • step 1: now - add get_fdata method:

    def get_fdata(self, dtype=np.float64):
    """ Return floating point image data with necessary scalng applied.

    If the image data is an array proxy (data not yet read from disk) then
    read the data from file, and retain the result in an internal cache.
    Future calls to ``get_fdata`` on the same image instance will return
    the cached copy.

    Parameters
    ----------
    dtype : numpy dtype specifier
        A numpy dtype specifier specifying a floating point type.  Data is
        returned as this floating point type.  Default is ``np.float64``.

    Returns
    -------
    fdata : array
        Array of image data of data type `dtype`.
    """
    dtype = np.dtype(dtype)
    if not issubclass(dtype, np.inexact):
        raise ValueError('{} should be floating point type'.format(dtype))
    if self._fdata_cache is None:
        self._fdata_cache = np.asanyarray(self._dataobj).astype(dtype)
    return self._fdata_cache

    Change all instances of get_data in documentation to get_fdata.

    Add warning about pending deprecation in get_data method, with suggestion to use get_fdata or np.asanyarray(img.dataobj) if you want the previous behavior, on the lines of:

    We recommend you use the ``get_fdata`` method instead of the ``get_data``
method, because it is easier to predict the return data type.  We will
deprecate the ``get_data`` method around April 2018, and remove it around
April 2020.

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)``.

    Add floating point cache self._fdata_cache to cache cleared by uncache method.

  • step 2: around one year from now - deprecate get_data method;

  • step 3: around three years from now - make get_data method raise an error such as NotImplementedError with a helpful message, and remove associated self._data_cache attribute. Leave this error in place for a long time, to help people porting older code.