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
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)¶ 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
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='', 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: 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
()¶ 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: dataarr : GiftiDataArray
instance
-
agg_data
(intent_code=None)¶ Aggregate GIFTI data arrays into an ndarray or tuple of ndarray
In the general case, the numpy data array is extracted from each
GiftiDataArray
object and returned in atuple
, in the order they are found in the GIFTI image.If all
GiftiDataArray
s haveintent
of 2001 (NIFTI_INTENT_TIME_SERIES
), then the data arrays are concatenated as columns, producing a vertex-by-time array. If anintent_code
is passed, data arrays are filtered by the selected intents, before being aggregated. This may be useful for images containing several intents, or ensuring an expected data type in an image of uncertain provenance. Ifintent_code
is atuple
, then atuple
will be returned with the result ofagg_data
for each element, in order. This may be useful for ensuring that expected data arrives in a consistent order.Parameters: intent_code : None, string, integer or tuple of strings or integers, optional
code(s) specifying nifti intent
Returns: tuple of ndarrays or ndarray
If the input is a tuple, the returned tuple will match the order.
Examples
Consider a surface GIFTI file:
>>> import nibabel as nib >>> from nibabel.testing import test_data >>> surf_img = nib.load(test_data('gifti', 'ascii.gii'))
The coordinate data, which is indicated by the
NIFTI_INTENT_POINTSET
intent code, may be retrieved using any of the following equivalent calls:>>> coords = surf_img.agg_data('NIFTI_INTENT_POINTSET') >>> coords_2 = surf_img.agg_data('pointset') >>> coords_3 = surf_img.agg_data(1008) # Numeric code for pointset >>> print(np.array2string(coords, precision=3)) [[-16.072 -66.188 21.267] [-16.706 -66.054 21.233] [-17.614 -65.402 21.071]] >>> np.array_equal(coords, coords_2) True >>> np.array_equal(coords, coords_3) True
Similarly, the triangle mesh can be retrieved using various intent specifiers:
>>> triangles = surf_img.agg_data('NIFTI_INTENT_TRIANGLE') >>> triangles_2 = surf_img.agg_data('triangle') >>> triangles_3 = surf_img.agg_data(1009) # Numeric code for pointset >>> print(np.array2string(triangles)) [0 1 2] >>> np.array_equal(triangles, triangles_2) True >>> np.array_equal(triangles, triangles_3) True
All arrays can be retrieved as a
tuple
by omitting the intent code:>>> coords_4, triangles_4 = surf_img.agg_data() >>> np.array_equal(coords, coords_4) True >>> np.array_equal(triangles, triangles_4) True
Finally, a tuple of intent codes may be passed in order to select the arrays in a specific order:
>>> triangles_5, coords_5 = surf_img.agg_data(('triangle', 'pointset')) >>> np.array_equal(triangles, triangles_5) True >>> np.array_equal(coords, coords_5) True
The following image is a GIFTI file with ten (10) data arrays of the same size, and with intent code 2001 (
NIFTI_INTENT_TIME_SERIES
):>>> func_img = nib.load(test_data('gifti', 'task.func.gii'))
When aggregating time series data, these arrays are concatenated into a single, vertex-by-timestep array:
>>> series = func_img.agg_data() >>> series.shape (642, 10)
In the case of a GIFTI file with unknown data arrays, it may be preferable to specify the intent code, so that a time series array is always returned:
>>> series_2 = func_img.agg_data('NIFTI_INTENT_TIME_SERIES') >>> series_3 = func_img.agg_data('time series') >>> series_4 = func_img.agg_data(2001) >>> np.array_equal(series, series_2) True >>> np.array_equal(series, series_3) True >>> np.array_equal(series, series_4) True
Requesting a data array from a GIFTI file with no matching intent codes will result in an empty tuple:
>>> surf_img.agg_data('time series') () >>> func_img.agg_data('triangle') ()
-
files_types
= (('image', '.gii'),)¶
-
classmethod
from_file_map
(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
(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
¶
-
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_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)¶ 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
()¶
-
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: filename : string
The Gifti file to open, it has usually ending .gii
Returns: img : GiftiImage
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: 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)¶ Parameters: encoding : str
string containing xml document
buffer_size: None or int, optional
size of read buffer. None uses default buffer_size from xml.parsers.expat.
verbose : int, 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
-
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