freesurferformats (version 1.1.0)

write.fs.parcellated.cifti: Write a CIFTI-2 parcellated map or series file.

Description

Write data that has one value (or one time series) per parcel to a parcellated CIFTI-2 file: a .pscalar (scalar maps, e.g. a mean value per region) or a .ptseries (a time series per region). The parcellated dimension of these file types is matrix dimension 1, and the order of the parcels is the order of the parcels axis, which comes from a template file or from a parcels axis that you build (see cifti.axis.parcels.from.annot for a parcellation of this package, e.g. the annotations of a FreeSurfer atlas).

The file type is derived from the file name: a name ending in .pscalar.nii gets a scalars dimension (the map names come from map_names), one ending in .ptseries.nii a series dimension (described by start, step and unit). Use write.cifti directly for the other parcellated types (.pconn, the mixed connectome types) or for a file with a non-standard name.

Usage

write.fs.parcellated.cifti(
  filepath,
  data,
  template = NULL,
  axes = NULL,
  map_names = NULL,
  start = 0,
  step = 1,
  unit = "SECOND",
  metadata = NULL
)

Value

the axes that were written, invisibly.

Arguments

filepath

character string, the path of the file to write, ending in .pscalar.nii or .ptseries.nii.

data

numeric vector or matrix, the data: a vector with one value per parcel (a .pscalar with a single map), or a matrix with one row per map (for a .pscalar) or series point (for a .ptseries) and one column per parcel. The first matrix dimension is CIFTI matrix dimension 0, like for every other reader and writer of this package.

template

character string (the path of a CIFTI-2 file), an fs.cifti or an fs.cifti.data object, or NULL. The parcels of this file are used, so pass the parcellated file the data belongs to (e.g. a .ptseries or .pconn of the same subject).

axes

list of two axes or a single parcels axis (see cifti.axis.parcels), or NULL. Use this instead of template to write data for a parcellation that is not in a CIFTI-2 file, e.g. one built from annotations with cifti.axis.parcels.from.annot.

map_names

character vector or NULL, the names of the maps of a .pscalar. The number of names has to match the number of rows of the data. Without this, the map names of the template are kept if it is a .pscalar with as many maps as the data.

start

numeric, the value of the first series point of a .ptseries, see cifti.axis.series.

step

numeric, the difference between consecutive series points.

unit

character string, the unit of the series, one of 'SECOND', 'HERTZ', 'METER' or 'RADIAN'.

metadata

named character vector or named list, or NULL, the matrix metadata, see write.cifti. The default keeps the metadata of the template file.

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

Examples

template <- system.file("extdata", "cifti", "tiny.ptseries.nii", package = "freesurferformats")
data <- matrix(seq_len(3 * 4), nrow = 4L) # 4 series points, 3 parcels
out_file <- file.path(tempdir(), "written.ptseries.nii")
write.fs.parcellated.cifti(out_file, data, template = template, step = 0.5)
dim(read.cifti(out_file)$data)
unlink(out_file)