gifti

GIfTI format IO

giftiio

gifti

Classes defining Gifti objects

Module: gifti.gifti

Classes defining Gifti objects

The Gifti specification was (at time of writing) available as a PDF download from http://www.nitrc.org/projects/gifti/

GiftiCoordSystem([dataspace, xformspace, xform])

Gifti coordinate system transform matrix

GiftiDataArray([data, intent, datatype, …])

Container for Gifti numerical data array and associated metadata

GiftiImage([header, extra, file_map, meta, …])

GIFTI image object

GiftiLabel([key, red, green, blue, alpha])

Gifti label: association of integer key with optional RGBA values

GiftiLabelTable()

Gifti label table: a sequence of key, label pairs

GiftiMetaData([nvpair])

A sequence of GiftiNVPairs containing metadata for a gifti data array

GiftiNVPairs([name, value])

Gifti name / value pairs

data_tag(dataarray, encoding, datatype, ordering)

data_tag is an internal API that will be discontinued.

Module: gifti.giftiio

read(filename)

Load a Gifti image from a file

write(image, filename)

Save the current image to a new file

Module: gifti.parse_gifti_fast

GiftiImageParser([encoding, buffer_size, …])

GiftiParseError

Gifti-specific parsing error

Outputter()

Outputter class deprecated.

parse_gifti_file([fname, fptr, buffer_size])

parse_gifti_file deprecated.

read_data_block(encoding, endian, ordering, …)

Tries to unzip, decode, parse the funny string data

Module: gifti.util

GiftiCoordSystem

class nibabel.gifti.gifti.GiftiCoordSystem(dataspace=0, xformspace=0, xform=None)

Bases: nibabel.xmlutils.XmlSerializable

Gifti coordinate system transform matrix

Quotes are from the gifti spec dated 2011-01-14.

“For a DataArray with an Intent NIFTI_INTENT_POINTSET, this element describes the stereotaxic space of the data before and after the application of a transformation matrix. The most common stereotaxic space is the Talairach Space that places the origin at the anterior commissure and the negative X, Y, and Z axes correspond to left, posterior, and inferior respectively. At least one CoordinateSystemTransformMatrix is required in a DataArray with an intent of NIFTI_INTENT_POINTSET. Multiple CoordinateSystemTransformMatrix elements may be used to describe the transformation to multiple spaces.”

Attributes
dataspaceint

From the spec: “Contains the stereotaxic space of a DataArray’s data prior to application of the transformation matrix. The stereotaxic space should be one of:

NIFTI_XFORM_UNKNOWN NIFTI_XFORM_SCANNER_ANAT NIFTI_XFORM_ALIGNED_ANAT NIFTI_XFORM_TALAIRACH NIFTI_XFORM_MNI_152”

xformspaceint

Spec: “Contains the stereotaxic space of a DataArray’s data after application of the transformation matrix. See the DataSpace element for a list of stereotaxic spaces.”

xformarray-like shape (4, 4)

Affine transformation matrix

__init__(dataspace=0, xformspace=0, xform=None)

Initialize self. See help(type(self)) for accurate signature.

print_summary()

GiftiDataArray

class nibabel.gifti.gifti.GiftiDataArray(data=None, intent='NIFTI_INTENT_NONE', datatype=None, encoding='GIFTI_ENCODING_B64GZ', endian='little', coordsys=None, ordering='C', meta=None, ext_fname='', ext_offset=0)

Bases: nibabel.xmlutils.XmlSerializable

Container for Gifti numerical data array and associated metadata

Quotes are from the gifti spec dated 2011-01-14.

Description of DataArray in spec:

“This element contains the numeric data and its related metadata. The CoordinateSystemTransformMatrix child is only used when the DataArray’s Intent is NIFTI_INTENT_POINTSET. FileName and FileOffset are required if the data is stored in an external file.”

Attributes
darrayNone or ndarray

Data array

intentint

NIFTI intent code, see nifti1.intent_codes

datatypeint

NIFTI data type codes, see nifti1.data_type_codes. From the spec: “This required attribute describes the numeric type of the data contained in a Data Array and are limited to the types displayed in the table:

NIFTI_TYPE_UINT8 : Unsigned, 8-bit bytes. NIFTI_TYPE_INT32 : Signed, 32-bit integers. NIFTI_TYPE_FLOAT32 : 32-bit single precision floating point.”

At the moment, we do not enforce that the datatype is one of these three.

encodingstring

Encoding of the data, see util.gifti_encoding_codes; default is GIFTI_ENCODING_B64GZ.

endianstring

The Endianness to store the data array. Should correspond to the machine endianness. Default is system byteorder.

coordsysGiftiCoordSystem instance

Input and output coordinate system with tranformation matrix between the two.

ind_ordint

The ordering of the array. see util.array_index_order_codes. Default is RowMajorOrder - C ordering

metaGiftiMetaData instance

An instance equivalent to a dictionary for metadata information.

ext_fnamestr

Filename in which data is stored, or empty string if no corresponding filename.

ext_offsetint

