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 (\*args, \*\*kwargs) |
data_tag is an internal API that will be discontinued. |
Module: gifti.giftiio
¶
read (\*args, \*\*kwargs) |
Load a Gifti image from a file |
write (\*args, \*\*kwargs) |
Save the current image to a new file |
Module: gifti.parse_gifti_fast
¶
GiftiImageParser ([encoding, buffer_size, ...]) |
|
GiftiParseError |
Gifti-specific parsing error |
Outputter (\*args, \*\*kwargs) |
Outputter class deprecated. |
parse_gifti_file (\*args, \*\*kwargs) |
parse_gifti_file deprecated. Use GiftiImageParser.parse() instead. |
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
dataspace (int) 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” xformspace (int) 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.” xform (array-like shape (4, 4)) Affine transformation matrix -
__init__
(dataspace=0, xformspace=0, xform=None)¶
-
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=u'', 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
darray (None or ndarray) Data array intent (int) NIFTI intent code, see nifti1.intent_codes datatype (int) 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. encoding (string) Encoding of the data, see util.gifti_encoding_codes; default is GIFTI_ENCODING_B64GZ. endian (string) The Endianness to store the data array. Should correspond to the machine endianness. Default is system byteorder. coordsys ( GiftiCoordSystem
instance) Input and output coordinate system with tranformation matrix between the two.ind_ord (int) The ordering of the array. see util.array_index_order_codes. Default is RowMajorOrder - C ordering meta ( GiftiMetaData
instance) An instance equivalent to a dictionary for metadata information.ext_fname (str) Filename in which data is stored, or empty string if no corresponding filename. ext_offset (int) 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=u'', ext_offset=0)¶ Returns a shell object that cannot be saved.
-
classmethod
from_array
(*args, **kwargs)¶ 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: darray : ndarray
NumPy data array
intent : string
NIFTI intent code, see nifti1.intent_codes
datatype : None or string, optional
NIFTI data type codes, see nifti1.data_type_codes If None, the datatype of the NumPy array is taken.
encoding : string, optionaal
Encoding of the data, see util.gifti_encoding_codes; default: GIFTI_ENCODING_B64GZ
endian : string, optional
The Endianness to store the data array. Should correspond to the machine endianness. default: system byteorder
coordsys : GiftiCoordSystem, optional
If None, a identity transformation is taken.
ordering : string, optional
The ordering of the array. see util.array_index_order_codes; default: RowMajorOrder - C ordering
meta : None or dict, optional
A dictionary for metadata information. If None, gives empty dict.
Returns: da : instance of our own class
-
get_metadata
(*args, **kwargs)¶ 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
(*args, **kwargs)¶ 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
(*args, **kwargs)¶ 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=u'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=u'1.0')¶
-
add_gifti_data_array
(dataarr)¶ Adds a data array to the GiftiImage
Parameters: dataarr : GiftiDataArray
instance
-
files_types
= (('image', '.gii'),)¶
-
classmethod
from_file_map
(klass, file_map, buffer_size=35000000)¶ Load a Gifti image from a file_map
Parameters: file_map : dict
Dictionary with single key
image
with associated value which is aFileHolder
instance pointing to the image file.Returns: img : GiftiImage
-
classmethod
from_filename
(klass, filename, buffer_size=35000000)¶
-
getArraysFromIntent
(*args, **kwargs)¶ 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
(*args, **kwargs)¶ 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
(*args, **kwargs)¶ 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
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
(*args, **kwargs)¶ 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
(*args, **kwargs)¶ 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_map : dict
Dictionary with single key
image
with associated value which is aFileHolder
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
key (int) (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.” red (None or float) Optional value for red. green (None or float) Optional value for green. blue (None or float) Optional value for blue. alpha (None or float) Optional value for alpha. -
__init__
(key=0, red=None, green=None, blue=None, alpha=None)¶
-
get_rgba
(*args, **kwargs)¶ 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__
()¶
-
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)¶
-
classmethod
from_dict
(klass, data_dict)¶
-
get_metadata
(*args, **kwargs)¶ get_metadata method deprecated. Use the metadata property instead.2.1
- deprecated from version: 4.0
-
metadata
¶ Returns metadata as dictionary
-
print_summary
()¶
-
data_tag¶
-
nibabel.gifti.gifti.
data_tag
(*args, **kwargs)¶ 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
(*args, **kwargs)¶ 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: filename : string
The Gifti file to open, it has usually ending .gii
Returns: img : GiftiImage
Returns a GiftiImage
write¶
-
nibabel.gifti.giftiio.
write
(*args, **kwargs)¶ 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: image : GiftiImage
A GiftiImage instance to store
filename : string
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)¶
-
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
-
Outputter
¶
-
class
nibabel.gifti.parse_gifti_fast.
Outputter
(*args, **kwargs)¶ 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__
(*args, **kwargs)¶ 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