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"; "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]; }

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()
as_byteswapped(endianness=None)

return new byteswapped header object with given endianness

Guaranteed to make a copy even if endianness is the same as the current endianness.

Parameters :

endianness : None or string, optional

endian code to which to swap. None means swap from current endianness, and is the default

Returns :

hdr : header object

hdr object with given endianness

Examples

>>> hdr = AnalyzeHeader()
>>> hdr.endianness == native_code
True
>>> bs_hdr = hdr.as_byteswapped()
>>> bs_hdr.endianness == swapped_code
True
>>> bs_hdr = hdr.as_byteswapped(swapped_code)
>>> bs_hdr.endianness == swapped_code
True
>>> bs_hdr is hdr
False
>>> bs_hdr == hdr
True

If you write to the resulting byteswapped data, it does not change the original.

>>> bs_hdr['dim'][1] = 2
>>> bs_hdr == hdr
False

If you swap to the same endianness, it returns a copy

>>> nbs_hdr = hdr.as_byteswapped(native_code)
>>> nbs_hdr.endianness == native_code
True
>>> nbs_hdr is hdr
False
binaryblock

binary block of data as string

Returns :

binaryblock : string

string giving binary data block

Examples

>>> # Make default empty header
>>> hdr = AnalyzeHeader()
>>> len(hdr.binaryblock)
348
check_fix(logger=None, error_level=None)

Check header data with checks

copy()

Return copy of header

>>> hdr = AnalyzeHeader()
>>> hdr['dim'][0]
0
>>> hdr['dim'][0] = 2
>>> hdr2 = hdr.copy()
>>> hdr2 is hdr
False
>>> hdr['dim'][0] = 3
>>> hdr2['dim'][0]
2
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 diagnose_binaryblock(klass, binaryblock, endianness=None)

Run checks over header binary data, return string

endianness

endian code of binary data

The endianness code gives the current byte order interpretation of the binary data.

Notes

Endianness gives endian interpretation of binary data. It is read only because the only common use case is to set the endianness on initialization, or occasionally byteswapping the data - but this is done via the as_byteswapped method

Examples

>>> hdr = AnalyzeHeader()
>>> code = hdr.endianness
>>> code == native_code
True
classmethod from_fileobj(klass, fileobj, endianness=None, check=True)

Return read header with given or guessed endiancode

Parameters :

fileobj : file-like object

Needs to implement read method

endianness : None or endian code, optional

Code specifying endianness of read data

Returns :

hdr : AnalyzeHeader object

AnalyzeHeader object initialized from data in fileobj

Examples

>>> from StringIO import StringIO #23dt : BytesIO
>>> hdr = AnalyzeHeader()
>>> fileobj = StringIO(hdr.binaryblock) #23dt : BytesIO
>>> _ = fileobj.seek(0) # returns 0 in python 3
>>> hdr2 = AnalyzeHeader.from_fileobj(fileobj)
>>> hdr2.binaryblock == hdr.binaryblock
True

You can write to the resulting object data

>>> hdr2['dim'][1] = 1
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

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)
items()

Return items from header data

keys()

Return keys from header data

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

scaling_from_data(data)

Calculate slope, intercept, min, max from data given header

Check that the data can be sensibly adapted to this header data dtype. If the header type does support useful scaling to allow this, raise a HeaderTypeError.

Parameters :

data : array-like

array of data for which to calculate scaling etc

Returns :

divslope : None or scalar

divisor for data, after subtracting intercept. If None, then there are no valid data

intercept : None or scalar

number to subtract from data before writing.

mn : None or scalar

data minimum to write, None means use data minimum

mx : None or scalar

data maximum to write, None means use data maximum

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

structarr

header data, with data fields

Examples

>>> hdr1 = AnalyzeHeader() # an empty header
>>> sz = hdr1.structarr['sizeof_hdr']
>>> hdr1.structarr = None
Traceback (most recent call last):
   ...
AttributeError: can't set attribute
values()

Return values from header data

write_to(fileobj)

Write header to fileobj

Write starts at fileobj current file position.

Parameters :

fileobj : file-like object

Should implement write method

Returns :

None :

Examples

>>> hdr = AnalyzeHeader()
>>> from StringIO import StringIO #23dt : BytesIO
>>> str_io = StringIO() #23dt : BytesIO
>>> hdr.write_to(str_io)
>>> hdr.binaryblock == str_io.getvalue()
True