NiBabel

Access a cacophony of neuro-imaging file formats

Previous topic

nibabel.analyze.AnalyzeImage

Next topic

nibabel.analyze.AnalyzeImage

Reggie -- the one

nibabel.analyze.AnalyzeHeader

digraph inheritance2c00aae88a { rankdir=LR; ratio=compress; fontsize=14; size="6.0, 8.0"; "WrapStruct" [shape=ellipse,fontname=Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans,fontsize=14,color=dodgerblue1,style=filled,height=0.75]; "AnalyzeHeader" [shape=ellipse,URL="#nibabel.analyze.AnalyzeHeader",fontname=Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans,fontsize=14,color=dodgerblue1,style=filled,height=0.75]; "WrapStruct" -> "AnalyzeHeader" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

class nibabel.analyze.AnalyzeHeader(binaryblock=None, endianness=None, check=True)

Class for basic analyze header

Implements zoom-only setting of affine transform, and no image scaling

Initialize header from binary data block

Parameters :

binaryblock : {None, string} optional

binary block to set into header. By default, None, in which case we insert the default empty header block

endianness : {None, ‘<’,’>’, other endian code} string, optional

endianness of the binaryblock. If None, guess endianness from the data.

check : bool, optional

Whether to check content of header in initialization. Default is True.

Examples

>>> hdr1 = AnalyzeHeader() # an empty header
>>> hdr1.endianness == native_code
True
>>> hdr1.get_data_shape()
(0,)
>>> hdr1.set_data_shape((1,2,3)) # now with some content
>>> hdr1.get_data_shape()
(1, 2, 3)

We can set the binary block directly via this initialization. Here we get it from the header we have just made

>>> binblock2 = hdr1.binaryblock
>>> hdr2 = AnalyzeHeader(binblock2)
>>> hdr2.get_data_shape()
(1, 2, 3)

Empty headers are native endian by default

>>> hdr2.endianness == native_code
True

You can pass valid opposite endian headers with the endianness parameter. Even empty headers can have endianness

>>> hdr3 = AnalyzeHeader(endianness=swapped_code)
>>> hdr3.endianness == swapped_code
True

If you do not pass an endianness, and you pass some data, we will try to guess from the passed data.

>>> binblock3 = hdr3.binaryblock
>>> hdr4 = AnalyzeHeader(binblock3)
>>> hdr4.endianness == swapped_code
True
as_analyze_map()
data_from_fileobj(fileobj)

Read scaled data array from fileobj

Use this routine to get the scaled image data from an image file fileobj, given a header self. “Scaled” means, with any header scaling factors applied to the raw data in the file. Use raw_data_from_fileobj to get the raw data.

Parameters :

fileobj : file-like

Must be open, and implement read and seek methods

Returns :

arr : ndarray

scaled data array

Notes

We use the header to get any scale or intercept values to apply to the data. Raw Analyze files don’t have scale factors or intercepts, but this routine also works with formats based on Analyze, that do have scaling, such as SPM analyze formats and NIfTI.

data_to_fileobj(data, fileobj)

Write data to fileobj, maybe modifying self

In writing the data, we match the header to the written data, by setting the header scaling factors. Thus we modify self in the process of writing the data.

Parameters :

data : array-like

data to write; should match header defined shape

fileobj : file-like object

Object with file interface, implementing write and seek

Examples

>>> from nibabel.analyze import AnalyzeHeader
>>> hdr = AnalyzeHeader()
>>> hdr.set_data_shape((1, 2, 3))
>>> hdr.set_data_dtype(np.float64)
>>> from StringIO import StringIO #23dt : BytesIO
>>> str_io = StringIO() #23dt : BytesIO
>>> data = np.arange(6).reshape(1,2,3)
>>> hdr.data_to_fileobj(data, str_io)
>>> data.astype(np.float64).tostring('F') == str_io.getvalue()
True
classmethod default_structarr(klass, endianness=None)

Return header data for empty header with given endianness

default_x_flip = True
classmethod from_header(klass, header=None, check=True)

Class method to create header from another header

Parameters :

header : Header instance or mapping

a header of this class, or another class of header for conversion to this type

check : {True, False}

whether to check header for integrity

Returns :

hdr : header instance

fresh header instance of our own class

get_base_affine()

Get affine from basic (shared) header fields

Note that we get the translations from the center of the image.

Examples

>>> hdr = AnalyzeHeader()
>>> hdr.set_data_shape((3, 5, 7))
>>> hdr.set_zooms((3, 2, 1))
>>> hdr.default_x_flip
True
>>> hdr.get_base_affine() # from center of image
array([[-3.,  0.,  0.,  3.],
       [ 0.,  2.,  0., -4.],
       [ 0.,  0.,  1., -3.],
       [ 0.,  0.,  0.,  1.]])
get_best_affine()

Get affine from basic (shared) header fields

Note that we get the translations from the center of the image.

Examples

>>> hdr = AnalyzeHeader()
>>> hdr.set_data_shape((3, 5, 7))
>>> hdr.set_zooms((3, 2, 1))
>>> hdr.default_x_flip
True
>>> hdr.get_base_affine() # from center of image
array([[-3.,  0.,  0.,  3.],
       [ 0.,  2.,  0., -4.],
       [ 0.,  0.,  1., -3.],
       [ 0.,  0.,  0.,  1.]])
get_data_dtype()

Get numpy dtype for data

For examples see set_data_dtype

get_data_offset()

Return offset into data file to read data

Examples

>>> hdr = AnalyzeHeader()
>>> hdr.get_data_offset()
0
>>> hdr['vox_offset'] = 12
>>> hdr.get_data_offset()
12
get_data_shape()

Get shape of data

Examples

>>> hdr = AnalyzeHeader()
>>> hdr.get_data_shape()
(0,)
>>> hdr.set_data_shape((1,2,3))
>>> hdr.get_data_shape()
(1, 2, 3)

Expanding number of dimensions gets default zooms

>>> hdr.get_zooms()
(1.0, 1.0, 1.0)
get_slope_inter()

Get scalefactor and intercept

These are not implemented for basic Analyze

get_value_label(fieldname)

Returns label for coded field

A coded field is an int field containing codes that stand for discrete values that also have string labels.

Parameters :

fieldname : str

name of header field to get label for

Returns :

label : str

label for code value in header field fieldname

Raises :

ValueError : if field is not coded

Examples

>>> hdr = AnalyzeHeader()
>>> hdr.get_value_label('datatype')
'float32'
get_zooms()

Get zooms from header

Returns :

z : tuple

tuple of header zoom values

Examples

>>> hdr = AnalyzeHeader()
>>> hdr.get_zooms()
(1.0,)
>>> hdr.set_data_shape((1,2))
>>> hdr.get_zooms()
(1.0, 1.0)
>>> hdr.set_zooms((3, 4))
>>> hdr.get_zooms()
(3.0, 4.0)
classmethod guessed_endian(klass, hdr)

Guess intended endianness from mapping-like hdr

Parameters :

hdr : mapping-like

hdr for which to guess endianness

Returns :

endianness : {‘<’, ‘>’}

Guessed endianness of header

Examples

Zeros header, no information, guess native

>>> hdr = AnalyzeHeader()
>>> hdr_data = np.zeros((), dtype=header_dtype)
>>> AnalyzeHeader.guessed_endian(hdr_data) == native_code
True

A valid native header is guessed native

>>> hdr_data = hdr.structarr.copy()
>>> AnalyzeHeader.guessed_endian(hdr_data) == native_code
True

And, when swapped, is guessed as swapped

>>> sw_hdr_data = hdr_data.byteswap(swapped_code)
>>> AnalyzeHeader.guessed_endian(sw_hdr_data) == swapped_code
True

The algorithm is as follows:

First, look at the first value in the dim field; this should be between 0 and 7. If it is between 1 and 7, then this must be a native endian header.

>>> hdr_data = np.zeros((), dtype=header_dtype) # blank binary data
>>> hdr_data['dim'][0] = 1
>>> AnalyzeHeader.guessed_endian(hdr_data) == native_code
True
>>> hdr_data['dim'][0] = 6
>>> AnalyzeHeader.guessed_endian(hdr_data) == native_code
True
>>> hdr_data['dim'][0] = -1
>>> AnalyzeHeader.guessed_endian(hdr_data) == swapped_code
True

If the first dim value is zeros, we need a tie breaker. In that case we check the sizeof_hdr field. This should be 348. If it looks like the byteswapped value of 348, assumed swapped. Otherwise assume native.

>>> hdr_data = np.zeros((), dtype=header_dtype) # blank binary data
>>> AnalyzeHeader.guessed_endian(hdr_data) == native_code
True
>>> hdr_data['sizeof_hdr'] = 1543569408
>>> AnalyzeHeader.guessed_endian(hdr_data) == swapped_code
True
>>> hdr_data['sizeof_hdr'] = -1
>>> AnalyzeHeader.guessed_endian(hdr_data) == native_code
True

This is overridden by the ``dim``[0] value though:

>>> hdr_data['sizeof_hdr'] = 1543569408
>>> hdr_data['dim'][0] = 1
>>> AnalyzeHeader.guessed_endian(hdr_data) == native_code
True
has_data_intercept = False
has_data_slope = False
raw_data_from_fileobj(fileobj)

Read unscaled data array from fileobj

Parameters :

fileobj : file-like

Must be open, and implement read and seek methods

Returns :

arr : ndarray

unscaled data array

set_data_dtype(datatype)

Set numpy dtype for data from code or dtype or type

Examples

>>> hdr = AnalyzeHeader()
>>> hdr.set_data_dtype(np.uint8)
>>> hdr.get_data_dtype()
dtype('uint8')
>>> hdr.set_data_dtype(np.dtype(np.uint8))
>>> hdr.get_data_dtype()
dtype('uint8')
>>> hdr.set_data_dtype('implausible') 
Traceback (most recent call last):
   ...
HeaderDataError: data dtype "implausible" not recognized
>>> hdr.set_data_dtype('none') 
Traceback (most recent call last):
   ...
HeaderDataError: data dtype "none" known but not supported
>>> hdr.set_data_dtype(np.void) 
Traceback (most recent call last):
   ...
HeaderDataError: data dtype "<type 'numpy.void'>" known but not supported
set_data_shape(shape)

Set shape of data

If ndims == len(shape) then we set zooms for dimensions higher than ndims to 1.0

Parameters :

shape : sequence

sequence of integers specifying data array shape

set_slope_inter(slope, inter=None)

Set slope and / or intercept into header

Set slope and intercept for image data, such that, if the image data is arr, then the scaled image data will be (arr * slope) + inter

In this case, for Analyze images, we can’t store the slope or the intercept, so this method only checks that slope is None or 1.0, and that inter is None or 0.

Parameters :

slope : None or float

If float, value must be 1.0 or we raise a HeaderTypeError

inter : None or float, optional

If float, value must be 0.0 or we raise a HeaderTypeError

set_zooms(zooms)

Set zooms into header fields

See docstring for get_zooms for examples

template_dtype = dtype([('sizeof_hdr', '<i4'), ('data_type', 'S10'), ('db_name', 'S18'), ('extents', '<i4'), ('session_error', '<i2'), ('regular', 'S1'), ('hkey_un0', 'S1'), ('dim', '<i2', (8,)), ('vox_units', 'S4'), ('cal_units', 'S8'), ('unused1', '<i2'), ('datatype', '<i2'), ('bitpix', '<i2'), ('dim_un0', '<i2'), ('pixdim', '<f4', (8,)), ('vox_offset', '<f4'), ('funused1', '<f4'), ('funused2', '<f4'), ('funused3', '<f4'), ('cal_max', '<f4'), ('cal_min', '<f4'), ('compressed', '<i4'), ('verified', '<i4'), ('glmax', '<i4'), ('glmin', '<i4'), ('descrip', 'S80'), ('aux_file', 'S24'), ('orient', 'S1'), ('originator', 'S10'), ('generated', 'S10'), ('scannum', 'S10'), ('patient_id', 'S10'), ('exp_date', 'S10'), ('exp_time', 'S10'), ('hist_un0', 'S3'), ('views', '<i4'), ('vols_added', '<i4'), ('start_field', '<i4'), ('field_skip', '<i4'), ('omax', '<i4'), ('omin', '<i4'), ('smax', '<i4'), ('smin', '<i4')])