freesurferformats (version 1.1.0)

read.fs.morph.cifti: Read surface morphometry data from CIFTI dscalar files.

Description

Read the data from a CIFTI dscalar file (or any other CIFTI-2 file with a single brainordinate dimension, e.g. a '.dtseries') and reconstruct it for one brain structure, based on the metadata like vertex counts, indices and offset in the CIFTI file. The result is a vector with one value per vertex of the surface.

Usage

read.fs.morph.cifti(
  filepath,
  brain_structure = "CIFTI_STRUCTURE_CORTEX_LEFT",
  data_column = 1L
)

Value

The reconstructed data for the given surface, one value per vertex in the surface. The value for vertices which did not have a value in the CIFTI data is set to NA. Note that the result always has the length of the complete surface: CIFTI files like the ones used in the HCP leave out the medial wall vertices, and the result reports those as NA.

Arguments

filepath

character string, the full path to a file in CIFTI 2 format, should end with '.dscalar.nii'. Note that this is NOT a NIFTI file, despite the '.nii' part. It uses a CIFTIv2 header though. See the spec for details. An 'fs.cifti' object from read.cifti.header or an 'fs.cifti.data' object from read.cifti may be given instead of a path (this is faster if you need the data of several structures). An object created by the 'cifti' package is still accepted for backwards compatibility.

brain_structure

character string or integer, the brain structure for which the data should be extracted from the file. Can be a CIFTI brain structure string (one of 'CIFTI_STRUCTURE_CORTEX_LEFT' or 'CIFTI_STRUCTURE_CORTEX_RIGHT'), or simply one of 'lh', 'rh' (which are used as aliases for the former). If you specify 'both', the concatenated data for 'lh' (first) and 'rh' will be returned, but you will get no information on hemi boundaries. If it is an integer, it will be interpreted as an index into the list of structures within the CIFTI file, use with care.

data_column

integer, the data column to return. A CIFTI file can contain several measures in different data columns (e.g., cortical thickness and surface area) in a single file. This specifies which column/measure you want. The columns are not named, so you will need to know this in advance if the file has several measures.

References

See https://www.nitrc.org/forum/attachment.php?attachid=341&group_id=454&forum_id=1955 for the CIFTI 2 file format spec. See https://www.nitrc.org/projects/cifti/ for more details on CIFTI, including example files.

Examples

cifti_file <- system.file("extdata", "cifti", "tiny.dscalar.nii", package = "freesurferformats")
morph_lh <- read.fs.morph.cifti(cifti_file, "lh")
length(morph_lh)
morph_lh2 <- read.fs.morph.cifti(cifti_file, "lh", 2L)
morph_both <- read.fs.morph.cifti(cifti_file, "both")