Position in bytes within ext_fname at which to start reading data.

Returns a shell object that cannot be saved.

__init__(data=None, intent='NIFTI_INTENT_NONE', datatype=None, encoding='GIFTI_ENCODING_B64GZ', endian='little', coordsys=None, ordering='C', meta=None, ext_fname='', ext_offset=0)

Returns a shell object that cannot be saved.

classmethod from_array(darray, intent='NIFTI_INTENT_NONE', datatype=None, encoding='GIFTI_ENCODING_B64GZ', endian='little', coordsys=None, ordering='C', meta=None)

Creates a new Gifti data array

from_array method is deprecated. Please use GiftiDataArray constructor instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

Parameters
darrayndarray

NumPy data array

intentstring

NIFTI intent code, see nifti1.intent_codes

datatypeNone or string, optional

NIFTI data type codes, see nifti1.data_type_codes If None, the datatype of the NumPy array is taken.

encodingstring, optionaal

Encoding of the data, see util.gifti_encoding_codes; default: GIFTI_ENCODING_B64GZ

endianstring, optional

The Endianness to store the data array. Should correspond to the machine endianness. default: system byteorder

coordsysGiftiCoordSystem, optional

If None, a identity transformation is taken.

orderingstring, optional

The ordering of the array. see util.array_index_order_codes; default: RowMajorOrder - C ordering

metaNone or dict, optional

A dictionary for metadata information. If None, gives empty dict.

Returns
dainstance of our own class
get_metadata()

get_metadata method deprecated. Use the metadata property instead.2.1

  • deprecated from version: 4.0

metadata

Returns metadata as dictionary

num_dim
print_summary()
to_xml_close()

to_xml_close method deprecated. Use the to_xml() function instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

to_xml_open()

to_xml_open method deprecated. Use the to_xml() function instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

GiftiImage

class nibabel.gifti.gifti.GiftiImage(header=None, extra=None, file_map=None, meta=None, labeltable=None, darrays=None, version='1.0')

Bases: nibabel.xmlutils.XmlSerializable, nibabel.filebasedimages.SerializableImage

GIFTI image object

The Gifti spec suggests using the following suffixes to your filename when saving each specific type of data:

.gii

Generic GIFTI File

.coord.gii

Coordinates

.func.gii

Functional

.label.gii

Labels

.rgba.gii

RGB or RGBA

.shape.gii

Shape

.surf.gii

Surface

.tensor.gii

Tensors

.time.gii

Time Series

.topo.gii

Topology

The Gifti file is stored in endian convention of the current machine.

__init__(header=None, extra=None, file_map=None, meta=None, labeltable=None, darrays=None, version='1.0')

Initialize self. See help(type(self)) for accurate signature.

add_gifti_data_array(dataarr)

Adds a data array to the GiftiImage

Parameters
dataarrGiftiDataArray instance
files_types = (('image', '.gii'),)
classmethod from_file_map(file_map, buffer_size=35000000)

Load a Gifti image from a file_map

Parameters
file_mapdict

Dictionary with single key image with associated value which is a FileHolder instance pointing to the image file.

Returns
imgGiftiImage
classmethod from_filename(filename, buffer_size=35000000)
getArraysFromIntent(intent)

getArraysFromIntent method deprecated. Use get_arrays_from_intent instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

get_arrays_from_intent(intent)

Return list of GiftiDataArray elements matching given intent

get_labeltable()

get_labeltable method deprecated. Use the gifti_img.labeltable property instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

get_meta()

get_meta method deprecated. Use the gifti_img.meta property instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

labeltable
meta
numDA
parser

alias of nibabel.gifti.parse_gifti_fast.GiftiImageParser

print_summary()
remove_gifti_data_array(ith)

Removes the ith data array element from the GiftiImage

remove_gifti_data_array_by_intent(intent)

Removes all the data arrays with the given intent type

set_labeltable(labeltable)

set_labeltable method deprecated. Use the gifti_img.labeltable property instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

set_metadata(meta)

set_meta method deprecated. Use the gifti_img.meta property instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

to_bytes(enc='utf-8')

Return XML corresponding to image content

to_file_map(file_map=None)

Save the current image to the specified file_map

Parameters
file_mapdict

Dictionary with single key image with associated value which is a FileHolder instance pointing to the image file.

Returns
None
to_xml(enc='utf-8')

Return XML corresponding to image content

valid_exts = ('.gii',)

GiftiLabel

class nibabel.gifti.gifti.GiftiLabel(key=0, red=None, green=None, blue=None, alpha=None)

Bases: nibabel.xmlutils.XmlSerializable

Gifti label: association of integer key with optional RGBA values

Quotes are from the gifti spec dated 2011-01-14.

Notes

freesurfer examples seem not to conform to datatype “NIFTI_TYPE_RGBA32” because they are floats, not 4 8-bit integers.

Attributes
keyint

