Cifti:main

From Van Essen Lab

Revision as of 21:39, 14 April 2011 by Jschindl (Talk | contribs)
Jump to: navigation, search

CIFTI Connectivity File Formats

Version 1.0

John Harwell
Jon Schindler
Matthew Glasser
David Van Essen

2011-4-14

fMRI
Trajectory

Contents

Introduction

In the past, the neuroimaging community used many file formats for both surface and volume data. These different data formats inhibited the sharing of data since each neuroimaging software application processed only a few of the many data formats. As a result, the NIFTI (Neuroimaging Informatics Technology Initiative) Committee, consisting of neuroimaging software developers, created the NIFTI-1 volume file format. This NIFTI-1 volume file format (a superset of the Analyze volume file format) has become the de facto standard file format for volume data in the neuroimaging community. The success of the NIFTI volume file format spurred the formation of the GIFTI (Geometry Informatics Technology Initiative) committee whose goal was to develop a standardized file format for surface-based data. The resulting GIFTI file format is becoming the standard file format for surface-based data.

Investigators studying brain connectivity are now producing several types of connectivity data that includes connectivity matrices, graphs, trajectories, and vectors. However, no standardized file formats exists for these data types. In this document, we propose the CIFTI (Connectivity Sub-committee of the Neuroimaging Informatics Technology Initiative) file format. What separates CIFTI from both NIFTI-1 and GIFTI is that the data in a CIFTI file may encompass both surface and volume data and the data may represent a subset of the surface nodes and/or volume voxels.

Both NIFTI-1 and GIFTI file formats were considered for the CIFTI connectivity matrix data. Since the connectivity matrix is two-dimensional, identical to a single slice in a volume, NIFTI-1 was found to be an attractive file format. However, the NIFTI-1 design that maintains compatibility with the Analyze file format restricts each of the dimensions in a NIFTI-1 volume file to a maximum index of 32,767 (the indices are stored in 16-bit integers). Since the indices in a CIFTI connectivity matrix will often exceed 32,767, this precluded the use of the NIFTI-1 file format.

Since eliminating the constraint on dimensions was found to be beneficial to many in the neuroscience community, the NIFTI committee has issued a standard for the NIFTI-2 file format. NIFTI-2 is very similar to NIFTI-1 except that the several attributes in the file’s header have been replaced with larger data types. Most importantly, this includes the indices that have been replaced with 64-bit integers allowing almost unlimited indices for each dimension (up to 9 quintillion).

The NIFTI-2 file format will be used for CIFTI connectivity matrix files. For proper interpretation of the data, additional metadata is placed into the NIFTI-2 file using the established protocols for NIFTI header extensions. This document defines the structure of the NIFTI-2 file format and the header extension for CIFTI data. The examples discussed here focus on MRI data (diffusion imaging and fMRI). Extensions of the CIFTI format may be appropriate for some types of MEG and EEG data that have been mapped to brainordinates (i.e. voxels or vertices).

