cifti2
¶
CIfTI format IO
cifti2 |
Read / write access to CIfTI2 image format |
Module: cifti2.cifti2
¶
Read / write access to CIfTI2 image format
Format of the NIFTI2 container format described here:
Definition of the CIFTI2 header format and file extensions attached to this email:
Filename is CIFTI-2_Main_FINAL_1March2014.pdf
.
Cifti2BrainModel ([index_offset, …]) |
Element representing a mapping of the dimension to vertex or voxels. |
Cifti2Header ([matrix, version]) |
Class for CIFTI2 header extension |
Cifti2HeaderError |
Error in CIFTI2 header |
Cifti2Image ([dataobj, header, nifti_header, …]) |
Class for single file CIFTI2 format image |
Cifti2Label ([key, label, red, green, blue, …]) |
CIFTI2 label: association of integer key with a name and RGBA values |
Cifti2LabelTable () |
CIFTI2 label table: a sequence of ``Cifti2Label``s |
Cifti2Matrix () |
CIFTI2 Matrix object |
Cifti2MatrixIndicesMap (…[, …]) |
Class for Matrix Indices Map |
Cifti2MetaData ([metadata]) |
A list of name-value pairs |
Cifti2NamedMap ([map_name, metadata, label_table]) |
CIFTI2 named map: association of name and optional data with a map index |
Cifti2Parcel ([name, voxel_indices_ijk, vertices]) |
CIFTI2 parcel: association of a name with vertices and/or voxels |
Cifti2Surface ([brain_structure, …]) |
Cifti surface: association of brain structure and number of vertices |
Cifti2TransformationMatrixVoxelIndicesIJKtoXYZ ([…]) |
Matrix that translates voxel indices to spatial coordinates |
Cifti2VertexIndices ([indices]) |
CIFTI2 vertex indices: vertex indices for an associated brain model |
Cifti2Vertices ([brain_structure, vertices]) |
CIFTI2 vertices - association of brain structure and a list of vertices |
Cifti2Volume ([volume_dimensions, …]) |
CIFTI2 volume: information about a volume for mappings that use voxels |
Cifti2VoxelIndicesIJK ([indices]) |
CIFTI2 VoxelIndicesIJK: Set of voxel indices contained in a structure |
load (filename) |
Load cifti2 from filename |
save (img, filename) |
Save cifti to filename |
Module: cifti2.parse_cifti2
¶
Cifti2Extension ([code, content]) |
|
Cifti2Parser ([encoding, buffer_size, verbose]) |
Class to parse an XML string into a CIFTI2 header object |
Cifti2BrainModel
¶
-
class
nibabel.cifti2.cifti2.
Cifti2BrainModel
(index_offset=None, index_count=None, model_type=None, brain_structure=None, n_surface_vertices=None, voxel_indices_ijk=None, vertex_indices=None)¶ Bases:
nibabel.xmlutils.XmlSerializable
Element representing a mapping of the dimension to vertex or voxels.
Mapping to vertices of voxels must be specified.
Description - Maps a range of indices to surface vertices or voxels when IndicesMapToDataType is “CIFTI_INDEX_TYPE_BRAIN_MODELS.”
Attributes
- IndexOffset - The matrix index of the first brainordinate of this BrainModel. Note that matrix indices are zero-based.
- IndexCount - Number of surface vertices or voxels in this brain model, must be positive.
- ModelType - Type of model representing the brain structure (surface or voxels). Valid values are listed in the table below.
- BrainStructure - Identifies the brain structure. Valid values for BrainStructure are listed in the table below. However, if the needed structure is not listed in the table, a message should be posted to the CIFTI Forum so that a standardized name can be created for the structure and added to the table.
- SurfaceNumberOfVertices - When ModelType is CIFTI_MODEL_TYPE_SURFACE this attribute contains the actual (or true) number of vertices in the surface that is associated with this BrainModel. When this BrainModel represents all vertices in the surface, this value is the same as IndexCount. When this BrainModel represents only a subset of the surface’s vertices, IndexCount will be less than this value.
Child Elements
- VertexIndices (0…1)
- VoxelIndicesIJK (0…1)
Text Content: [NA]
Parent Element - MatrixIndicesMap
For ModelType values, see CIFTI_MODEL_TYPES module attribute.
For BrainStructure values, see CIFTI_BRAIN_STRUCTURES model attribute.
Attributes
index_offset (int) Start of the mapping index_count (int) Number of elements in the array to be mapped model_type (str) One of CIFTI_MODEL_TYPES brain_structure (str) One of CIFTI_BRAIN_STRUCTURES surface_number_of_vertices (int) Number of vertices in the surface. Use only for surface-type structure voxel_indices_ijk (Cifti2VoxelIndicesIJK, optional) Indices on the image towards where the array indices are mapped vertex_indices (Cifti2VertexIndices, optional) Indices of the vertices towards where the array indices are mapped -
__init__
(index_offset=None, index_count=None, model_type=None, brain_structure=None, n_surface_vertices=None, voxel_indices_ijk=None, vertex_indices=None)¶
-
vertex_indices
¶
-
voxel_indices_ijk
¶
Cifti2Header
¶
-
class
nibabel.cifti2.cifti2.
Cifti2Header
(matrix=None, version='2.0')¶ Bases:
nibabel.filebasedimages.FileBasedHeader
,nibabel.xmlutils.XmlSerializable
Class for CIFTI2 header extension
-
__init__
(matrix=None, version='2.0')¶
-
get_index_map
(index)¶ Cifti2 Mapping class for a given index
Parameters: index : int
Index for which we want to obtain the mapping. Must be in the mapped_indices sequence.
Returns: cifti2_map : Cifti2MatrixIndicesMap
Returns the Cifti2MatrixIndicesMap corresponding to the given index.
-
mapped_indices
¶ List of matrix indices that are mapped
-
classmethod
may_contain_header
(klass, binaryblock)¶
-
number_of_mapped_indices
¶ Number of mapped indices
-
Cifti2Image
¶
-
class
nibabel.cifti2.cifti2.
Cifti2Image
(dataobj=None, header=None, nifti_header=None, extra=None, file_map=None)¶ Bases:
nibabel.dataobj_images.DataobjImage
Class for single file CIFTI2 format image
Initialize image
The image is a combination of (dataobj, header), with optional metadata in nifti_header (a NIfTI2 header). There may be more metadata in the mapping extra. Filename / file-like objects can also go in the file_map mapping.
Parameters: dataobj : object
Object containing image data. It should be some object that returns an array from
np.asanyarray
. It should have ashape
attribute or property.header : Cifti2Header instance
Header with data for / from XML part of CIFTI2 format.
nifti_header : None or mapping or NIfTI2 header instance, optional
Metadata for NIfTI2 component of this format.
extra : None or mapping
Extra metadata not captured by header or nifti_header.
file_map : mapping, optional
Mapping giving file information for this image format.
-
__init__
(dataobj=None, header=None, nifti_header=None, extra=None, file_map=None)¶ Initialize image
The image is a combination of (dataobj, header), with optional metadata in nifti_header (a NIfTI2 header). There may be more metadata in the mapping extra. Filename / file-like objects can also go in the file_map mapping.
Parameters: dataobj : object
Object containing image data. It should be some object that returns an array from
np.asanyarray
. It should have ashape
attribute or property.header : Cifti2Header instance
Header with data for / from XML part of CIFTI2 format.
nifti_header : None or mapping or NIfTI2 header instance, optional
Metadata for NIfTI2 component of this format.
extra : None or mapping
Extra metadata not captured by header or nifti_header.
file_map : mapping, optional
Mapping giving file information for this image format.
-
files_types
= (('image', '.nii'),)¶
-
classmethod
from_file_map
(klass, file_map)¶ Load a CIFTI2 image from a file_map
Parameters: file_map : file_map
Returns: img : Cifti2Image
Returns a Cifti2Image
-
classmethod
from_image
(klass, img)¶ Class method to create new instance of own class from img
Parameters: img : instance
In fact, an object with the API of
DataobjImage
.Returns: cimg : instance
Image, of our own class
-
get_data_dtype
()¶
-
header_class
¶ alias of
Cifti2Header
-
makeable
= False¶
-
nifti_header
¶
-
rw
= True¶
-
set_data_dtype
(dtype)¶
-
to_file_map
(file_map=None)¶ Write image to file_map or contained
self.file_map
Parameters: file_map : None or mapping, optional
files mapping. If None (default) use object’s
file_map
attribute instead.Returns: None
-
update_headers
()¶ Harmonize CIFTI2 and NIfTI headers with image data
>>> import numpy as np >>> data = np.zeros((2,3,4)) >>> img = Cifti2Image(data) >>> img.shape == (2, 3, 4) True >>> img.update_headers() >>> img.nifti_header.get_data_shape() == (2, 3, 4) True
-
valid_exts
= ('.nii',)¶
-
Cifti2Label
¶
-
class
nibabel.cifti2.cifti2.
Cifti2Label
(key=0, label='', red=0.0, green=0.0, blue=0.0, alpha=0.0)¶ Bases:
nibabel.xmlutils.XmlSerializable
CIFTI2 label: association of integer key with a name and RGBA values
For all color components, value is floating point with range 0.0 to 1.0.
Description - Associates a label key value with a name and a display color.
Attributes
- Key - Integer, data value which is assigned this name and color.
- Red - Red color component for label. Value is floating point with range 0.0 to 1.0.
- Green - Green color component for label. Value is floating point with range 0.0 to 1.0.
- Blue - Blue color component for label. Value is floating point with range 0.0 to 1.0.
- Alpha - Alpha color component for label. Value is floating point with range 0.0 to 1.0.
Child Elements: [NA]
Text Content - Name of the label.
Parent Element - LabelTable
Attributes
key (int, optional) Integer, data value which is assigned this name and color. label (str, optional) Name of the label. red (float, optional) Red color component for label (between 0 and 1). green (float, optional) Green color component for label (between 0 and 1). blue (float, optional) Blue color component for label (between 0 and 1). alpha (float, optional) Alpha color component for label (between 0 and 1). -
__init__
(key=0, label='', red=0.0, green=0.0, blue=0.0, alpha=0.0)¶
-
rgba
¶ Returns RGBA as tuple
Cifti2LabelTable
¶
-
class
nibabel.cifti2.cifti2.
Cifti2LabelTable
¶ Bases:
nibabel.xmlutils.XmlSerializable
,_abcoll.MutableMapping
CIFTI2 label table: a sequence of ``Cifti2Label``s
Description - Used by NamedMap when IndicesMapToDataType is “CIFTI_INDEX_TYPE_LABELS” in order to associate names and display colors with label keys. Note that LABELS is the only mapping type that uses a LabelTable. Display coloring of continuous-valued data is not specified by CIFTI-2.
Attributes: [NA]
Child Elements
- Label (0…N)
Text Content: [NA]
Parent Element - NamedMap
-
__init__
()¶
-
append
(label)¶
Cifti2Matrix
¶
-
class
nibabel.cifti2.cifti2.
Cifti2Matrix
¶ Bases:
nibabel.xmlutils.XmlSerializable
,_abcoll.MutableSequence
CIFTI2 Matrix object
This is a list-like container where the elements are instances of
Cifti2MatrixIndicesMap
.Description: contains child elements that describe the meaning of the values in the matrix.
Attributes: [NA]
Child Elements
- MetaData (0 .. 1)
- MatrixIndicesMap (1 .. N)
Text Content: [NA]
Parent Element: CIFTI
For each matrix (data) dimension, exactly one MatrixIndicesMap element must list it in the AppliesToMatrixDimension attribute.
-
__init__
()¶
-
get_index_map
(index)¶ Cifti2 Mapping class for a given index
Parameters: index : int
Index for which we want to obtain the mapping. Must be in the mapped_indices sequence.
Returns: cifti2_map : Cifti2MatrixIndicesMap
Returns the Cifti2MatrixIndicesMap corresponding to the given index.
-
insert
(index, value)¶
-
mapped_indices
¶ List of matrix indices that are mapped
-
metadata
¶
Cifti2MatrixIndicesMap
¶
-
class
nibabel.cifti2.cifti2.
Cifti2MatrixIndicesMap
(applies_to_matrix_dimension, indices_map_to_data_type, number_of_series_points=None, series_exponent=None, series_start=None, series_step=None, series_unit=None, maps=[])¶ Bases:
nibabel.xmlutils.XmlSerializable
,_abcoll.MutableSequence
Class for Matrix Indices Map
Description - Provides a mapping between matrix indices and their interpretation.
Attributes
- AppliesToMatrixDimension - Lists the dimension(s) of the matrix to which this MatrixIndicesMap applies. The dimensions of the matrix start at zero (dimension 0 describes the indices along the first dimension, dimension 1 describes the indices along the second dimension, etc.). If this MatrixIndicesMap applies to more than one matrix dimension, the values are separated by a comma.
- IndicesMapToDataType - Type of data to which the MatrixIndicesMap applies.
- NumberOfSeriesPoints - Indicates how many samples there are in a series mapping type. For example, this could be the number of timepoints in a timeseries.
- SeriesExponent - Integer, SeriesStart and SeriesStep must be multiplied by 10 raised to the power of the value of this attribute to give the actual values assigned to indices (e.g., if SeriesStart is “5” and SeriesExponent is “-3”, the value of the first series point is 0.005).
- SeriesStart - Indicates what quantity should be assigned to the first series point.
- SeriesStep - Indicates amount of change between each series point.
- SeriesUnit - Indicates the unit of the result of multiplying SeriesStart and SeriesStep by 10 to the power of SeriesExponent.
Child Elements
- BrainModel (0…N)
- NamedMap (0…N)
- Parcel (0…N)
- Surface (0…N)
- Volume (0…1)
Text Content: [NA]
Parent Element - Matrix
-
__init__
(applies_to_matrix_dimension, indices_map_to_data_type, number_of_series_points=None, series_exponent=None, series_start=None, series_step=None, series_unit=None, maps=[])¶
-
brain_models
¶
-
insert
(index, value)¶
-
named_maps
¶
-
parcels
¶
-
surfaces
¶
-
volume
¶
Cifti2MetaData
¶
-
class
nibabel.cifti2.cifti2.
Cifti2MetaData
(metadata=None)¶ Bases:
nibabel.xmlutils.XmlSerializable
,_abcoll.MutableMapping
A list of name-value pairs
Description - Provides a simple method for user-supplied metadata that associates names with values.
Attributes: [NA]
Child Elements
- MD (0…N)
Text Content: [NA]
Parent Elements - Matrix, NamedMap
MD elements are a single metadata entry consisting of a name and a value.
Attributes
data (list of (name, value) tuples) -
__init__
(metadata=None)¶
-
difference_update
(metadata)¶ Remove metadata key-value pairs
Parameters: metadata : dict-like datatype Returns: None
Cifti2NamedMap
¶
-
class
nibabel.cifti2.cifti2.
Cifti2NamedMap
(map_name=None, metadata=None, label_table=None)¶ Bases:
nibabel.xmlutils.XmlSerializable
CIFTI2 named map: association of name and optional data with a map index
Associates a name, optional metadata, and possibly a LabelTable with an index in a map.
Description - Associates a name, optional metadata, and possibly a LabelTable with an index in a map.
Attributes: [NA]
Child Elements
- MapName (1)
- LabelTable (0…1)
- MetaData (0…1)
Text Content: [NA]
Parent Element - MatrixIndicesMap
Attributes
map_name (str) Name of map metadata (None or Cifti2MetaData) Metadata associated with named map label_table (None or Cifti2LabelTable) Label table associated with named map -
__init__
(map_name=None, metadata=None, label_table=None)¶
-
label_table
¶
-
metadata
¶
Cifti2Parcel
¶
-
class
nibabel.cifti2.cifti2.
Cifti2Parcel
(name=None, voxel_indices_ijk=None, vertices=None)¶ Bases:
nibabel.xmlutils.XmlSerializable
CIFTI2 parcel: association of a name with vertices and/or voxels
Description - Associates a name, plus vertices and/or voxels, with an index.
Attributes
- Name - The name of the parcel
Child Elements
- Vertices (0…N)
- VoxelIndicesIJK (0…1)
Text Content: [NA]
Parent Element - MatrixIndicesMap
Attributes
name (str) Name of parcel voxel_indices_ijk (None or Cifti2VoxelIndicesIJK) Voxel indices associated with parcel vertices (list of Cifti2Vertices) Vertices associated with parcel -
__init__
(name=None, voxel_indices_ijk=None, vertices=None)¶
-
append_cifti_vertices
(vertices)¶ Appends a Cifti2Vertices element to the Cifti2Parcel
Parameters: vertices : Cifti2Vertices
-
pop_cifti2_vertices
(ith)¶ Pops the ith vertices element from the Cifti2Parcel
-
voxel_indices_ijk
¶
Cifti2Surface
¶
-
class
nibabel.cifti2.cifti2.
Cifti2Surface
(brain_structure=None, surface_number_of_vertices=None)¶ Bases:
nibabel.xmlutils.XmlSerializable
Cifti surface: association of brain structure and number of vertices
Description - Specifies the number of vertices for a surface, when IndicesMapToDataType is “CIFTI_INDEX_TYPE_PARCELS.” This is separate from the Parcel element because there can be multiple parcels on one surface, and one parcel may involve multiple surfaces.
Attributes
- BrainStructure - A string from the BrainStructure list to identify what surface structure this element refers to (usually left cortex, right cortex, or cerebellum).
- SurfaceNumberOfVertices - The number of vertices that this structure’s surface contains.
Child Elements: [NA]
Text Content: [NA]
Parent Element - MatrixIndicesMap
Attributes
brain_structure (str) Name of brain structure surface_number_of_vertices (int) Number of vertices on surface -
__init__
(brain_structure=None, surface_number_of_vertices=None)¶
Cifti2TransformationMatrixVoxelIndicesIJKtoXYZ
¶
-
class
nibabel.cifti2.cifti2.
Cifti2TransformationMatrixVoxelIndicesIJKtoXYZ
(meter_exponent=None, matrix=None)¶ Bases:
nibabel.xmlutils.XmlSerializable
Matrix that translates voxel indices to spatial coordinates
Description - Contains a matrix that translates Voxel IJK Indices to spatial XYZ coordinates (+X=>right, +Y=>anterior, +Z=> superior). The resulting coordinate is the center of the voxel.
Attributes
- MeterExponent - Integer, specifies that the coordinate result from the transformation matrix should be multiplied by 10 to this power to get the spatial coordinates in meters (e.g., if this is “-3”, then the transformation matrix is in millimeters).
Child Elements: [NA]
Text Content - Sixteen floating-point values, in row-major order, that form a 4x4 homogeneous transformation matrix.
Parent Element - Volume
Attributes
meter_exponent (int) See attribute description above. matrix (array-like shape (4, 4)) Affine transformation matrix from voxel indices to RAS space. -
__init__
(meter_exponent=None, matrix=None)¶
Cifti2VertexIndices
¶
-
class
nibabel.cifti2.cifti2.
Cifti2VertexIndices
(indices=None)¶ Bases:
nibabel.xmlutils.XmlSerializable
,_abcoll.MutableSequence
CIFTI2 vertex indices: vertex indices for an associated brain model
The vertex indices (which are independent for each surface, and zero-based) that are used in this brain model[.] The parent BrainModel’s
index_count
indicates the number of indices.- Description - Contains a list of vertex indices for a BrainModel with ModelType equal to CIFTI_MODEL_TYPE_SURFACE.
- Attributes: [NA]
- Child Elements: [NA]
- Text Content - The vertex indices (which are independent for each surface, and zero-based) that are used in this brain model, with each index separated by a whitespace character. The parent BrainModel’s IndexCount attribute indicates the number of indices in this element’s content.
- Parent Element - BrainModel
-
__init__
(indices=None)¶
-
insert
(index, value)¶
Cifti2Vertices
¶
-
class
nibabel.cifti2.cifti2.
Cifti2Vertices
(brain_structure=None, vertices=None)¶ Bases:
nibabel.xmlutils.XmlSerializable
,_abcoll.MutableSequence
CIFTI2 vertices - association of brain structure and a list of vertices
Description - Contains a BrainStructure type and a list of vertex indices within a Parcel.
Attributes
- BrainStructure - A string from the BrainStructure list to identify what surface this vertex list is from (usually left cortex, right cortex, or cerebellum).
Child Elements: [NA]
Text Content - Vertex indices (which are independent for each surface, and zero-based) separated by whitespace characters.
Parent Element - Parcel
The class behaves like a list of Vertex indices (which are independent for each surface, and zero-based)
Attributes
brain_structure (str) A string from the BrainStructure list to identify what surface this vertex list is from (usually left cortex, right cortex, or cerebellum). -
__init__
(brain_structure=None, vertices=None)¶
-
insert
(index, value)¶
Cifti2Volume
¶
-
class
nibabel.cifti2.cifti2.
Cifti2Volume
(volume_dimensions=None, transform_matrix=None)¶ Bases:
nibabel.xmlutils.XmlSerializable
CIFTI2 volume: information about a volume for mappings that use voxels
Description - Provides information about the volume for any mappings that use voxels.
Attributes
- VolumeDimensions - Three integer values separated by commas, the lengths of the three volume file dimensions that are related to spatial coordinates, in number of voxels. Voxel indices (which are zero-based) that are used in the mapping that this element applies to must be within these dimensions.
Child Elements
- TransformationMatrixVoxelIndicesIJKtoXYZ (1)
Text Content: [NA]
Parent Element - MatrixIndicesMap
Attributes
volume_dimensions (array-like shape (3,)) See attribute description above. transformation_matrix_voxel_indices_ijk_to_xyz (Cifti2TransformationMatrixVoxelIndicesIJKtoXYZ) Matrix that translates voxel indices to spatial coordinates -
__init__
(volume_dimensions=None, transform_matrix=None)¶
Cifti2VoxelIndicesIJK
¶
-
class
nibabel.cifti2.cifti2.
Cifti2VoxelIndicesIJK
(indices=None)¶ Bases:
nibabel.xmlutils.XmlSerializable
,_abcoll.MutableSequence
CIFTI2 VoxelIndicesIJK: Set of voxel indices contained in a structure
- Description - Identifies the voxels that model a brain structure, or participate in a parcel. Note that when this is a child of BrainModel, the IndexCount attribute of the BrainModel indicates the number of voxels contained in this element.
- Attributes: [NA]
- Child Elements: [NA]
- Text Content - IJK indices (which are zero-based) of each voxel in this brain model or parcel, with each index separated by a whitespace character. There are three indices per voxel. If the parent element is BrainModel, then the BrainModel element’s IndexCount attribute indicates the number of triplets (IJK indices) in this element’s content.
- Parent Elements - BrainModel, Parcel
Each element of this sequence is a triple of integers.
-
__init__
(indices=None)¶
-
insert
(index, value)¶
load¶
-
nibabel.cifti2.cifti2.
load
(filename)¶ Load cifti2 from filename
Parameters: filename : str
filename of image to be loaded
Returns: img : Cifti2Image
cifti image instance
Raises: ImageFileError: if `filename` doesn’t look like cifti
IOError : if filename does not exist
save¶
-
nibabel.cifti2.cifti2.
save
(img, filename)¶ Save cifti to filename
Parameters: filename : str
filename to which to save image
Cifti2Extension
¶
-
class
nibabel.cifti2.parse_cifti2.
Cifti2Extension
(code=None, content=None)¶ Bases:
nibabel.nifti1.Nifti1Extension
-
__init__
(code=None, content=None)¶
-
code
= 32¶
-
Cifti2Parser
¶
-
class
nibabel.cifti2.parse_cifti2.
Cifti2Parser
(encoding=None, buffer_size=3500000, verbose=0)¶ Bases:
nibabel.xmlutils.XmlParser
Class to parse an XML string into a CIFTI2 header object
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=3500000, 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
-