(From the spec): “This required attribute contains a non-negative integer value. If a DataArray’s Intent is NIFTI_INTENT_LABEL and a value in the DataArray is ‘X’, its corresponding label is the label with the Key attribute containing the value ‘X’. In early versions of the GIFTI file format, the attribute Index was used instead of Key. If an Index attribute is encountered, it should be processed like the Key attribute.”

redNone or float

Optional value for red.

greenNone or float

Optional value for green.

blueNone or float

Optional value for blue.

alphaNone or float

Optional value for alpha.

__init__(key=0, red=None, green=None, blue=None, alpha=None)

Initialize self. See help(type(self)) for accurate signature.

get_rgba()

get_rgba method deprecated. Use the rgba property instead.2.1

  • deprecated from version: 4.0

rgba

Returns RGBA as tuple

GiftiLabelTable

class nibabel.gifti.gifti.GiftiLabelTable

Bases: nibabel.xmlutils.XmlSerializable

Gifti label table: a sequence of key, label pairs

From the gifti spec dated 2011-01-14:

The label table is used by DataArrays whose values are an key into the LabelTable’s labels. A file should contain at most one LabelTable and it must be located in the file prior to any DataArray elements.

__init__()

Initialize self. See help(type(self)) for accurate signature.

get_labels_as_dict()
print_summary()

GiftiMetaData

class nibabel.gifti.gifti.GiftiMetaData(nvpair=None)

Bases: nibabel.xmlutils.XmlSerializable

A sequence of GiftiNVPairs containing metadata for a gifti data array

__init__(nvpair=None)

Initialize self. See help(type(self)) for accurate signature.

classmethod from_dict(data_dict)
get_metadata()

get_metadata method deprecated. Use the metadata property instead.2.1

  • deprecated from version: 4.0

metadata

Returns metadata as dictionary

print_summary()

GiftiNVPairs

class nibabel.gifti.gifti.GiftiNVPairs(name='', value='')

Bases: object

Gifti name / value pairs

Attributes
namestr
valuestr
__init__(name='', value='')

Initialize self. See help(type(self)) for accurate signature.

data_tag

nibabel.gifti.gifti.data_tag(dataarray, encoding, datatype, ordering)

data_tag is an internal API that will be discontinued.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

read

nibabel.gifti.giftiio.read(filename)

Load a Gifti image from a file

giftiio.read function deprecated. Use nibabel.load() instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

Parameters
filenamestring

The Gifti file to open, it has usually ending .gii

Returns
imgGiftiImage

Returns a GiftiImage

write

nibabel.gifti.giftiio.write(image, filename)

Save the current image to a new file

giftiio.write function deprecated. Use nibabel.load() instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

Parameters
imageGiftiImage

A GiftiImage instance to store

filenamestring

Filename to store the Gifti file to

Returns
None

Notes

We write all files with utf-8 encoding, and specify this at the top of the XML file with the encoding attribute.

The Gifti spec suggests using the following suffixes to your filename when saving each specific type of data:

.gii

Generic GIFTI File

.coord.gii

Coordinates

.func.gii

Functional

.label.gii

Labels

.rgba.gii

RGB or RGBA

.shape.gii

Shape

.surf.gii

Surface

.tensor.gii

Tensors

.time.gii

Time Series

.topo.gii

Topology

The Gifti file is stored in endian convention of the current machine.

GiftiImageParser

class nibabel.gifti.parse_gifti_fast.GiftiImageParser(encoding=None, buffer_size=35000000, verbose=0)

Bases: nibabel.xmlutils.XmlParser

__init__(encoding=None, buffer_size=35000000, verbose=0)
Parameters
encodingstr

string containing xml document

buffer_size: None or int, optional

size of read buffer. None uses default buffer_size from xml.parsers.expat.

verboseint, optional

amount of output during parsing (0=silent, by default).

CharacterDataHandler(data)

Collect character data chunks pending collation

The parser breaks the data up into chunks of size depending on the buffer_size of the parser. A large bit of character data, with standard parser buffer_size (such as 8K) can easily span many calls to this function. We thus collect the chunks and process them when we hit start or end tags.

EndElementHandler(name)
StartElementHandler(name, attrs)
flush_chardata()

Collate and process collected character data

pending_data

True if there is character data pending for processing

GiftiParseError

class nibabel.gifti.parse_gifti_fast.GiftiParseError

Bases: xml.parsers.expat.ExpatError

Gifti-specific parsing error

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

Outputter

class nibabel.gifti.parse_gifti_fast.Outputter

Bases: nibabel.gifti.parse_gifti_fast.GiftiImageParser

Outputter class deprecated. Use GiftiImageParser instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

__init__()

Outputter class deprecated. Use GiftiImageParser instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

initialize()

Initialize outputter

parse_gifti_file

nibabel.gifti.parse_gifti_fast.parse_gifti_file(fname=None, fptr=None, buffer_size=None)

parse_gifti_file deprecated. Use GiftiImageParser.parse() instead.

  • deprecated from version: 2.1

  • Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

read_data_block

nibabel.gifti.parse_gifti_fast.read_data_block(encoding, endian, ordering, datatype, shape, data)

Tries to unzip, decode, parse the funny string data