freesurferformats (version 1.1.0)

write.dti.tsf: Write per-point track values to a file in MRtrix TSF format.

Description

The TSF format stores one scalar value per point of a streamline, e.g., the fractional anisotropy, the distance along the track or a value sampled from an image at the point coordinates. It is the companion format of the TCK format: a TSF file contains no coordinates and no track boundaries, it is just a stream of values that has to be read together with the tractogram it describes. The number of values per track is therefore required to write the file, and a TSF file without the matching TCK file is meaningless to every reader (MRtrix checks this, see the note below).

Usage

write.dti.tsf(
  tracts,
  filepath,
  lengths = NULL,
  datatype = "Float32LE",
  gzip = NULL,
  header = list()
)

Value

the file path, invisibly.

Arguments

tracts

the values to write. This can be an fs.tracts instance whose scalars entry holds a single column of values (as returned by read.dti.trk for a file with one scalar, see fs.tracts to construct one), the scalars entry of the result of read.dti.tsf (so that a scalar file can be read and written back), a list of numeric vectors (one per track), or a single numeric vector of all values concatenated (in which case lengths is required).

filepath

character string, the path of the file to write.

lengths

integer vector or NULL, the number of values per track. This is ignored unless tracts is a plain vector, and has to be given in that case.

datatype

character string, one of 'Float32LE' (the default, and what MRtrix writes), 'Float32BE', 'Float64LE' or 'Float64BE'.

gzip

logical or NULL, whether to gzip-compress the output. If NULL (the default), the file is compressed when the file name ends in '.gz'.

header

named list of additional header entries to store in the file, e.g., the header of the file the tracks were read from. The entries 'id', 'datatype', 'count', 'file' and 'derived' are always computed by the readers and cannot be set.

See Also

read.dti.tsf, write.dti.tck

Examples

# A TSF file stores one value per point. Since the format contains no track
# boundaries, the track lengths have to be provided:
tsff <- tempfile(fileext = ".tsf");
values_by_track <- list(c(0.1, 0.2, 0.3), c(0.4, 0.5));
write.dti.tsf(values_by_track, tsff);
read.dti.tsf(tsff)$scalars$scalar_list;

# The same file can be written from one vector of values and the lengths:
write.dti.tsf(c(0.1, 0.2, 0.3, 0.4, 0.5), tsff, lengths = c(3L, 2L));

if (FALSE) {
# Read the values of a track scalar file, modify them and write them back:
tsf <- read.dti.tsf("brain.tsf");
tsf$scalars$merged <- tsf$scalars$merged * 2;
write.dti.tsf(tsf$scalars, "brain_doubled.tsf");

# Sample an image along the tracks of a tractogram and store the result. The
# values of a TRK file that has one scalar are accepted as they are:
trk <- read.dti.trk("brain.trk");
write.dti.tsf(trk$tracks, "brain.trk.tsf");
}