read.cifti.header: Read CIFTI-2 header (XML metadata).

In freesurferformats: Read and Write 'FreeSurfer' Neuroimaging File Formats

Read CIFTI-2 header (XML metadata).

Description

Read the metadata of a CIFTI version 2 file, i.e. the XML document that describes everything except the actual data values: the matrix dimensions and their meaning, the brain models (surface vertices and volume voxels), the parcels, the series information, and the label tables. CIFTI-2 files are NIFTI-2 files that store this XML in a NIFTI v2 header extension with the extension code 32. Use read.cifti to read the data values as well (not implemented yet), or the accessor functions cifti.structures, cifti.parcels, cifti.series.info and cifti.label.table to inspect the result.

Usage

read.cifti.header(filepath)

Arguments

filepath

character string, the path to a CIFTI-2 file (usually one of .dscalar.nii, .dtseries.nii, .dlabel.nii, .dconn.nii, .pscalar.nii, .ptseries.nii, .pconn.nii, .dpconn.nii or .pdconn.nii). Note that this is not a NIFTI file, despite the .nii part. Gzipped CIFTI files are not supported, because the CIFTI-2 format forbids compression.

Value

an fs.cifti object, a named list with the entries: 'filepath' (the file path), 'niiheader' (the NIFTI-2 header as returned by read.nifti2.header), 'version' (the CIFTI version, always '2' for files that can be read), and 'matrix', a named list with the entries 'metadata' (the matrix-level metadata, a named list of character strings, in file order; the names may repeat) and 'indices_maps' (a list of the MatrixIndicesMap elements, see below), plus 'dim_sizes' (the integer sizes of the matrix dimensions; these are stored in entries 5, 6, ... of the dim field of the NIFTI-2 header, and R index vectors are 1-based, so the 6th entry of dim holds matrix dimension 0).

Each element of indices_maps is a named list with the entries: 'dims' (integer vector, the 0-based matrix dimensions this mapping applies to; it has several entries for files like a .dconn, where one mapping describes both dimensions), 'applies_to' (the same as a character string, as found in the file), 'type' (character string, one of 'CIFTI_INDEX_TYPE_BRAIN_MODELS', 'CIFTI_INDEX_TYPE_PARCELS', 'CIFTI_INDEX_TYPE_SERIES', 'CIFTI_INDEX_TYPE_SCALARS' or 'CIFTI_INDEX_TYPE_LABELS'), 'size' (integer vector, the size of the dimension(s) from 'dims'), 'series' (a list with entries 'number_of_series_points', 'start', 'step', 'exponent' and 'unit', for series mappings; NULL otherwise), 'surfaces' (a list of lists with entries 'brain_structure' and 'surface_number_of_vertices'), 'volumes' (a list of lists with entries 'dimensions' (integer vector of length 3), 'meter_exponent' and 'transformation_matrix' (4x4 numeric matrix, row-major as in the file, mapping 0-based voxel indices to coordinates in units of 10^meter_exponent)), 'brain_models' (a list of lists with entries 'index_offset' (0-based), 'index_count', 'model_type', 'brain_structure', 'surface_number_of_vertices' (surfaces only, NA otherwise), 'vertex_indices' (0-based integer vector, or NULL if all vertices of the surface are used) and 'voxel_indices_ijk' (an n x 3 integer matrix of 0-based voxel indices, or NULL) ), 'parcels' (a list of lists with entries 'index' (0-based position in the list), 'name', 'vertices' (named list of 0-based vertex index vectors, named by the canonical brain structure name, e.g. 'CORTEX_LEFT') and 'voxel_indices_ijk'), and 'named_maps' (a list of lists with entries 'name', 'metadata' and 'labels'; 'labels' is a data.frame with the columns 'key', 'red', 'green', 'blue', 'alpha', 'label', 'x', 'y' and 'z', see cifti.label.table).

Note

This function performs structural validation of the XML and stops with a descriptive error if the file is not a CIFTI-2 file, if the XML is inconsistent (e.g., index ranges that do not cover the data, or a number of parcels that does not match the matrix dimension), or if a file in the outdated CIFTI-1 format is passed (which has to be converted first, see the error message).

See Also

Other cifti functions: cifti.axis.brain.models(), cifti.axis.from.template(), cifti.axis.labels(), cifti.axis.parcels(), cifti.axis.parcels.from.annot(), cifti.axis.scalars(), cifti.axis.series(), cifti.brain.model.surface(), cifti.brain.model.volume(), cifti.dim.labels(), cifti.file.type.for.axes(), cifti.grayordinates(), cifti.header.from.axes(), cifti.label.table(), cifti.parcel(), cifti.parcels(), cifti.series.info(), cifti.structure.data(), cifti.structures(), cifti.volume(), print.fs.cifti(), print.fs.cifti.data(), print.fs.connectome(), read.cifti(), read.cifti.rows(), read.fs.connectome.cifti(), write.cifti(), write.fs.connectome.cifti(), write.fs.morph.cifti(), write.fs.parcellated.cifti(), write.fs.parcellation.cifti(), write.fs.series.cifti()

Examples

cifti_file <- system.file("extdata", "cifti", "tiny.dscalar.nii", package = "freesurferformats")
cii <- read.cifti.header(cifti_file)
cii
cii$matrix$indices_maps[[1]]$type
cifti.structures(cii, dim = 1L)

freesurferformats documentation built on Sept. 25, 2026, 1:07 a.m.