The NITRC (Neuroimaging Informatics Tools and Resources Clearinghouse, http://www.nitrc.org) website is a portal for neuroimaging resources. CIFTI, GIFTI, and NIFTI all use NITRC for the discussion and dissemination of project related information. Documentation, example files, and message forums have been setup for the CIFTI file format on the NITRC website. Visit http://www.nitrc.org/projects/cifti for more information.

Connectivity Matrix Files

There are several types of connectivity matrix files. Each of these files contains a single matrix, which may represent a correlation matrix in the case of resting state fMRI data or number of streamlines in the case of diffusion tractography data, though any type of connectivity measure could be represented. Each element in the matrix measures the connectivity of the entities in the intersecting row and column. The row indices start at the top of the matrix and increment in a downward direction. The column indices start at the left side of the matrix and increment in a rightward direction.

Connectivity Matrix

In most cases, the connectivity matrix is a two-dimensional matrix whose elements consist of connectivity measurements. A three-dimensional matrix can be used to store multiple connectivity measures between two points or fiber trajectory information (see below). The data in this connectivity matrix may be associated with brainordinates, parcels, time-points, fibers, or a combination of these data types. The first data type, a brainordinate (brain coordinate), is a spatial location in the brain that is modeled as either a surface node or a volume voxel. Subtypes of brainordinates are grayordinates (brainordinates representing gray matter) and whiteordinates (brainordinates representing white matter). The cerebral cortices, due to their sheet-like structure, are typically modeled using surfaces and the sub-cortical structures, due to their solid composition, are modeled using volumes, however these conventions are not enforced. The second data type, a parcel, represents a group of related brainordinates that have a common attribute such as architectonics or function. A related set of parcels forms a parcellation scheme. The Brodmann Areas are an example of a parcellation scheme. Lastly, the third data type is a time-point, which is a measurement obtained at a specific time during a neuroimaging scan. Fibers refer to the fiber orientations reconstructed at a given diffusion imaging voxel that can be used to reconstruct trajectory information.

The connectivity matrix may be very large. For example, at high spatial resolution, the dimensions of the Dense Connectivity Matrix may be 100,000 by 100,000 (38GB for 4-byte floats) or greater. Typical connectivity matrices will be smaller on the order of 50,000 by 50,000 (9GB for 4-byte floats). Because of the large file size, it will often be advantageous to read subsets of the file when viewing the connectivity data, typically one or several rows of the matrix, using a random access file implementation. For efficient random access file reading of a matrix row, the data must be stored in row-major order so that the data for the row is in a contiguous section of memory.

CIFTI Metadata

Two types of metadata are associated with a connectivity matrix. The first type of metadata, Matrix Indices Map metadata, is required and maps row and column indices of the matrix to brainordinates. The second type of metadata is optional and allows users to add additional metadata, as desired. The hierarchy of the metadata is shown in the diagram that follows.

File:CiftiMetadataHierarchy.png

User Metadata

A system for user metadata is present in a CIFTI file. This system is identical to GIFTI’s metadata system and the metadata is an associative arrays containing pairs of keys and values. Users are free to add metadata as desired. CIFTI also follows the GIFTI policy that if matrix is modified, the user metadata may be discarded due to the fact that modifying the matrix may invalidate the user metadata.

Standard User Metadata

There are several metadata entries that are commonly used and their names are listed as standard metadata in this section.

Standard User Metadata
Name Description
DateTime Indicates date and time file was written. Value is in ISO 8601 extended format as YYYY-MM-DDTHH:MM (ie: 2011-02-17T09:12).
Description Provides a text description (comment) of the data
Name Name of the data, possibly displayed in the graphical user-interface.
UniqueID A universally unique identifier
UserName Name of user that created the matrix.

Matrix Indices Map Metadata

A connectivity matrix provides a connectivity measurement between the data represented by the rows and the data represented by the columns. Types of data supported include brain structures, fibers, parcels, and timepoints. The first type of data associated with a dimension is CIFTI_INDEX_TYPE_BRAIN_MODELS, which consist of brainordinates, and requires additional metadata that maps dimension indices to specific brainordinates. The second type of data associated with a dimension is CIFTI_INDEX_TYPE_FIBERS for use in tractography trajectory analyses. The third type of data associated with a dimension is CIFTI_INDEX_TYPE_PARCELS. Parcellated data requires the presence of a LabelTable that associates a name with each of the parcel dimension indices. Lastly, if the data along a dimension is CIFTI_INDEX_TYPE_TIME_POINTS, two attributes are added. The attribute TimeStep indicates the amount of time between each timepoint and the attribute TimeStepUnits indicates the units of TimeStep.

If a MatrixIndicesMap’s IndicesMapToDataType is CIFTI_INDEX_TYPE_BRAIN_MODELS, additional metadata is present that links a brain model’s brainordinates to their connectivity matrix data’s indices. A brain structure may be modeled as a surface or a volume. When modeled as a surface, the NodeIndices element lists the node indices corresponding to the row and/or column indices of the matrix. If the NodeIndices element is missing or empty, it implies that all of the surface’s nodes are present in the matrix. In the case of a volume, VoxelIndicesIJK element lists the voxel IJK indices corresponding to the row and/or column indices of the matrix. If the voxelIndicesIJK element is missing or empty, it implies that all of the volume’s voxels are present in the matrix. The dimensions of the volume are located in the VolumeDimensions attribute of the Volume element which is a child of the Matrix element. The Volume element also contains one or more TransformationMatrixVoxelIndicesIJKtoXYZ elements that convert voxel IJK indices to XYZ-coordinates. The spatial XYZ coordinates of the voxels always map positive X to the right, positive Y to anterior, and positive Z to superior. If desired, multiple transformation matrices are allowed.

Label Metadata

When the connectivity matrix involves parcels, a LabelTable provides metadata associated with the row and/or column indices of the parcels. Each label provides a name, color components, and coordinates associated with a parcel.

CIFTI Metadata Elements

Following each child of an element are quantity indicators, in parenthesis, that describe the allowable quantity of the preceding child. This quantity is expressed in two ways. A number indicates a fixed number of children. A varying quantity is shown as a range of numbers separated by an ellipsis. When ‘N’ is present on the right side of the ellipsis, it indicates a quantity greater than or equal to the quantity on the left side of the ellipsis.

BrainModel Element

  • Description – Maps indices in a matrix dimension to data in surfaces and/or volumes.
  • Attributes
    • IndexOffset - Index of first element in dimension of the matrix for this brain structure. The value is the number of elements, NOT the number of bytes. The element indices of a matrix always starts at zero.
    • IndexCount – Number of elements in this brain model.
    • ModelType – Type of model representing the brain structure.
    • BrainStructure – Identifies the brain structure. Software reading a CIFTI volume should allow any value for BrainStructure, not just the values listed in the table below.
    • SurfaceNumberOfNodes - When ModelType is CIFTI_MODEL_TYPE_SURFACE this attribute contains the actual (or true) number of nodes in the surface that is associated with this BrainModel. When this BrainModel represents all nodes in the surface, this value is the same as IndexCount. When this BrainModel represents only a subset of the surface's nodes, IndexCount will be less than this value.
  • Children Elements
    • NodeIndices (0..1)
    • VoxelIndicesIJK (0..1)
  • Text Content
  • Parent ElementMatrixIndicesMap.


ModelType Values
ModelType Description Constant Value
CIFTI_MODEL_TYPE_SURFACE Modeled using surface nodes. 1
CIFTI_MODEL_TYPE_VOXELS Modeled using voxels. 2



BrainStructure Values
BrainStructureType Constant Value
CIFTI_ACCUMBENS_LEFT 1
CIFTI_ACCUMBENS_RIGHT 2
CIFTI_AMYGDALA_LEFT 3
CIFTI_AMYGDALA_RIGHT 4
CIFTI_BRAIN_STEM 5
CIFTI_CAUDATE_LEFT 6
CIFTI_CAUDATE_RIGHT 7
CIFTI_CEREBELLUM 8
CIFTI_CEREBELLUM_LEFT 9
CIFTI_CEREBELLUM_RIGHT 10
CIFTI_CORTEX_LEFT 11
CIFTI_CORTEX_RIGHT 12
CIFTI_HIPPOCAMPUS_LEFT 13
CIFTI_HIPPOCAMPUS_RIGHT 14
CIFTI_OTHER 15
CIFTI_PALLIDUM_LEFT 16
CIFTI_PALLIDUM_RIGHT 17
CIFTI_PUTAMEN_LEFT 18
CIFTI_PUTAMEN_RIGHT 19
CIFTI_SUBCORTICAL_WHITE_MATTER_LEFT 20
CIFTI_SUBCORTICAL_WHITE_MATTER_RIGHT 21
CIFTI_THALAMUS_LEFT 22
CIFTI_THALMUS_RIGHT 23

CIFTI Element

  • Description – The root of the CIFTI metadata.
  • Attributes
    • Version – Indicates version of the CIFTI metadata. Value is “1”.
  • Children Elements
    • Matrix (1). At this time, there is only one Matrix child. Future versions of CIFTI may allow more than one Matrix child.
  • Text Content
  • Parent Element

Matrix Element

  • Description – Contains children elements that describe matrix.
  • Attributes
  • Children Elements
    • LabelTable (0..1)
    • MetaData (0..1)
    • MatrixIndicesMap (1..N)
    • Volume (0..1).
  • Text Content
  • Parent ElementCIFTI

MatrixIndicesMap Element

  • Description – Provides a mapping between matrix indices and the data associated with the matrix indices.
  • Attributes
    • AppliesToMatrixDimension – Lists the dimension(s) of the matrix to which this MatrixIndicesMap applies. The dimensions of the matrix start at zero (dimension zero is the rows, dimension one is the columns). 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.
    • TimeStep - Indicates amount of time between each timepoint.
    • TimeStepUnits – Indicates units of TimeStep.
  • Children Elements
    • BrainModel (0..N)
  • Text Content
  • Parent ElementMatrix.
IndicesMapToDataType
Value Description Constant Value
CIFTI_INDEX_TYPE_BRAIN_MODELS The dimension represents one or more brain models. 1
CIFTI_INDEX_TYPE_FIBERS The dimension represents a count of streamlines for a fiber. 2
CIFTI_INDEX_TYPE_PARCELS The dimension represents a parcellation scheme. 3
CIFTI_INDEX_TYPE_ TIME_POINTS The dimension represents timepoints. 4
Time Step Units
Value Description
NIFTI_UNITS_SEC Seconds
NIFTI_UNITS_MSEC Milliseconds
NIFTI_UNITS_USEC Microseconds

Label Element

  • Description – Associates a parcel name with a row and/or column index of the connectivity matrix. Content is the name of the label.
  • Attributes
    • Key – Corresponding index, starting at zero, of a row and/or column of the connectivity matrix.
    • 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.
    • X – X-coordinate of spatial location associated with the label. Value is floating point.
    • Y – Y-coordinate of spatial location associated with the label. Value is floating point.
    • Z – Z-coordinate of spatial location associated with the label. Value is floating point.
  • Children Elements
  • Text Content – Text of the label.
  • Parent ElementLabelTable

LabelTable Element

  • Description - Required when a MatrixIndicesMap’s type is Parcels.
  • Attributes
  • Children ElementsLabel (0..N)
  • Text Content
  • Parent ElementCIFTI

MD Element

  • Description – A single metadata entry consisting of a name and a value.
  • Attributes
  • Children Element
    • Name (1)
    • Value (1).
  • Content
  • Parent ElementMetaData.

MetaData Element

  • Description – Provides a simple method for user-supplied metadata that associates names with values.
  • Attributes
  • Children ElementsMD (0..N)
  • Content
  • Parent ElementMatrix.

Name Element

  • Description – Content is the name of a metadata entry.
  • Attributes
  • Children Elements
  • Content – Name of metadata element.
  • Parent ElementMD.

NodeIndices Element

  • Description – Contains a list of nodes indices for a BrainModel with ModelType equal to CIFTI_MODEL_TYPE_SURFACE.
  • Attributes
  • Children Elements
  • Content – The node indices of each node in the 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 ElementBrainModel.

TransformationMatrixVoxelIndicesIJKtoXYZ Element

  • Description – Contains a matrix that for conversion of Voxel IJK Indices to spatial XYZ coordinates (+X=>right, +Y=>anterior, +Z=>posterior). The resulting coordinate is at the CENTER of the voxel.
  • Attributes
    • DataSpace - Contains the name of the space of the voxels prior to application of the transformation matrix. Permitted values are listed in the table below.
    • TransformedSpace - Contains the name of the space of the voxels after application of the transformation of voxel IJK indices to spatial XYZ coordinates. Permitted values identical to those for DataSpace.
    • UnitsXYZ – Identifies the units of the spatial XYZ coordinates.
  • Children Elements
  • Text Content - Sixteen floating-point values, in row-major order, that form a 4x4 homogeneous transformation matrix.
  • Parent ElementVolume.
UnitsXYZ
Value Description
NIFTI_UNITS_MM Millimeters
NIFTI_UNITS_MICRON Microns


Valid Values for DataSpace and TransformedSpace
NIFTI_XFORM_UNKNOWN
NIFTI_XFORM_SCANNER_ANAT
NIFTI_XFORM_ALIGNED_ANAT
NIFTI_XFORM_TALAIRACH
NIFTI_XFORM_MNI_152


The matrix below is ordered in memory as “m1 m2 m3 m4 m5 m6 m7 m8 m9 m10 m11 m12 m13 m14 m15 m16”. The last row, elements [m13, m14, m15, and m16] will always be [0, 0, 0, 1].

 m1  m2  m3  m4
 m5  m6  m7  m8
 m9 m10 m11 m12
m13 m14 m15 m16

Value Element

  • Description – Content is the value of a metadata entry.
  • Attributes
  • Children Elements
  • Text Content – Value of metadata element.
  • Parent ElementMD.

Volume Element

  • Description – Provides information about the volume for any BrainModels that are modeled with voxels.
  • Attributes
    • VolumeDimensions – Three integer values that indicate original dimensions of the volume from which the voxels were extracted.
  • Children Elements
    • TransformationMatrixVoxelIndicesIJKtoXYZ (0..N).
  • Text Content
  • Parent ElementMatrix.

VoxelIndicesIJK Element

  • Description – Identifies the voxels that model a brain structure. Note that IndexCount, an attribute of the parent BrainModel element, indicates the number of voxels contained in the element.
  • Attributes
  • Children Elements
  • Text Content – IJK indices of each voxel in the brain model with each index separated by a whitespace character. There are three indices per voxel. The parent BrainModel’s IndexCount attribute indicates the number of triplets (IJK indices) in this element’s content.
  • Parent ElementBrainModel.

CIFTI File

The CIFTI file is a NIFTI-2 file with the CIFTI metadata placed into a NIFTI header extension. While NIFTI-2 files allow compression with GZIP, CIFTI files must not be compressed so that efficient, random access is feasible. In this initial version of CIFTI, a CIFTI file contains one, and only one, connectivity matrix. Future versions of CIFTI may contain more than one matrix.

The CIFTI XML metadata is stored in a NIFTI header extension. NIFTI_ECODE_CIFTI is the name for the CIFTI extension and its integer code is 32.

The matrix is always stored in row-major order. That is, the data is stored in a manner such that the highest increment the fastest. For example, the following 3 x 2 (3 rows, 2 columns) matrix is stored as the sequence of values “a b c d e f”.

a   b   c
d   e   f

NIFTI-2 Header Elements as used by CIFTI

The elements in a NIFTI-2 Header are listed in the table below. Many elements are not used by CIFTI and these elements are typically shown with a value of zero. For example, a matrix for transforming voxel indices to coordinates is contained in the CIFTI XML metadata. As a result, the transformation information in the NIFTI-2 header (qform_code, quatern_b, srow_x, etc.) are not used by CIFTI.

NIFTI Header Element Data Type Offset Values
sizeof_hdr int32 0 540
magic [8] int8 4 ‘n’, ’+’, ‘2’, ‘\0’,’\r’,’\n’,’\032’,’\n’

or (0x6E,0x2B,0x32,0x00,0x0D,0x0A,0x1A,0x0A)

datatype int16 12 See file formats
bitpix int16 14 See file formats
dim[8] int64 16 See file formats
intent_p1 double 80 0
intent_p2 double 88 0
intent_p3 double 96 0
pixdim[8] double 104 0,1,1,1,1,1,1,1
vox_offset int64 168 Offset of data, minimum=544
scl_slope double 176 1
scl_inter double 184 0
cal_max double 192 0
cal_min double 200 0
slice_duration double 208 0
toffset double 216 0
slice_start int64 224 0
slice_end int64 232 0
descrip[80] int8 240 All zeros
aux_file[24] int8 320 All zeros
qform_code int32 344 NIFTI_XFORM_UNKNOWN (0)
sform_code int32 348 NIFTI_XFORM_UNKNOWN (0)
quatern_b double 352 0
quatern_c double 360 0
quatern_d double 368 0
qoffset_x double 376 0
qoffset_y double 384 0
qOffset_z double 392 0
srow_x[4] double 400 0,0,0,0
srow_y[4] double 432 0,0,0,0
srow_z[4] double 464 0,0,0,0
slice_code int32 496 0
xyzt_units int32 500 0xC (seconds, millimeters)
intent_code int32 504 See file formats
intent_name[16] int8 508 See file formats
dim_info int8 524 0
unused_str[15] int8 525 All zeros
540 End of the header

Following the NIFTI header are four bytes that indicate the presence of (or lack of) NIFTI header extensions. If the first byte is non-zero, it indicates that on or more NIFTI header extensions follow these four bytes. If the first byte is zero, no NIFTI header extensions are present. The remaining three bytes always contain a value of zero. Since a NIFTI header extension is used for CIFTI XML metadata, these four bytes will be the values 1,0,0,0.

Dense Connectivity CIFTI File

The dense connectivity file format contains connectivity measurements between high resolution brainordinates. The connectivity matrix is of size M x N where M and N are brainordinates from one or more brain structures. A brain model occupies a contiguous sequence of rows (and/or columns) of the matrix and each row contains the connectivity measurement data for a single brainordinate. The filename extension of a dense connectivity file is “.dconn.nii”.


Dense Connectivity NIFTI Header Elements

NIFTI Header Element Value
dim 6,1,1,1,1,M,N,1
intent_code NIFTI_INTENT_CONNECTIVITY_DENSE
datatype NIFTI_TYPE_FLOAT32
bitpix 32
intent_name ConnDense (remaining elements are zeros).

Dense Time Series CIFTI File

The dense time series contains data collected over time at brainordinates. Common uses of this dense time series file are for region-of-interest analysis and two-dimensional time-series analysis. Since the most common query is to access all data for a brainordinate, the data for each brainordinate must be stored in the rows of the matrix and the timepoints must be stored in the columns of the matrix. Thus, a MatrixIndicesMap will have its AppliesToMatrixDimension attribute set to 0 and its IndicesMapToDataType attribute set to CIFTI_INDEX_TYPE_BRAIN_MODELS. A second MatrixIndicesMap will have its AppliesToMatrixDimension attribute set to 1 and its IndicesMapToDataType attribute set to CIFTI_INDEX_TYPE_TIME_POINTS. In the matrix, the number of rows (M) is equal to the number of brainordinates and the number of columns (N) is equal to the number of timepoints. The filename extension of a dense time series file “.dtseries.nii”.

Dense Time Series NIFTI Header Elements

NIFTI Header Element Value
dim 6,1,1,1,1,M,N,1
intent_code NIFTI_INTENT_CONNECTIVITY_DENSE_TIME
datatype NIFTI_TYPE_FLOAT32
bitpix 32
intent_name ConnDenseTime (remaining elements are zeros).

Parcellated Connectivity File

The parcellated connectivity format contains connectivity measurements between parcels (distinct, identified regions) in the brain. These regions may be identified by architectonics, function, or other methods. Both the number of rows (M) and columns (N) in the connectivity matrix are equal to the number of parcels. There is one MatrixIndicesMap with its IndicesMapToDataType set to CIFTI_INDEX_TYPE_PARCELS and its AppliesToMatrixDimension set to “0,1”. The proposed filename extension for a parcellated connectivity matrix is “.pconn.nii”.

A LabelTable is required in the CIFTI metadata for a parcellated connectivity file. This LabelTable provides a name for each of the parcels and thus it contains “number of parcels” labels. Therefore, for example, a label with a key of two identifies the parcel associated with a matrix row (or column) with an index of two (indices start at zero).

One may want to associate coordinates with parcels. For this purpose, attributes of the Label element are available for X-, Y-, and Z-coordinates. One type of coordinates contains the center of gravity for each parcel’s stereotaxic brainordinates, likely used for simultaneous visualization with a surface.

The matrix in the Parcellated Connectivity File is essentially an adjacency matrix representation of a complete graph. In a complete graph, all nodes connect to all nodes. The parcels represent the nodes of the graph and the matrix contains the weights (connectivity measurement) of the edges (connections) between the parcels.

Parcellated Connectivity NIFTI Header Elements

NIFTI Header Element Value
dim 6,1,1,1,1,M,N,1
intent_code NIFTI_INTENT_CONNECTIVITY_PARCELLATED
datatype NIFTI_TYPE_FLOAT32
bitpix 32
intent_name ConnParcels (remaining elements are zeros).

Parcellated Time Series File

The Parcellated Time Series is similar to a Dense Time Series matrix except that the first dimension is Parcels. Thus, the first MatrixIndicesMap will have its AppliesToMatrixDimension attribute set to 0, its IndicesMapToDataType attribute set to CIFTI_INDEX_TYPE_PARCELS. A second MatrixIndicesMap will have its AppliesToMatrixDimension attribute set to 1 and its IndicesMapToDataType attribute set to CIFTI_INDEX_TYPE_TIME_POINTS. The number of rows (M) is the number of Parcels and the number of columns (N) is the number of timepoints. The filename extension is “ptseries.nii”.

Parcellated Time Series NIFTI Header Elements

NIFTI Header Element Value
dim 6,1,1,1,1,M,N,1
intent_code NIFTI_INTENT_CONNECTIVITY_PARCELLATED_TIME
datatype NIFTI_TYPE_FLOAT32
bitpix 32
intent_name ConnParcelTime (remaining elements are zeros).

Trajectory Connectivity CIFTI File

The Trajectory Connectivity matrix is similar to a Dense Connectivity matrix in that it contains connectivity information between pairs of brainordinates. However, a third dimension is added to the matrix permitting multiple measurements between each pair of brainordinates. The trajectory matrix typically represents connectivity seeded from grayordinate surfaces nodes, represented in the first dimension, or rows (M), to whiteordinate volume voxels, represented in the second dimension, or columns (N), although rows need not be surface nodes only, the columns must be white matter volume voxels only. The third dimension (P) typically contains four elements. The first three elements are the number of probabilistic streamlines that chose each fiber orientation in the whiteordinate using the grayordinate as a seed. The fourth element is the average trajectory length from the grayordinate to the whiteordinate. In the future, the third dimension may be greater than four when analysis methods support more than three fiber per whiteordinate volume voxels. The filename extension is “.traj.nii”.

Trajectory NIFTI Header Elements

NIFTI Header Element Value
dim 7,1,1,1,1,M,N,P
intent_code NIFTI_INTENT_CONNECTIVITY_TRAJECTORY
datatype NIFTI_TYPE_FLOAT32
bitpix 32
intent_name ConnTraj (remaining elements are zeros).

Sparse and Compressed Matrix Representations

Since the dense connectivity matrix may be very large, a sparse or compressed representation of the matrix may be desirable for connectivity matrices that are inherently sparse, such as tractography matrices. A sparse matrix is a matrix containing a large percentage of elements with the value zero. Data compression involves encoding repeated patterns of data with simpler representations that are later reversed when the data is decompressed. The need to access the matrix by row limits the available sparse or compressed method representations.

Compressed Row Storage

Compressed Row Storage (CRS) is a sparse matrix representation that represents the non-zero matrix elements using several one-dimensional arrays. The first array, Row Offsets, contains “number of rows” elements, is indexed by row index (which starts at zero), and contains the index (starting at zero) of the row’s first non-zero element in both the Matrix Data and the Column Indices array. To get the number of non-zero elements in a row, one subtracts the value of the row’s offset from the offset of the next row. However, for the last row, its number of non-zero elements is found by subtracting its row offset from the number of non-zero elements. The second array, Column Indices, contains the column indices corresponding to each of the non-zero matrix elements in the Matrix Data array. The third array, Matrix Data, contains the non-zero elements of the matrix in left-to-right, top-to-bottom (row-major) order.

When Compressed Row Storage is used, the dimensions in the NIFTI header will not contain the true dimensions of the matrix. Instead, the dimension in the NIFTI header will be 5,1,1,1,1,N,1,1 where N is the length, in bytes, of the compressed matrix representation. Note that the NIFTI data type is bytes (NIFTI_TYPE_INT8).


NIFTI Header Element Value
dim 5,1,1,1,1,N,1,1
intent_code NIFTI_INTENT_TWO_DIM_SPARSE_CRS
datatype NIFTI_TYPE_INT8
bitpix 8


Compressed Data Item Data Type Count Compressed Description
IntentCode int64_t 1 Actual Intent code for data (intent code in NIFTI header just indicates compressed data).
Matrix Dimensions int64_t 8 Dimensions of matrix as per NIFTI specification (note: the dimensions in the NIFTI header contains the size of the compressed data in a one-dimensional vector).
Matrix Data Type int64_t 1 Data type in matrix (valid values are any NIFTI_TYPE…).
Number of Non-Zero Elements int64_t 1 Number of non-zero elements in the data array.
Row Offsets int64_t Number of matrix rows. (Matrix Dimensions[5]) Offset from beginning of data array to first non-zero element in the row.
Column Indices of Non-Zero Elements int64_t Number of non-zero elements. Column index for each non-zero element in the data array.
Matrix Data “Matrix Data Type” value “Number of non-zero elements” Non-zero elements in the matrix.


Example of Compressed Row Storage

Matrix (6 x 3) 
0   5   9   33     0    0
1   0   0    0    24    0
0   0   0    8     0    2


NIFTI Header Element Value(s)
dim 5,1,1,1,1,196,1,1
intent_code NIFTI_INTENT_TWO_DIM_SPARSE_CRS
datatype NIFTI_TYPE_INT8
bitpix 8


Compressed Data Item Count Contents
Intent Code 1 NIFTI_INTENT_CONNECTIVITY_...
Matrix Dimensions 8 6,1,1,1,1,6,3,1
Matrix Data Type 1 NIFTI_TYPE_FLOAT32
Number of Non-Zero Elements 1 7
Row Offsets 3 0,3,5,
Column Indices of Non-Zero Elements 7 1,2,3,0,4,3,5
Matrix Data 7 5, 9, 33, 1, 24, 8,2

GZIP Compression

An alternative to a sparse matrix representation is to use data compression. NIFTI already uses GZIP compression, however, it compress the entire file. Since fast access to individual rows of the matrix is needed, compression of the entire file is not an option. Instead, one could compress each row individually. Using row compression also requires one to store the offset of each matrix row in the data. The compressed length of a row is obtained by subtracting the offset of a row from the offset of the next row.


Compression information for row compression with GZIP

Compressed Data Item Data Type Count Compressed Description
IntentCode Int64_t 1 Actual Intent code for data (intent code in NIFTI header just indicates compressed data).
Dimensions int64_t 8 Dimensions of matrix as per NIFTI specification. The dimensions in the NIFTI header contains the size of the compressed data in a one-dimensional vector.
Rows Offsets int64_t Number of Rows + One (Dimensions[5]+1) Offset of row’s compressed data, in bytes, in Matrix Data.
Matrix Data NIFTI_TYPE_INT8 Row Offsets[Number of Rows] Bytes containing compressed row data.

Spatial Vector File (Probably not needed?)

A spatial vector consists of a three-dimensional origin and three-dimensional vector components. The magnitude of the vector is included in the vector components.

A spatial vector file contains (N) vectors with six elements per vector. The first three elements are the origin of the vector and the second three elements are the vector components with magnitude included.

NIFTI Header Element Value(s)
dim 6,1,1,1,1,N,6,1
intent_code NIFTI_INTENT_SPATIAL_VECTOR
datatype NIFTI_TYPE_FLOAT32
bitpix 32
intent_name SpatialVector (remaining elements are zeros).

Character Encodings

Character (String) data uses UTF-8 Encoding. ASCII is a valid subset of UTF-8.

NIFTI Changes and Support

New NIFTI Intent Codes

The following NIFTI Intent codes will be needed:

NIFTI Intent Code Constant Value
NIFTI_INTENT_CONNECTIVITY_DENSE 2001
NIFTI_INTENT_CONNECTIVITY_DENSE_TIME 2002
NIFTI_INTENT_CONNECTIVITY_PARCELLATED 2003
NIFTI_INTENT_CONNECTIVITY_PARCELLATED_TIME 2004
NIFTI_INTENT_CONNECTIVITY_CONNECTIVITY_TRAJECTORY 2005


One or more of these new NIFTI Intent codes may be needed for compressed data:

NIFTI Intent Code Constant Value
NIFTI_INTENT_COMPRESSED_SPARSE_CRS 2006
NIFTI_INTENT_COMPRESSED_GZIP_ROWS 2007

CIFTI Header Extension Code

In a NIFTI volume file, the CIFTI header extension is identified by the header extension code NIFTI_ECODE_CIFTI which has the numeric value 32.

References

Compressed Row Strorage

CIFTI

GIFTI

NIFTI

NITRC

ISO-Date

UUID

UTF8

nifti1.h

The NIFTI-1 Data Format Data Format Working Group

Appendices

Example CIFTI Metadata In XML Format

Example Dense Connectivity Metadata XML Format

This example Dense Connectivity Metadata contains symmetric connectivity data for two brain structures, a three node left cerebral cortex and a two voxel left thalamus. Since the connectivity data is symmetric in this example, there is one MatrixIndicesMap with its AppliesToMatrixDimension set to “0,1”.

<CIFTI Version="1.0"
       NumberOfMatrices="1">
   <Matrix>
      <MetaData>
         <MD>
            <Name>UserName</Name>
            <Value>Joe User</Value>
         </MD>
      </MetaData>
      <Volume VolumeDimensions="176,208,176">
          <TransformationMatrixVoxelIndicesIJKtoXYZ
              DataSpace="NIFTI_XFORM_SCANNER_ANAT"
              TransformedSpace="NIFTI_XFORM_TALAIRACH"
              UnitsXYZ="NIFTI_UNITS_MM">
              -2.0   0.0  0.0  126.0
              0.0  -2.0  0.0  128.0
              0.0   0.0  2.0  -66.0
              0.0   0.0  0.0    1.0
          </TransformationMatrixVoxelIndicesIJKtoXYZ>
      </Volume>
      <MatrixIndicesMap AppliesToMatrixDimension="0,1"
                        IndicesMapToDataType="CIFTI_INDEX_TYPE_BRAIN_MODELS">
         <BrainModel IndexOffset="0"
                     IndexCount="3"
                     ModelType="CIFTI_MODEL_TYPE_SURFACE"
                     BrainStructure="NIFTI_STRUCTURE_CORTEX_LEFT"
                     SurfaceNumberOfNodes="7">
             <NodeIndices>
                 0 2 4
             </NodeIndices>
         </BrainModel>
         <BrainModel IndexOffset="3"
                     IndexCount="2"
                     ModelType="CIFTI_MODEL_TYPE_VOXELS"
                     BrainStructure="NIFTI_STRUCTURE_THALAMUS_LEFT">
            <VoxelIndicesIJK>
               27 38 40
               27 39 40
            </VoxelIndicesIJK>
         </BrainModel>
      </MatrixIndicesMap>
   </Matrix>
</CIFTI>

Example Dense Time Series Metadata XML Format

This example Dense Time Series Metadata contains data for two brain structures, a three node left cerebral cortex and a two voxel left thalamus in the first dimension. The second dimension contains three time points with two seconds between each time point.


<CIFTI Version="1.0"
    NumberOfMatrices="1">
    <Matrix>
        <MetaData>
            <MD>
                <Name>UserName</Name>
                <Value>Joe User</Value>
            </MD>
        </MetaData>
        <Volume VolumeDimensions="176,208,176">
            <TransformationMatrixVoxelIndicesIJKtoXYZ
                DataSpace="NIFTI_XFORM_SCANNER_ANAT"
                TransformedSpace="NIFTI_XFORM_TALAIRACH"
                UnitsXYZ="NIFTI_UNITS_MM">
                -2.0   0.0  0.0  126.0
                0.0  -2.0  0.0  128.0
                0.0   0.0  2.0  -66.0
                0.0   0.0  0.0    1.0
            </TransformationMatrixVoxelIndicesIJKtoXYZ>
        </Volume>
        <MatrixIndicesMap AppliesToMatrixDimension="0"
            IndicesMapToDataType="CIFTI_INDEX_TYPE_BRAIN_MODELS">
            <BrainModel IndexOffset="0"
                IndexCount="3"
                ModelType="CIFTI_MODEL_TYPE_SURFACE"
                BrainStructure="NIFTI_STRUCTURE_CORTEX_LEFT"
                SurfaceNumberOfNodes="7">
                <NodeIndices>
                    0 2 4
                </NodeIndices>
            </BrainModel>
            <BrainModel IndexOffset="3"
                IndexCount="2"
                ModelType="CIFTI_MODEL_TYPE_VOXELS"
                BrainStructure="NIFTI_STRUCTURE_THALAMUS_LEFT">
                <VoxelIndicesIJK>
                    27 38 40
                    27 39 40
                </VoxelIndicesIJK>
            </BrainModel>
        </MatrixIndicesMap>
        <MatrixIndicesMap AppliesToMatrixDimension="1"
            IndicesMapToDataType="CIFTI_INDEX_TYPE_TIME_POINTS"
            TimeStep="2.0"
            TimeStepUnits="NIFTI_UNITS_SEC">
        </MatrixIndicesMap>
    </Matrix>
</CIFTI>

Example Parcellated Connectivity Metadata XML Format

This Parcellated Connectivity Metadata contains a partitioning scheme with five parcels, V1, V2, V3, IT, and LIP. Names and color components for each parcel are provided in the Label elements of the LabelTable. Also present in each label are optional XYZ coordinates that may be the approximate stereotaxic location of the parcel.

<CIFTI Version="1.0"
       NumberOfMatrices="1">
   <Matrix>
      <MetaData>
         <MD>
            <Name>UserName</Name>
            <Value>Joe User</Value>
         </MD>
      </MetaData>
      <LabelTable>
         <Label Key="0" Red="1.0" Green="0.0" Blue="0.0" Alpha="1.0"
                X="3.7",  Y="-46.1" Z="5.2">V1</Label>
         <Label Key="1" Red="0.0" Green="1.0" Blue="0.0" Alpha="1.0"
                X="9.7",  Y="-38.5" Z="2.1">V2</Label>
         <Label Key="2" Red="1.0" Green="0.0" Blue="1.0" Alpha="1.0"
                X="4.1",  Y="-44.5" Z="4.3">V3</Label> 
         <Label Key="3" Red="0.0" Green="0.0" Blue="1.0" Alpha="1.0"
                X="9.7",  Y="-24.1" Z="12.7">IT</Label>
         <Label Key="4" Red="0.0" Green="1.0" Blue="1.0" Alpha="1.0"
                X="10.9",  Y="-17.9" Z="18.2">LIP</Label>
      </LabelTable>
      <MatrixIndicesMap AppliesToMatrixDimension="0,1"
                        IndicesMapToDataType="CIFTI_INDEX_TYPE_PARCELS">
      </MatrixIndicesMap>
   </Matrix>
</CIFTI>

Example Parcellated Time Series Metadata XML Format

This parcellated time series metadata contains five parcels in the first dimension and three timepoints in the second dimension with two seconds between each timepoint.

<CIFTI Version="1.0"
       NumberOfMatrices="1">
   <Matrix>
      <MetaData>
         <MD>
            <Name>UserName</Name>
            <Value>Joe User</Value>
         </MD>
      </MetaData>
      <LabelTable>
         <Label Key="0" Red="1.0" Green="0.0" Blue="0.0" Alpha="1.0"
                X="3.7",  Y="-46.1" Z="5.2">V1</Label>
         <Label Key="1" Red="0.0" Green="1.0" Blue="0.0" Alpha="1.0"
                X="9.7",  Y="-38.5" Z="2.1">V2</Label>
         <Label Key="2" Red="1.0" Green="0.0" Blue="1.0" Alpha="1.0"
                X="4.1",  Y="-44.5" Z="4.3">V3</Label> 
         <Label Key="3" Red="0.0" Green="0.0" Blue="1.0" Alpha="1.0"
                X="9.7",  Y="-24.1" Z="12.7">IT</Label>
         <Label Key="4" Red="0.0" Green="1.0" Blue="1.0" Alpha="1.0"
                X="10.9",  Y="-17.9" Z="18.2">LIP</Label>
      </LabelTable>
      <MatrixIndicesMap AppliesToMatrixDimension="0"
                        IndicesMapToDataType="CIFTI_INDEX_TYPE_PARCELS">
      </MatrixIndicesMap>
      <MatrixIndicesMap AppliesToMatrixDimension="1"
                        IndicesMapToDataType="CIFTI_INDEX_TYPE_TIME_POINTS"
                        TimeStep="2.0"
                        TimeStepUnits="NIFTI_UNITS_SEC">
      </MatrixIndicesMap>
   </Matrix>
</CIFTI>

Example Trajectory Metadata XML Format

This example trajectory metadata contains a matrix that provides connectivity from all nodes in a left cortical surface to all voxels in white matter. There are four measurements per node/voxel connectivity.

<CIFTI Version="1.0"
       NumberOfMatrices="1">
   <Matrix>
      <MetaData>
         <MD>
            <Name>UserName</Name>
            <Value>Joe User</Value>
         </MD>
      </MetaData>
      <Volume VolumeDimensions="176,208,176">
           <TransformationMatrixVoxelIndicesIJKtoXYZ
               DataSpace="NIFTI_XFORM_SCANNER_ANAT"
               TransformedSpace="NIFTI_XFORM_TALAIRACH"
               UnitsXYZ="NIFTI_UNITS_MM">
               -2.0   0.0  0.0  126.0
               0.0  -2.0  0.0  128.0
               0.0   0.0  2.0  -66.0
               0.0   0.0  0.0    1.0
           </TransformationMatrixVoxelIndicesIJKtoXYZ>
      </Volume>
      <MatrixIndicesMap AppliesToMatrixDimension="0"
                        IndicesMapToDataType="CIFTI_INDEX_TYPE_BRAIN_MODELS">
         <BrainModel IndexOffset="0"
                     IndexCount="3"
                     ModelType="CIFTI_MODEL_TYPE_SURFACE"
                     BrainStructure="NIFTI_STRUCTURE_CORTEX_LEFT",
                     SurfaceNumberOfNodes="7">
             <NodeIndices>
                 0 2 4
             </NodeIndices>
         </BrainModel>
      </MatrixIndicesMap>
      <MatrixIndicesMap AppliesToMatrixDimension="1"
                        IndicesMapToDataType="CIFTI_INDEX_TYPE_BRAIN_MODELS">
         <BrainModel IndexOffset="0"
                     IndexCount="2"
                     ModelType="CIFTI_MODEL_TYPE_VOXELS"
                     BrainStructure="NIFTI_STRUCTURE_WHITE_MATTER">
            <VoxelIndicesIJK>
               27 38 40
               27 39 40
            </VoxelIndicesIJK>
         </BrainModel>
      </MatrixIndicesMap>
      <MatrixIndicesMap AppliesToMatrixDimension="2"
                        IndicesMapToDataType="CIFTI_INDEX_TYPE_FIBERS">
      </MatrixIndicesMap>
   </Matrix>
</CIFTI>

Personal tools
Sums Database