write.fs.connectome.cifti: Write a CIFTI-2 connectome file.

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

Write a CIFTI-2 connectome file.

Description

Write a connectome matrix to a CIFTI-2 file: a dense connectome (.dconn), a parcellated connectome (.pconn), or one of the mixed types (.pdconn, .dpconn) whose two dimensions hold brainordinates and parcels. The file type follows from the axes (and has to match the file name, see write.cifti), and the mapping of the two dimensions has to be given: it cannot be derived from the matrix, and guessing it (e.g. from the size of the matrix) would silently produce a file whose rows and columns describe the wrong brain regions.

Use template for the normal case, i.e. to write a connectome of the brainordinates or parcels of an existing file: this is how a .dconn of a subject gets the mapping of that subject, and how a .pconn gets the parcels of the .ptseries it was computed from. A template with a single brainordinate dimension (a .dscalar, .dtseries or .dlabel, i.e. the files that actually exist for a subject) is accepted as well: its mapping is then used for both dimensions of the connectome, which is what those files describe. Use axes if the mapping has to be built, e.g. a parcels axis from annotations (see cifti.axis.parcels.from.annot).

The complete matrix is written: a connectome file stores both halves of the matrix and its diagonal, so the symmetry of the matrix is not exploited anywhere, and the matrix of a .dconn can be huge (33 GB for the 91,282 grayordinates of an HCP subject, which is more than any implementation can hold in memory). Writing such a file is not supported yet; a connectome of a reduced set of brainordinates can be written.

Usage

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

Arguments

filepath	character string, the path of the file to write. The name should be one of .dconn.nii, .pconn.nii, .pdconn.nii or .dpconn.nii (the file type is derived from the axes, and the name has to agree with it).
data	numeric matrix, the connectome: the first matrix dimension (the rows) is CIFTI matrix dimension 0, which the axes describe. An fs.connectome instance (see read.fs.connectome.cifti) is accepted as well, in which case its data and its header are used.
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; a file with a single brainordinate dimension has that mapping used for both dimensions of the connectome.
axes	list of two axes (see cifti.header.from.axes) or a single axis that is used for both dimensions, or NULL. Use this instead of template to write a file with a mapping that is not in a file, e.g. a parcels axis built with cifti.axis.parcels.from.annot.
metadata	named character vector or named list, or NULL, the matrix metadata, see write.cifti. The default keeps the metadata of the template file.

Value

the axes that were written, invisibly.

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

Examples

pconn_file <- system.file("extdata", "cifti", "tiny.pconn.nii", package = "freesurferformats")
conn <- read.fs.connectome.cifti(pconn_file)
out_file <- file.path(tempdir(), "written.pconn.nii")
# The values are squared, the mapping is the one of the original file:
write.fs.connectome.cifti(out_file, conn$data^2, template = pconn_file)
read.fs.connectome.cifti(out_file)$data[1:2, 1:2]


## Not run: 
# The grayordinates of a subject are the same in all its dense files, so a dtseries
# can define the mapping of the dconn:
write.fs.connectome.cifti("sub-01_dconn.nii", connectivity_matrix,
                          template = "sub-01_task-rest_dtseries.nii")

## End(Not run)

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