freesurferformats (version 1.1.0)

write.cifti: Write a CIFTI-2 file.

Description

Write a data matrix and its axes to a CIFTI-2 file, i.e. a NIFTI-2 file with the CIFTI-2 XML in a header extension. The axes describe what the matrix dimensions contain; they can be given explicitly (see the cifti.axis.*() functions), taken from a template file (recommended for real data, see cifti.axis.from.template), or both.

The file type (and thus the NIFTI intent code that identifies it) follows from the axes: a scalars dimension and a brain model dimension make a .dscalar file, a series dimension and a brain model dimension a .dtseries file, and so on. If the file name has one of the standard CIFTI extensions, the axes have to match it: a file named .pdconn.nii whose dimensions are not (brain models, parcels) is an error, not a warning, because the file name is the only hint that other software has about the content.

Usage

write.cifti(filepath, data, axes = NULL, template = NULL, metadata = NULL)

Value

the axes that were written, invisibly. The file is written as a side effect.

Arguments

filepath

character string, the path of the file to write.

data

numeric or integer matrix or array, the data. The dimensions have to match the sizes of the axes, and the order is the same as for read.cifti: the first array dimension is CIFTI matrix dimension 0. A plain vector is interpreted as an array of that length (which is what you want for a file with a single map, e.g. a .dscalar with one map).

axes

list of axes, one per matrix dimension, or NULL (in which case template has to be given). See cifti.header.from.axes for the naming rules.

template

character string (the path of a CIFTI-2 file), an fs.cifti or an fs.cifti.data object or NULL. The axes of this file are used for the dimensions that axes does not describe, and also for the metadata if metadata is NULL.

metadata

named character vector or named list, or NULL, the matrix metadata to write. The default writes the metadata of the template file, if there is one, so that the provenance of the source data is kept.

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.header(), read.cifti.rows(), read.fs.connectome.cifti(), write.fs.connectome.cifti(), write.fs.morph.cifti(), write.fs.parcellated.cifti(), write.fs.parcellation.cifti(), write.fs.series.cifti()

Examples

axis_brain <- cifti.axis.brain.models(list(
  cifti.brain.model.surface("lh", 10L),
  cifti.brain.model.surface("rh", 12L)))
data_matrix <- matrix(1:22, nrow = 1L)
out_file <- file.path(tempdir(), "tiny_written.dscalar.nii")
write.cifti(out_file, data_matrix, axes = list(cifti.axis.scalars("my data"), axis_brain))
unlink(out_file)
if (FALSE) {
# Write data with the mapping of an existing file (recommended for real data):
template <- "Conte69.MyelinAndCorrThickness.32k_fs_LR.dscalar.nii"
data_matrix <- read.cifti(template)$data
write.cifti("copy.dscalar.nii", data_matrix, template = template)
}