Multivariate Pattern Analysis in Python

# mvpa2.misc.plot.lightbox.SpatialImage

class `mvpa2.misc.plot.lightbox.``SpatialImage`(dataobj, affine, header=None, extra=None, file_map=None)

  Initialize image

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

  Parameters:

  dataobj : object

  > Object containg image data. It should be some object that retuns an array from `np.asanyarray`. It should have a `shape` attribute or property

  affine : None or (4,4) array-like

  > homogenous affine giving relationship between voxel coordinates and world coordinates. Affine can also be None. In this case, `obj.affine` also returns None, and the affine as written to disk will depend on the file format.

  header : None or mapping or header instance, optional

  > metadata for this image format

  extra : None or mapping, optional

  > metadata to associate with image that cannot be stored in the metadata of this image type

  file_map : mapping, optional

  > mapping giving file information for this image format

  Attributes

  `affine` |
  `dataobj` |
  `header` |
  `in_memory` | True when array data is in memory
  `shape` |

  Methods

  `affine`
  `dataobj`
  `files_types` = (('image', None),)
  classmethod `filespec_to_file_map`(klass, filespec)

    Make `file_map` for this class from filename `filespec`

    Class method

    Parameters:

    filespec : str

    > Filename that might be for this image file type.

    Returns:

    file_map : dict

    > `file_map` dict with (key, value) pairs of (`file_type`, FileHolder instance), where `file_type` is a string giving the type of the contained file.

    Raises:

    ImageFileError

    > if `filespec` is not recognizable as being a filename for this image type.

  classmethod `filespec_to_files`(klass, filespec)
  classmethod `from_file_map`(klass, file_map)
  classmethod `from_filename`(klass, filename)
  classmethod `from_files`(klass, file_map)
  classmethod `from_filespec`(klass, filespec)
  classmethod `from_image`(klass, img)

    Class method to create new instance of own class from `img`

    Parameters:

    img : `spatialimage` instance

    > In fact, an object with the API of `spatialimage` - specifically `dataobj`, `affine`, `header` and `extra`.

    Returns:

    cimg : `spatialimage` instance

    > Image, of our own class

  `get_affine`()

    Get affine from image

    Please use the `affine` property instead of `get_affine`; we will deprecate this method in future versions of nibabel.

  `get_data`(caching='fill')

    Return image data from image with any necessary scalng applied

    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:

    data : array

    > 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 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_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_data_dtype`()
  `get_filename`()

    Fetch the image filename

    Parameters: | None

    Returns:

    fname : None or str

    > Returns None if there is no filename, or a filename string. If an image may have several filenames assoctiated with it (e.g Analyze `.img, .hdr` pair) then we return the more characteristic filename (the `.img` filename in the case of Analyze’)

  `get_header`()

    Get header from image

    Please use the `header` property instead of `get_header`; we will deprecate this method in future versions of nibabel.

  `get_shape`()

    Return shape for image

    This function deprecated; please use the `shape` property instead

  `header`
  `header_class`

    alias of `Header`

  `in_memory`

    True when array data is in memory

  classmethod `instance_to_filename`(klass, img, filename)

    Save `img` in our own format, to name implied by `filename`

    This is a class method

    Parameters:

    img : `spatialimage` instance

    > In fact, an object with the API of `spatialimage` - specifically `dataobj`, `affine`, `header` and `extra`.

    filename : str

    > Filename, implying name to which to save image.

  classmethod `load`(klass, filename)
  classmethod `make_file_map`(klass, mapping=None)

    Class method to make files holder for this image type

    Parameters:

    mapping : None or mapping, optional

    > mapping with keys corresponding to image file types (such as ‘image’, ‘header’ etc, depending on image class) and values that are filenames or file-like. Default is None

    Returns:

    file_map : dict

    > dict with string keys given by first entry in tuples in sequence klass.files_types, and values of type FileHolder, where FileHolder objects have default values, other than those given by `mapping`

  `set_data_dtype`(dtype)
  `set_filename`(filename)

    Sets the files in the object from a given filename

    The different image formats may check whether the filename has an extension characteristic of the format, and raise an error if not.

    Parameters:

    filename : str

    > If the image format only has one file associated with it, this will be the only filename set into the image `.file_map` attribute. Otherwise, the image instance will try and guess the other filenames from this given filename.

  `shape`
  `to_file_map`(file_map=None)
  `to_filename`(filename)

    Write image to files implied by filename string

    Parameters:

    filename : str

    > filename to which to save image. We will parse `filename` with `filespec_to_file_map` to work out names for image, header etc.

    Returns: | None

  `to_files`(file_map=None)
  `to_filespec`(filename)
  `uncache`()

    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_data()` 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_data()`. If you modify the returned data, as in:

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

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

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

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

  `update_header`()

    Harmonize header with image data and affine

        >>> data = np.zeros((2,3,4))
        >>> affine = np.diag([1.0,2.0,3.0,1.0])
        >>> img = SpatialImage(data, affine)
        >>> img.shape == (2, 3, 4)
        True
        >>> img.update_header()
        >>> img.header.get_data_shape() == (2, 3, 4)
        True
        >>> img.header.get_zooms()
        (1.0, 2.0, 3.0)