nibabel.wrapstruct

Class to wrap numpy structured array

wrapstruct

The WrapStruct class is a wrapper around a numpy structured array type.

It implements:

  • Mappingness from the underlying structured array fields

  • from_fileobj, write_to methods to read and write data to fileobj

  • A mechanism for setting checks and fixes to the data on object creation

  • Endianness guessing, and on-the-fly swapping

The LabeledWrapStruct subclass adds:

  • A pretty printing mechanism whereby field values can be displayed as corresponding strings (see LabeledWrapStruct.get_value_label() and LabeledWrapStruct.__str_())

Mappingness

You can access and set fields of the contained structarr using standard __getitem__ / __setitem__ syntax:

wrapped[‘field’] = 10

Wrapped structures also implement general mappingness:

wrapped.keys() wrapped.items() wrapped.values()

Properties:

.endianness (read only)
.binaryblock (read only)
.structarr (read only)

Methods:

.as_byteswapped(endianness)
.check_fix()
.__str__
.__eq__
.__ne__
.get_value_label(name)

Class methods:

.diagnose_binaryblock
.as_byteswapped(endianness)
.write_to(fileobj)
.from_fileobj(fileobj)
.default_structarr() - return default structured array
.guessed_endian(structarr) - return guessed endian code from this structarr
Class variables:

template_dtype - native endian version of dtype for contained structarr

Consistency checks

We have a file, and we would like information as to whether there are any problems with the binary data in this file, and whether they are fixable. WrapStruct can hold checks for internal consistency of the contained data:

wrapped = WrapStruct.from_fileobj(open('myfile.bin'), check=False)
dx_result = WrapStruct.diagnose_binaryblock(wrapped.binaryblock)

This will run all known checks, with no fixes, returning a string with diagnostic output. See below for the check=False flag.

In creating a WrapStruct object, we often want to check the consistency of the contained data. The checks can test for problems of various levels of severity. If the problem is severe enough, it should raise an Error. So, with data that is consistent - no error:

wrapped = WrapStruct.from_fileobj(good_fileobj)

whereas:

wrapped = WrapStruct.from_fileobj(bad_fileobj)

would raise some error, with output to logging (see below).

If we want the created object, come what may:

hdr = WrapStruct.from_fileobj(bad_fileobj, check=False)

We set the error level (the level of problem that the check=True versions will accept as OK) from global defaults:

import nibabel as nib
nib.imageglobals.error_level = 30

The same for logging:

nib.imageglobals.logger = logger

Classes

LabeledWrapStruct([binaryblock, endianness, ...])

A WrapStruct with some fields having value labels for printing etc

WrapStruct([binaryblock, endianness, check])

Initialize WrapStruct from binary data block

Exceptions

WrapStructError