read.cifti: Read a CIFTI-2 file.
In freesurferformats: Read and Write 'FreeSurfer' Neuroimaging File Formats

read.cifti

R Documentation

Read a CIFTI-2 file.

Description

Read a CIFTI-2 file, i.e. its XML metadata (see read.cifti.header) and its data values. The data are returned as an array in the order in which they are stored in the file: the first array dimension is CIFTI matrix dimension 0 (which Connectome Workbench calls the ROW dimension), the second one is matrix dimension 1 (the COLUMN dimension). This is the same order that other CIFTI implementations use for their data arrays.

For a dense file like a .dscalar, dimension 0 holds the scalars (maps) and dimension 1 the brainordinates (surface vertices and volume voxels), so the data matrix has one row per map and one column per grayordinate. For a .dtseries, dimension 0 holds the series, so the matrix has one row per series point. The functions cifti.series.info and cifti.map.for.dim tell you what a dimension is; never conclude it from the file name. Use cifti.structure.data to extract the data of a brain structure, which is the more convenient interface for most purposes and the one that the read.fs.*.cifti functions are built on.

Reading a file twice (once for the header, once for the data) is not necessary to extract a single structure, but it is what this function does; use it if you need more than one structure or the raw matrix.

Usage

read.cifti(filepath, rows = NULL, columns = NULL)

Arguments

`filepath`	character string, the path to a CIFTI-2 file. Note that a CIFTI-2 file is a NIFTI-2 file, but its data are not a 3D volume; gzipped CIFTI files do not exist (the format forbids compression so that random access remains possible).
`rows`	integer vector or `NULL`, the indices of matrix dimension 0 to read. Indices are 1-based, like everywhere else in R, and they refer to the rows of the returned array, i.e. to the first CIFTI matrix dimension. Use `NULL` (the default) to read all of them. Note that this selection is applied after reading the whole matrix: use `read.cifti.rows` if the file is too large for that.
`columns`	integer vector or `NULL`, the indices of matrix dimension 1 to read, i.e. the columns of the returned array. This is the matrix dimension that holds the brainordinates of a dense file (the grayordinates of a `.dscalar`, `.dtseries` or `.dlabel`), and it is also one of the two dimensions that hold them in a connectome file like a `.dconn`. Selecting columns avoids reading the rest of the file, which is the only practical way to read a small part of a huge file like a `.dconn` (9 to 38 GB): for a 2-dimensional matrix, one contiguous block of the file holds all values of one column. Note that `rows` does not have this property, selecting rows still reads all values of the file.

Value

a named list with the entries 'header' (an fs.cifti object, see read.cifti.header) and 'data' (the numeric or integer array). The array dimensions are named with the axis labels of the corresponding matrix dimensions, see cifti.dim.labels. The object has class 'fs.cifti.data'.

Note

The generic readers read.fs.morph and read.fs.volume dispatch on the file name and would therefore match a CIFTI-2 file (which is a NIFTI-2 file), so they detect this case and stop with a pointer to this function and the other CIFTI readers instead of returning the values of the matrix in an order that means nothing.

Examples

cifti_file <- system.file("extdata", "cifti", "tiny.dscalar.nii", package = "freesurferformats")
cii <- read.cifti(cifti_file)
dim(cii$data)
# The first 3 grayordinates of the first map:
cii$data[1, 1:3]

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