NiBabel

Access a cacophony of neuro-imaging file formats

Previous topic

nibabel.nifti1.Nifti1Extensions

Next topic

nibabel.nifti1.Nifti1Image

Reggie -- the one

nibabel.nifti1.Nifti1Header

digraph inheritance81c29cf437 { rankdir=LR; ratio=compress; fontsize=14; size="6.0, 8.0"; "AnalyzeHeader" [shape=ellipse,URL="nibabel.analyze.AnalyzeHeader.html#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)"]; "WrapStruct" [shape=ellipse,fontname=Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans,fontsize=14,color=dodgerblue1,style=filled,height=0.75]; "SpmAnalyzeHeader" [shape=ellipse,URL="nibabel.spm99analyze.SpmAnalyzeHeader.html#nibabel.spm99analyze.SpmAnalyzeHeader",fontname=Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans,fontsize=14,color=dodgerblue1,style=filled,height=0.75]; "AnalyzeHeader" -> "SpmAnalyzeHeader" [arrowsize=0.5,style="setlinewidth(0.5)"]; "Nifti1Header" [shape=ellipse,URL="#nibabel.nifti1.Nifti1Header",fontname=Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans,fontsize=14,color=dodgerblue1,style=filled,height=0.75]; "SpmAnalyzeHeader" -> "Nifti1Header" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

class nibabel.nifti1.Nifti1Header(binaryblock=None, endianness=None, check=True, extensions=())

Class for NIFTI1 header

The NIFTI1 header has many more coded fields than the simpler Analyze variants. Nifti1 headers also have extensions.

Nifti allows the header to be a separate file, as part of a nifti image / header pair, or to precede the data in a single file. The object needs to know which type it is, in order to manage the voxel offset pointing to the data, extension reading, and writing the correct magic string.

This class handles the header-preceding-data case.

Initialize header from binary data block and extensions

copy()

Return copy of header

Take reference to extensions as well as copy of header contents

classmethod default_structarr(klass, endianness=None)

Create empty header binary block with given endianness

exts_klass

alias of Nifti1Extensions

classmethod from_fileobj(klass, fileobj, endianness=None, check=True)
get_best_affine()

Select best of available transforms

get_data_shape()

Get shape of data

Notes

Allows for freesurfer hack for large vectors described in https://github.com/nipy/nibabel/issues/100 and http://code.google.com/p/fieldtrip/source/browse/trunk/external/freesurfer/save_nifti.m?spec=svn5022&r=5022#77

Examples

>>> hdr = Nifti1Header()
>>> 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_dim_info()

Gets nifti MRI slice etc dimension information

Returns :

freq : {None,0,1,2}

Which data array axis is freqency encode direction

phase : {None,0,1,2}

Which data array axis is phase encode direction

slice : {None,0,1,2}

Which data array axis is slice encode direction

where ``data array`` is the array returned by ``get_data`` :

Because nifti1 files are natively Fortran indexed: :

0 is fastest changing in file 1 is medium changing in file 2 is slowest changing in file

``None`` means the axis appears not to be specified. :

Examples

See set_dim_info function

get_intent(code_repr='label')

Get intent code, parameters and name

Parameters :

code_repr : string

string giving output form of intent code representation. Default is ‘label’; use ‘code’ for integer representation.

Returns :

code : string or integer

intent code, or string describing code

parameters : tuple

parameters for the intent

name : string

intent name

Examples

>>> hdr = Nifti1Header()
>>> hdr.set_intent('t test', (10,), name='some score')
>>> hdr.get_intent()
('t test', (10.0,), 'some score')
>>> hdr.get_intent('code')
(3, (10.0,), 'some score')
get_n_slices()

Return the number of slices

get_qform(coded=False)

Return 4x4 affine matrix from qform parameters in header

Parameters :

coded : bool, optional

If True, return {affine or None}, and qform code. If False, just return affine. {affine or None} means, return None if qform code == 0, and affine otherwise.

Returns :

affine : None or (4,4) ndarray

If coded is False, always return affine reconstructed from qform quaternion. If coded is True, return None if qform code is 0, else return the affine.

code : int

Qform code. Only returned if coded is True.

get_qform_quaternion()

Compute quaternion from b, c, d of quaternion

Fills a value by assuming this is a unit quaternion

get_sform(coded=False)

Return 4x4 affine matrix from sform parameters in header

Parameters :

coded : bool, optional

If True, return {affine or None}, and sform code. If False, just return affine. {affine or None} means, return None if sform code == 0, and affine otherwise.

Returns :

affine : None or (4,4) ndarray

If coded is False, always return affine from sform fields. If coded is True, return None if sform code is 0, else return the affine.

code : int

Sform code. Only returned if coded is True.

get_slice_duration()

Get slice duration

Returns :

slice_duration : float

time to acquire one slice

Notes

The Nifti1 spec appears to require the slice dimension to be defined for slice_duration to have meaning.

Examples

>>> hdr = Nifti1Header()
>>> hdr.set_dim_info(slice=2)
>>> hdr.set_slice_duration(0.3)
>>> print "%0.1f" % hdr.get_slice_duration()
0.3
get_slice_times()

Get slice times from slice timing information

Returns :

slice_times : tuple

Times of acquisition of slices, where 0 is the beginning of the acquisition, ordered by position in file. nifti allows slices at the top and bottom of the volume to be excluded from the standard slice timing specification, and calls these “padding slices”. We give padding slices None as a time of acquisition

Examples

>>> hdr = Nifti1Header()
>>> hdr.set_dim_info(slice=2)
>>> hdr.set_data_shape((1, 1, 7))
>>> hdr.set_slice_duration(0.1)
>>> hdr['slice_code'] = slice_order_codes['sequential increasing']
>>> slice_times = hdr.get_slice_times()
>>> np.allclose(slice_times, [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6])
True
get_slope_inter()

Get data scaling (slope) and DC offset (intercept) from header data

Parameters :

self : header object

Should have fields (keys) * scl_slope - slope * scl_inter - intercept

Returns :

slope : None or float

scaling (slope). None if there is no valid scaling from these fields

inter : None or float

offset (intercept). None if there is no valid scaling or if offset is not finite.

Examples

>>> hdr = Nifti1Header()
>>> hdr.get_slope_inter()
(1.0, 0.0)
>>> hdr['scl_slope'] = 0
>>> hdr.get_slope_inter()
(None, None)
>>> hdr['scl_slope'] = np.nan
>>> hdr.get_slope_inter()
(None, None)
>>> hdr['scl_slope'] = 1
>>> hdr['scl_inter'] = 1
>>> hdr.get_slope_inter()
(1.0, 1.0)
>>> hdr['scl_inter'] = np.inf
>>> hdr.get_slope_inter()
(1.0, None)
get_xyzt_units()
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

Notes

Applies freesurfer hack for large vectors described in https://github.com/nipy/nibabel/issues/100 and http://code.google.com/p/fieldtrip/source/browse/trunk/external/freesurfer/save_nifti.m?spec=svn5022&r=5022#77

set_dim_info(freq=None, phase=None, slice=None)

Sets nifti MRI slice etc dimension information

Parameters :

hdr : nifti1 header

freq : {None, 0, 1, 2}

axis of data array refering to freqency encoding

phase : {None, 0, 1, 2}

axis of data array refering to phase encoding

slice : {None, 0, 1, 2}

axis of data array refering to slice encoding

``None`` means the axis is not specified. :

Notes

This is stored in one byte in the header

Examples

>>> hdr = Nifti1Header()
>>> hdr.set_dim_info(1, 2, 0)
>>> hdr.get_dim_info()
(1, 2, 0)
>>> hdr.set_dim_info(freq=1, phase=2, slice=0)
>>> hdr.get_dim_info()
(1, 2, 0)
>>> hdr.set_dim_info()
>>> hdr.get_dim_info()
(None, None, None)
>>> hdr.set_dim_info(freq=1, phase=None, slice=0)
>>> hdr.get_dim_info()
(1, None, 0)
set_intent(code, params=(), name='')

Set the intent code, parameters and name

If parameters are not specified, assumed to be all zero. Each intent code has a set number of parameters associated. If you specify any parameters, then it will need to be the correct number (e.g the “f test” intent requires 2). However, parameters can also be set in the file data, so we also allow not setting any parameters (empty parameter tuple).

Parameters :

code : integer or string

code specifying nifti intent

params : list, tuple of scalars

parameters relating to intent (see intent_codes) defaults to (). Unspecified parameters are set to 0.0

name : string

intent name (description). Defaults to ‘’

Returns :

None :

Examples

>>> hdr = Nifti1Header()
>>> hdr.set_intent(0) # unknown code
>>> hdr.set_intent('z score')
>>> hdr.get_intent()
('z score', (), '')
>>> hdr.get_intent('code')
(5, (), '')
>>> hdr.set_intent('t test', (10,), name='some score')
>>> hdr.get_intent()
('t test', (10.0,), 'some score')
>>> hdr.set_intent('f test', (2, 10), name='another score')
>>> hdr.get_intent()
('f test', (2.0, 10.0), 'another score')
>>> hdr.set_intent('f test')
>>> hdr.get_intent()
('f test', (0.0, 0.0), '')
set_qform(affine, code=None, strip_shears=True)

Set qform header values from 4x4 affine

Parameters :

hdr : nifti1 header

affine : None or 4x4 array

affine transform to write into sform. If None, only set code.

code : None, string or integer

String or integer giving meaning of transform in affine. The default is None. If code is None, then: * If affine is None, code-> 0 * If affine not None and sform code in header == 0, code-> 2

(aligned)

  • If affine not None and sform code in header != 0, code-> sform code in header

strip_shears : bool, optional

Whether to strip shears in affine. If True, shears will be silently stripped. If False, the presence of shears will raise a HeaderDataError

Notes

The qform transform only encodes translations, rotations and zooms. If there are shear components to the affine transform, and strip_shears is True (the default), the written qform gives the closest approximation where the rotation matrix is orthogonal. This is to allow quaternion representation. The orthogonal representation enforces orthogonal axes.

Examples

>>> hdr = Nifti1Header()
>>> int(hdr['qform_code']) # gives 0 - unknown
0
>>> affine = np.diag([1,2,3,1])
>>> np.all(hdr.get_qform() == affine)
False
>>> hdr.set_qform(affine)
>>> np.all(hdr.get_qform() == affine)
True
>>> int(hdr['qform_code']) # gives 2 - aligned
2
>>> hdr.set_qform(affine, code='talairach')
>>> int(hdr['qform_code'])
3
>>> hdr.set_qform(affine, code=None)
>>> int(hdr['qform_code'])
3
>>> hdr.set_qform(affine, code='scanner')
>>> int(hdr['qform_code'])
1
>>> hdr.set_qform(None)
>>> int(hdr['qform_code'])
0
set_sform(affine, code=None)

Set sform transform from 4x4 affine

Parameters :

hdr : nifti1 header

affine : None or 4x4 array

affine transform to write into sform. If None, only set code

code : None, string or integer

String or integer giving meaning of transform in affine. The default is None. If code is None, then: * If affine is None, code-> 0 * If affine not None and sform code in header == 0, code-> 2

(aligned)

  • If affine not None and sform code in header != 0, code-> sform code in header

Examples

>>> hdr = Nifti1Header()
>>> int(hdr['sform_code']) # gives 0 - unknown
0
>>> affine = np.diag([1,2,3,1])
>>> np.all(hdr.get_sform() == affine)
False
>>> hdr.set_sform(affine)
>>> np.all(hdr.get_sform() == affine)
True
>>> int(hdr['sform_code']) # gives 2 - aligned
2
>>> hdr.set_sform(affine, code='talairach')
>>> int(hdr['sform_code'])
3
>>> hdr.set_sform(affine, code=None)
>>> int(hdr['sform_code'])
3
>>> hdr.set_sform(affine, code='scanner')
>>> int(hdr['sform_code'])
1
>>> hdr.set_sform(None)
>>> int(hdr['sform_code'])
0
set_slice_duration(duration)

Set slice duration

Parameters :

duration : scalar

time to acquire one slice

Examples

See get_slice_duration

set_slice_times(slice_times)

Set slice times into hdr

Parameters :

slice_times : tuple

tuple of slice times, one value per slice tuple can include None to indicate no slice time for that slice

Examples

>>> hdr = Nifti1Header()
>>> hdr.set_dim_info(slice=2)
>>> hdr.set_data_shape([1, 1, 7])
>>> hdr.set_slice_duration(0.1)
>>> times = [None, 0.2, 0.4, 0.1, 0.3, 0.0, None]
>>> hdr.set_slice_times(times)
>>> hdr.get_value_label('slice_code')
'alternating decreasing'
>>> int(hdr['slice_start'])
1
>>> int(hdr['slice_end'])
5
set_slope_inter(slope, inter=0.0)

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

Parameters :

slope : None or float

If None, implies slope of 0. When the slope is set to 0 or a not-finite value, get_slope_inter returns (None, None), i.e. inter is ignored unless there is a valid value for slope.

inter : None or float, optional

intercept. None implies inter value of 0.

set_xyzt_units(xyz=None, t=None)
write_to(fileobj)