Skip to contents

Write a CIFTI-2 connectome file.

Source: R/write_cifti_connectome.R
write.fs.connectome.cifti.Rd

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]
#>          PARCEL_A PARCEL_B
#> PARCEL_A        1        1
#> PARCEL_B        1        1

if (FALSE) { # \dontrun{
# 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")
} # }