# NiBabel

### Access a cacophony of neuro-imaging file formats

# `gifti`

GIfTI format IO

`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`(*args, **kwargs) | A sequence of GiftiNVPairs containing metadata for a gifti data array
`GiftiNVPairs`([name, value]) | Gifti name / value pairs

## Module: `gifti.parse_gifti_fast`

`GiftiImageParser`([encoding, buffer_size, ...]) |
`GiftiParseError` | Gifti-specific parsing error
`read_data_block`(darray, fname, data, mmap) | Parses data from a <Data> element, or loads from an external file.

## Module: `gifti.util`

### `GiftiCoordSystem`

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

  Bases: `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='', ext_offset=0)

  Bases: `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 transformation 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.

  property metadata

    Returns metadata as dictionary

  property num_dim
  print_summary()

### `GiftiImage`

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

  Bases: `XmlSerializable`, `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')
  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 a `tuple`, in the order they are found in the GIFTI image.

    If all `GiftiDataArray` s have `intent` of 2001 (`NIFTI_INTENT_TIME_SERIES`), then the data arrays are concatenated as columns, producing a vertex-by-time array. If an `intent_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. If `intent_code` is a `tuple`, then a `tuple` will be returned with the result of `agg_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 get_test_data
        >>> surf_img = nib.load(get_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(get_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: tuple[ExtensionSpec, ...] = (('image', '.gii'),)
  classmethod from_file_map(file_map, buffer_size=35000000, mmap=True)

    Load a Gifti image from a file_map

    Parameters:
      file_map dict

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

      buffer_size: None or int, optional

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

      mmap{True, False, ‘c’, ‘r’, ‘r+’}

        Controls the use of numpy memory mapping for reading data. Only has an effect when loading GIFTI images with data stored in external files (`DataArray` elements with an `Encoding` equal to `ExternalFileBinary`). If `False`, do not try numpy `memmap` for data array. If one of `{'c', 'r', 'r+'}`, try numpy `memmap` with `mode=mmap`. A mmap value of `True` gives the same behavior as `mmap='c'`. If the file cannot be memory-mapped, ignore mmap value and read array from file.

    Returns:
      img GiftiImage
  classmethod from_filename(filename, buffer_size=35000000, mmap=True)
  get_arrays_from_intent(intent)

    Return list of GiftiDataArray elements matching given intent

  property labeltable
  property meta
  property 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

  to_bytes(enc='utf-8', *, mode='strict')

    Return a `bytes` object with the contents of the file that would be written if the image were saved.

    Parameters:
      **kwargs keyword arguments

        Keyword arguments that may be passed to `img.to_file_map()`

    Returns:
      bytes

        Serialized image

  to_file_map(file_map=None, enc='utf-8', *, mode='strict')

    Save the current image to the specified file_map

    Parameters:
      file_map dict

        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', *, mode='strict', **kwargs) → bytes

    Return XML corresponding to image content

  valid_exts: tuple[str, ...] = ('.gii',)

### `GiftiLabel`

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

  Bases: `XmlSerializable`

  Gifti label: association of integer key with optional RGBA values

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

  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.

  Notes

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

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

    Returns RGBA as tuple

### `GiftiLabelTable`

class nibabel.gifti.gifti.GiftiLabelTable

  Bases: `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(*args, **kwargs)

  Bases: `CaretMetaData`

  A sequence of GiftiNVPairs containing metadata for a gifti data array

  __init__(*args, **kwargs)
  property data

    The data attribute is deprecated. Use GiftiMetaData object directly as a dict.

    - deprecated from version: 4.0

    - Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 6.0

  classmethod from_dict(data_dict)

    from_dict class method deprecated. Use GiftiMetaData directly.

    - deprecated from version: 4.0

    - Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 6.0

  property metadata

    Returns metadata as dictionary

    metadata property deprecated. Use GiftiMetaData object as dict or pass to dict() for a standard dictionary.

    - deprecated from version: 4.0

    - Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 6.0

  print_summary()

### `GiftiNVPairs`

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

  Bases: `object`

  Gifti name / value pairs

  Attributes:
    name str
    value str

  GiftiNVPairs objects are deprecated. Use the GiftiMetaData object as a dict, instead.

  - deprecated from version: 4.0

  - Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 6.0

  __init__(name='', value='')

    GiftiNVPairs objects are deprecated. Use the GiftiMetaData object as a dict, instead.

    - deprecated from version: 4.0

    - Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 6.0

  property name
  property value

### `GiftiImageParser`

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

  Bases: `XmlParser`

  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).

  __init__(encoding=None, buffer_size=35000000, verbose=0, mmap=True)
    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

  property pending_data

    True if there is character data pending for processing

### `GiftiParseError`

class nibabel.gifti.parse_gifti_fast.GiftiParseError

  Bases: `ExpatError`

  Gifti-specific parsing error

  __init__(*args, **kwargs)

### read_data_block

nibabel.gifti.parse_gifti_fast.read_data_block(darray, fname, data, mmap)

  Parses data from a <Data> element, or loads from an external file.

  Parameters:
    darray GiftiDataArray

      GiftiDataArray object representing the parent <DataArray> of this <Data> element

    fname str or None

      Name of GIFTI file being loaded, or None if in-memory

    data str or None

      Data to parse, or None if data is in an external file

    mmap{True, False, ‘c’, ‘r’, ‘r+’}

      Controls the use of numpy memory mapping for reading data. Only has an effect when loading GIFTI images with data stored in external files (`DataArray` elements with an `Encoding` equal to `ExternalFileBinary`). If `False`, do not try numpy `memmap` for data array. If one of `{'c', 'r', 'r+'}`, try numpy `memmap` with `mode=mmap`. A mmap value of `True` gives the same behavior as `mmap='c'`. If the file cannot be memory-mapped, ignore mmap value and read array from file.

  Returns:
    `numpy.ndarray` or `numpy.memmap` containing the parsed data