NiBabel

Access a cacophony of neuro-imaging file formats

Table Of Contents

Previous topic

nibabel.quaternions.rotate_vector

Next topic

nibabel.spatialimages.Header

Reggie -- the one

nibabel.spatialimages

Very simple spatial image class

The image class maintains the association between a 3D (or greater) array, and an affine transform that maps voxel coordinates to some real world space. It also has a header - some standard set of meta-data that is specific to the image format - and extra - a dictionary container for any other metadata.

It has attributes:

  • extra

methods:

  • .get_data()
  • .get_affine()
  • .get_header()
  • .set_shape(shape)
  • .to_filename(fname) - writes data to filename(s) derived from fname, where the derivation may differ between formats.
  • to_file_map() - save image to files with which the image is already associated.
  • .get_shape() (Deprecated)

properties:

  • shape

classmethods:

  • from_filename(fname) - make instance by loading from filename
  • instance_to_filename(img, fname) - save img instance to filename fname.

There are several ways of writing data.

There is the usual way, which is the default:

img.to_filename(fname)

and that is, to take the data encapsulated by the image and cast it to the datatype the header expects, setting any available header scaling into the header to help the data match.

You can load the data into an image from file with:

img.from_filename(fname)

The image stores its associated files in its files attribute. In order to just save an image, for which you know there is an associated filename, or other storage, you can do:

img.to_file_map()

You can get the data out again with of:

img.get_data()

Less commonly, for some image types that support it, you might want to fetch out the unscaled array via the header:

unscaled_data = img.get_unscaled_data()

Analyze-type images (including nifti) support this, but others may not (MINC, for example).

Sometimes you might to avoid any loss of precision by making the data type the same as the input:

hdr = img.get_header()
hdr.set_data_dtype(data.dtype)
img.to_filename(fname)

Files interface

The image has an attribute file_map. This is a mapping, that has keys corresponding to the file types that an image needs for storage. For example, the Analyze data format needs an image and a header file type for storage:

>>> import nibabel as nib
>>> data = np.arange(24, dtype='f4').reshape((2,3,4))
>>> img = nib.AnalyzeImage(data, np.eye(4))
>>> sorted(img.file_map)
['header', 'image']

The values of file_map are not in fact files but objects with attributes filename, fileobj and pos.

The reason for this interface, is that the contents of files has to contain enough information so that an existing image instance can save itself back to the files pointed to in file_map. When a file holder holds active file-like objects, then these may be affected by the initial file read; in this case, the contains file-like objects need to carry the position at which a write (with to_files) should place the data. The file_map contents should therefore be such, that this will work:

>>> # write an image to files
>>> from StringIO import StringIO #23dt : BytesIO
>>> file_map = nib.AnalyzeImage.make_file_map()
>>> file_map['image'].fileobj = StringIO() #23dt : BytesIO
>>> file_map['header'].fileobj = StringIO() #23dt : BytesIO
>>> img = nib.AnalyzeImage(data, np.eye(4))
>>> img.file_map = file_map
>>> img.to_file_map()
>>> # read it back again from the written files
>>> img2 = nib.AnalyzeImage.from_file_map(file_map)
>>> np.all(img2.get_data() == data)
True
>>> # write, read it again
>>> img2.to_file_map()
>>> img3 = nib.AnalyzeImage.from_file_map(file_map)
>>> np.all(img3.get_data() == data)
True

digraph inheritance90953247c4 { rankdir=LR; ratio=compress; fontsize=14; size="6.0, 8.0"; "ImageDataError" [shape=ellipse,fontname=Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans,fontsize=14,color=dodgerblue1,style=filled,height=0.75]; "HeaderDataError" [shape=ellipse,fontname=Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans,fontsize=14,color=dodgerblue1,style=filled,height=0.75]; "Header" [shape=ellipse,URL="nibabel.spatialimages.Header.html#nibabel.spatialimages.Header",fontname=Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans,fontsize=14,color=dodgerblue1,style=filled,height=0.75]; "ImageFileError" [shape=ellipse,fontname=Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans,fontsize=14,color=dodgerblue1,style=filled,height=0.75]; "SpatialImage" [shape=ellipse,URL="nibabel.spatialimages.SpatialImage.html#nibabel.spatialimages.SpatialImage",fontname=Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans,fontsize=14,color=dodgerblue1,style=filled,height=0.75]; "HeaderTypeError" [shape=ellipse,fontname=Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans,fontsize=14,color=dodgerblue1,style=filled,height=0.75]; }

Classes

Header([data_dtype, shape, zooms]) Template class to implement header protocol
SpatialImage(data, affine[, header, extra, ...]) Initialize image

Exceptions

Header([data_dtype, shape, zooms]) Template class to implement header protocol
SpatialImage(data, affine[, header, extra, ...]) Initialize image