Package {freesurferformats}

Type:	Package
Title:	Read and Write 'FreeSurfer' Neuroimaging File Formats
Version:	1.1.0
Maintainer:	Tim Schäfer <ts+code@rcmd.org>
Description:	Provides functions to read and write neuroimaging data in various file formats, with a focus on 'FreeSurfer' formats. This includes, but is not limited to, the following file formats: 1) MGH/MGZ/NIFTI format files, which can contain multi-dimensional images or other data. Typically they contain time-series of three-dimensional brain scans acquired by magnetic resonance imaging (MRI). They can also contain vertex-wise measures of surface morphometry data. The MGH format is named after the Massachusetts General Hospital, and the MGZ format is a compressed version of the same format. 2) 'FreeSurfer' morphometry data files in binary 'curv' format. These contain vertex-wise surface measures, i.e., one scalar value for each vertex of a brain surface mesh. These are typically values like the cortical thickness or brain surface area at each vertex. 3) Annotation file format. This contains a brain surface parcellation derived from a cortical atlas. 4) Surface file format. Contains a brain surface mesh, given by a list of vertices and a list of faces.
License:	MIT + file LICENSE
Copyright:	Tim Schäfer (package code); the optional data files that can be downloaded at runtime are owned by their respective copyright holders, see 'inst/COPYRIGHTS'.
Encoding:	UTF-8
URL:	https://github.com/dfsp-spirit/freesurferformats, https://dfsp-spirit.github.io/freesurferformats/
BugReports:	https://github.com/dfsp-spirit/freesurferformats/issues
Imports:	utils, pkgfilecache (≥ 0.1.1), xml2
Suggests:	knitr, rmarkdown, curl, testthat (≥ 2.1.0), oro.nifti (≥ 0.9), gifti (≥ 0.7.5), cifti (≥ 0.4.5)
VignetteBuilder:	knitr
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-09-24 10:02:44 UTC; ts
Author:	Tim Schäfer [aut, cre], Van Essen Lab [cph] (Copyright holder of the Conte69 template and HCP group-average data files that can OPTIONALLY be downloaded via download_opt_data().), Montreal Neurological Institute (MNI) [cph] (Copyright holder of the MNI152/avg152T1 template that can OPTIONALLY be downloaded via download_opt_data().)
Repository:	CRAN
Date/Publication:	2026-09-24 18:00:02 UTC

Bring a gradient table into the canonical 'one row per volume' layout.

Description

Gradient tables occur in two orientations in the wild: the FSL layout, in which the first axis is the vector component (3 rows of N values for b-vectors, a single row of N values for b-values), and the volumes layout, in which each line is one volume (N rows of 3 values for b-vectors, as used by HCP, and N rows of 4 values for the MRtrix gradient table format). This helper maps both to one row per volume.

Usage

.canonicalize.gradient.table(
  m,
  n_components,
  layout,
  what,
  square_is_ambiguous = FALSE
)

Arguments

Value

a numeric matrix with one row per volume and n_components columns.

Note

A square 3x3 file is ambiguous, and the two reference implementations do not agree on it: MRtrix3 reads such a b-vectors file with the components in the rows, while DIPY reads it with the volumes in the rows. Like MRtrix3, read.dti.bvec treats the lines as components, and warns, because silently guessing here would scramble the gradient directions. Matrices passed in memory are read with one row per volume, which is the R convention, and no warning is needed.

Convert a label table to the format the package has always returned.

Description

The readers document a label table with the column names 'Key', 'Red', 'Green', 'Blue', 'Alpha' and 'Label'; keep that spelling (and the column order) for the user-facing functions, while the internal representation uses lower case column names and also stores the optional label coordinates.

Usage

.cifti.label.table.for.users(labels)

Arguments

Value

a data.frame with the columns 'Key', 'Red', 'Green', 'Blue', 'Alpha' and 'Label'.

Get the b-value threshold below which a volume counts as a b=0 volume.

Description

MRtrix3 treats any volume whose b-value is at most this threshold as a b=0 volume. See the BZeroThreshold configuration entry of MRtrix3, which defaults to 10 s/mm^2.

Usage

.dti.bzero.threshold()

Value

numeric scalar, the threshold in s/mm^2.

Find the b-value file that belongs to a b-vector file.

Description

Looks for the bvals file next to a bvecs file, by replacing the bvec/bvecs part of the file name with bval/bvals, and by replacing the file extension if that does not match. This makes the readers work out of the box on standard datasets, e.g. the BIDS files ⁠sub-01_dwi.bvec⁠ and ⁠sub-01_dwi.bval⁠.

Usage

.find.bval.file(bvec_filepath)

Arguments

Value

character string, the path to the existing b-value file, or NULL if none of the candidates exists.

Format numeric values for a gradient table text file.

Description

Writes gradient values with enough significant digits to survive a round trip, in a plain decimal or scientific notation that the FSL, MRtrix3, DIPY and NumPy readers all accept. Note that formatC(..., digits = 15) cannot be used here: with the default width = NULL it treats digits as the field width and pads every value with spaces, which makes the files hard to read.

Usage

.format.gradient.values(x)

Arguments

Value

character vector of the same length as x.

Format a possibly missing TRK header size for an error message.

Description

Format a possibly missing TRK header size for an error message.

Usage

.format.header.size(value)

Arguments

Value

character string.

Name the columns of an MRtrix gradient table.

Description

Name the columns of an MRtrix gradient table.

Usage

.name.gradient.table.columns(gt)

Arguments

Value

the matrix with columns named 'x', 'y', 'z' and 'b'.

Read DTI tracking data from MRtrix TCK and TSF files.

Description

Read DTI tracking data from MRtrix TCK and TSF files.

Usage

.read.dti.tcktsf(
  filepath,
  max_tracks = Inf,
  skip_tracks = 0L,
  bbox = NULL,
  chunk_values = 4e+06
)

Arguments

Value

named list with entries header and either tracks (for TCK files) or scalars (for TSF files).

Read a whitespace-separated numeric table from a text file.

Description

Low-level parser shared by all gradient table readers. Values may be separated by spaces, tabs or commas, and both blank lines and lines starting with ⁠#⁠ are ignored. All remaining lines must contain the same number of values.

Usage

.read.numeric.table(filepath, allow_count_header = FALSE)

Arguments

Value

a numeric matrix, one row per input line.

Write a numeric table to a text file, one matrix row per line.

Description

Write a numeric table to a text file, one matrix row per line.

Usage

.write.numeric.table(filepath, m)

Arguments

Value

NULL, invisibly.

The NIFTI v2 extension code that holds the CIFTI-2 XML metadata.

Description

The CIFTI-2 XML document is stored in a NIFTI v2 header extension with this code.

Usage

CIFTI_EXTENSION_CODE

Subset an fs.tracts instance.

Description

Subset an fs.tracts instance.

Usage

## S3 method for class 'fs.tracts'
x[i]

Arguments

Value

a new fs.tracts instance containing the selected tracts.

Examples

## Not run: 
tck <- read.dti.tck("brain.tck");
first_ten <- tck$tracks[1:10];

## End(Not run)

Access a single tract of an fs.tracts instance.

Description

For TCK data (see read.dti.tck), a tract is an n x 3 numeric matrix of coordinates. For TRK data (see read.dti.trk), a tract is a named list with the entries coords (n x 3 matrix), num_points (integer), scalars (n x n_scalars matrix or NULL) and properties (numeric vector or NULL).

This returns a copy of the requested tract, the data is stored in a single matrix internally.

Usage

## S3 method for class 'fs.tracts'
x[[i]]

Arguments

Value

the tract, see the description.

Examples

## Not run: 
tck <- read.dti.tck("brain.tck");
first_tract_coords <- tck$tracks[[1]];

## End(Not run)

Adjust integer matrix to target min value.

Description

This takes a matrix of integers, and adjusts the values such that the minimal value is the 'target_min_index' value. It is used to adjust from 0-based to 1-based indices in meshes.

Usage

adjust.face.indices.to(faces, target_min_index = 1L)

Arguments

Value

3xn integer matrix, the adjusted values

Note

The current and the target min values must be 0 or 1.

Compute the R data type and the number of bytes per value for an ANALYZE data type.

Description

Compute the R data type and the number of bytes per value for an ANALYZE data type.

Usage

analyze.dtype.info(analyzeheader, filepath = NULL)

Arguments

Value

named list with the entries datatype and bitpix (the data type fields to use for reading the data, which may differ from the values in the file if the file contradicts itself), num_bytes (the number of bytes per value) and r_dtype (the R type to read the values as).

Note

ANALYZE files in the wild sometimes have a wrong bitpix field, since the format was used by many tools that did not care about it. The data type is the reliable field, so if the two fields contradict each other, the bitpix value that belongs to the data type is used, with a warning.

Check whether an ANALYZE 7.5 header is suitable for writing.

Description

Check whether an ANALYZE 7.5 header is suitable for writing.

Usage

analyze.header.check(analyzeheader)

Arguments

Value

logical, whether the header passed the checks. Fields that cannot be written as requested are reported with a message.

Note

The checks are in no way meant to be exhaustive. They only verify that the fields that are written to the file have a length that fits into their fixed size slots in the 348 byte header, since writing a longer value would shift all fields behind it and produce a corrupt file.

Compute a transformation matrix from the fields of an ANALYZE 7.5 header.

Description

Compute the voxel-to-RAS matrix for an ANALYZE 7.5 image, using the conventions of SPM and of the original ANALYZE software. See the "geometry" section of read.fs.volume.analyze for what this matrix is and is not.

Usage

analyze.header.to.vox2ras(analyzeheader)

Arguments

Value

a 4x4 numeric matrix, the voxel-to-RAS transformation matrix. The matrix assumes that the first voxel axis points to the left (i.e. it contains -pix_dim[2] in its first column), which is the convention of the format. If the SPM origin is present in the header, the matrix maps the origin to the world position that the SPM fields describe, otherwise the center of the image is used as the origin, exactly as the reference implementation of the format (nibabel) does it.

Compute the voxel-to-RAS matrix from the MATLAB sidecar file of an ANALYZE image.

Description

Read the transformation matrix that SPM and FreeSurfer write into the .mat file next to an ANALYZE image, and convert it to the convention used by this package (0-based voxel indices, right-anterior-superior world coordinates). See the geometry section of read.fs.volume.analyze for the details.

Usage

analyze.mat.sidecar.to.vox2ras(matfile)

Arguments

Value

named list with the entries vox2ras (a 4x4 numeric matrix, or NULL if the file could not be read or contains no usable matrix) and reason (a character string describing the problem, or NULL on success).

Determine the header and data file of an ANALYZE 7.5 or NIFTI v1 pair file.

Description

The two formats ANALYZE 7.5 and NIFTI v1 (in its two-file variant) store the image in a header file (⁠<base>.hdr⁠) and a data file (⁠<base>.img⁠). This function computes the two file names from any of them, so that the user can pass any of the possible spellings.

Usage

analyze.pair.files(filepath, require_header = FALSE)

Arguments

Value

named list with the entries header and image, the full paths to the header and the data file, the logical entries header_exists and image_exists, and the entries mat (the path of the MATLAB sidecar file that SPM and FreeSurfer write next to the image file, see read.fs.volume.analyze) and mat_exists, which report whether such a file is present.

Note

Compression is handled the way the other implementations of the format handle it: the suffix .gz (and .hdr/.img) is stripped from the file name to get the base name, and the two file names are constructed from it. A name like vol.hdr.gz therefore describes the pair vol.hdr.gz and vol.img.gz, and vol.nii.gz would be the pair vol.nii.hdr.gz and vol.nii.img.gz. Note that many tools only read uncompressed pairs, so compressed pairs should only be written if the software that reads them supports this.

Read a fixed length character field of an ANALYZE 7.5 header.

Description

Read a fixed length character field of an ANALYZE 7.5 header.

Usage

analyze.read.char.field(filehandle, n)

Arguments

Value

character string, the field content with the trailing zero bytes removed. The bytes are interpreted as ISO-8859-1 (latin-1) and converted to UTF-8, which cannot fail: the ANALYZE 7.5 fields originator, generated, patient_id and friends contain whatever the software that wrote the file put there, including bytes that are not valid UTF-8 (the SPM software, for example, stores an image origin as 3 little endian integers in the originator field). Decoding them as UTF-8 would fail or return NA for a subset of the possible byte values.

Read ANALYZE 7.5 header from file.

Description

Read ANALYZE 7.5 header from file.

Usage

analyze.read.header.internal(filepath, little_endian = TRUE)

Arguments

Value

named list, the ANALYZE 7.5 header. See read.analyze.header.

Read the 4 magic bytes of an ANALYZE 7.5 or NIFTI v1 header.

Description

Read the 4 magic bytes of an ANALYZE 7.5 or NIFTI v1 header.

Usage

analyze.read.magic(filepath)

Arguments

Value

character string, the 4 bytes at offset 344 of the file, interpreted as a string. This is the NIFTI v1 magic field, which is empty ('') for ANALYZE 7.5 files (where the same bytes are the smin field), 'ni1' for a NIFTI v1 pair file and 'n+1' for a single file NIFTI v1 file.

Write the voxel data of an ANALYZE 7.5 image to a connection.

Description

Write the voxel data of an ANALYZE 7.5 image to a connection.

Usage

analyze.write.data.internal(fh, analyzedata, analyzeheader)

Arguments

Value

the data that was written, after conversion to the data type stated in the header.

Create ANALYZE 7.5 header suitable for given data.

Description

Create ANALYZE 7.5 header suitable for given data.

Usage

analyzeheader.for.data(analyzedata, ...)

Arguments

Value

an ANALYZE 7.5 header (see analyzeheader.template) in which the datatype, bitpix, dim, cal_min and cal_max fields have been set to values suitable for the given data. Feel free to change the other fields, e.g. the voxel sizes in pix_dim or the orient code.

Note

ANALYZE 7.5 has much fewer data types than NIFTI: integers are stored as 32 bit signed integers and floating point data as 32 bit floats, which is what this function selects (the same choice that ni1header.for.data makes for NIFTI v1). To store 16 bit integers, which is the classic ANALYZE data type, set datatype to 4L and bitpix to 16L in the returned header after calling this function.

Examples

analyzeheader <- analyzeheader.for.data(array(1:24, dim = c(4, 3, 2)))
analyzeheader$datatype

Create a template ANALYZE 7.5 header. You will have to adapt it for your use case.

Description

This function returns a valid ANALYZE 7.5 header with all fields present, filled with the default values of the format. You will most likely have to adapt at least the dim, datatype, bitpix and pix_dim fields to your data, which is what analyzeheader.for.data does for you.

Usage

analyzeheader.template()

Value

named list, the ANALYZE 7.5 header. The fields endian, magic, header_format and spm_origin are not part of the ANALYZE 7.5 header: endian and magic describe how the file is stored, header_format tells which variant of the 348 byte header this is ('analyze' or 'nifti1_pair'), and spm_origin is the interpretation of the originator field that the SPM software uses.

Note

The fields spm_origin and magic are derived when a file is read, they are documented in read.analyze.header.

See Also

analyzeheader.for.data, read.analyze.header, write.analyze

Examples

analyzeheader <- analyzeheader.template()
analyzeheader$dim <- c(3L, 4L, 3L, 2L, 1L, 1L, 1L, 1L)
analyzeheader$pix_dim <- c(1., 1., 1., 1., 0., 0., 0., 0.)

Get max region index of an fs.annot instance.

Description

Get max region index of an fs.annot instance.

Usage

annot.max.region.idx(annot)

Arguments

Value

integer, the max region index. They typically start with 0 and are consecutive, but this is not enforced or checked in any way.

Note

This is a helper function to be used with annot.unique, see the example there.

Make the region names and indices unique across hemispheres for a parcellation.

Description

Sometimes you need an annotation to use unique IDs and region names across hemispheres, but that is not the case for the standard FreeSurfer parcellations. So what you need to do is change the codes and names for one hemi. Typically the left hemi annot will be left as is, and the right hemi annot will be modified using this function.

Usage

annot.unique(
  annot,
  add_to_region_indices,
  region_name_prefix = "rh_",
  region_name_suffix = NULL,
  set_first_idx_zero = FALSE
)

Arguments

Note

This function is not part of the official API and should not be used. It is currently broken.

Examples

## Not run: 
lh_annot <- read.fs.annot("~/data/study1/subject1/label/lh.aparc.annot")
lh_annot
# shows info including region IDs
rh_annot <- read.fs.annot("~/data/study1/subject1/label/rh.aparc.annot")
rh_annot_mod <- annot.unique(rh_annot, annot.max.region.idx(lh_annot) + 1L,
                             region_name_prefix = "rh_")

## End(Not run)

Apply an affine to a set of coordinates.

Description

Apply an affine to a set of coordinates.

Usage

apply.affine.to.coords(coords, affine)

Arguments

Value

numeric matrix with 3 columns, the transformed coordinates.

Convert a collection of tracts to an fs.tracts instance.

Description

Accepts an fs.tracts instance, a list of numeric matrices with 3 columns, or a single such matrix (which is then treated as one tract), and returns an fs.tracts instance. This is what the writers use to accept several input types.

Usage

as.fs.tracts(tracts, kind = "tck")

Arguments

Value

an fs.tracts instance.

Examples

tracts <- as.fs.tracts(list(matrix(c(0, 0, 0, 1, 1, 1), ncol = 3, byrow = TRUE)));
length(tracts);

Convert an fs.tracts instance to a plain list of tracts.

Description

Converts to the classic representation as a list with one entry per tract. This is convenient for interacting with code that expects a plain list, but note that it materializes one R object per tract and is therefore much more expensive in both memory and time. Prefer [[ for accessing individual tracts.

Usage

## S3 method for class 'fs.tracts'
as.list(x, ...)

Arguments

Value

list with one entry per tract.

Examples

## Not run: 
tck <- read.dti.tck("brain.tck");
tracts_list <- as.list(tck$tracks);

## End(Not run)

Convert scalar values for streamlines to a list of vectors.

Description

Normalizes the several input forms accepted by write.dti.tsf to a list of numeric vectors, one per streamline, and checks the lengths for consistency.

Usage

as.tsf.scalars(tracts, lengths = NULL)

Arguments

Value

named list with entries values (list of numeric vectors) and lengths (integer vector).

Stop unless surf is an fs.surface

Description

Stop unless surf is an fs.surface

Usage

assert.surface(surface, param_name = "surface")

Arguments

Value

Called for the side effect of stopping if surface is not an fs.surface instance.

Construct a brain atlas from a colortable (LUT) file and a per-vertex label file.

Description

Construct a brain atlas (surface annotation) from a FreeSurfer ASCII colortable lookup table (LUT) file and a text file that assigns a label (struct index) to each vertex of a brain surface. This is useful when an atlas is distributed as two text files: a colortable (LUT) plus a per-vertex label assignment, for example the cortical atlases bundled with the Python package 'yabplot' (files like 'aparc_LUT.txt' and 'aparc_conte69.csv').

Usage

atlas.from.lut.and.csv(
  lut_file,
  csv_file = NULL,
  label_indices = NULL,
  num_vertices = NULL,
  unknown_label_name = "unknown",
  unknown_index = 0L,
  include_unknown_in_colortable = TRUE
)

Arguments

Value

an 'fs.annot' instance with class 'fs.annot', see read.fs.annot for the structure. Can be written to a FreeSurfer annotation file with write.fs.annot.

See Also

Other atlas functions: colortable.from.annot(), read.fs.annot(), read.fs.colortable(), write.atlas.to.lut.and.csv(), write.fs.annot(), write.fs.annot.gii(), write.fs.colortable()

Examples

## Not run: 
# Example for the yabplot cortical atlas files (LUT + per-vertex indices):
annot <- atlas.from.lut.and.csv("aparc_LUT.txt", "aparc_conte69.csv")
write.fs.annot("lh.aparc.annot", fs.annot = annot)

## End(Not run)

Convert axis codes to an orientation array.

Description

Convert axis codes to an orientation array.

Usage

axcodes2ornt(axcodes)

Arguments

Value

numeric matrix with 3 rows and 2 columns, see io.orientation.

Build the text header of an MRtrix streamlines file.

Description

MRtrix streamlines files (TCK for the tracks, TSF for per-point values along the tracks) share one header format, they only differ in the identifier line and in the meaning of the payload. The header is ASCII text, and its length is stored within the header itself as the offset at which the binary payload starts.

Usage

build.mrtrix.header(header_id, entries, datatype, count, offset)

Arguments

Value

character string, the header including the terminating newline.

Determine the length of an MRtrix streamlines header.

Description

The length of the header determines the data offset that is stored inside the header, so the two have to be reconciled: the offset is written with a number of digits that depends on its own value, which can change the length of the header. Starting from an offset guess and recomputing until it is stable always terminates, since the length only ever grows with the number of digits and that number is bounded.

Usage

build.mrtrix.header.stable(header_id, entries, datatype, count)

Arguments

Value

named list with entries text (the header) and offset.

Create new bvsmp instance encoding morph data for Brainvoyager.

Description

Create new bvsmp instance encoding morph data for Brainvoyager.

Usage

bvsmp(morph_data)

Arguments

Value

bvsmp instance, can be used to write Brainvoyager SMP format morphometry files using write.smp.brainvoyager. Modify as needed before writing.

Examples

morph_data <- rnorm(100L, 3.0, 1.0)
mybvsmp <- bvsmp(morph_data)
mybvsmp$smp_version

Create CDATA element string from string.

Description

Create CDATA element string from string.

Usage

cdata(string)

Arguments

Value

character string, the input wrapped in the cdata tags

Note

This returns a string, not an XML node. See xml_cdata if you want a node.

Check whether the dtype is suitable for the data.

Description

This function provides an educated guess on whether the given dtype is suitable for the data. It is usually called for the site effect of printing warnings in case something seems off.

Usage

check.dtype.for.data(mridata, mri_dtype_code)

Arguments

Value

logical, whether the dtype could be suitable. This is only a guess, as the checks are in no way complete.

Check that a numeric vector or matrix contains only finite values.

Description

Stops with an error if the input contains NA, NaN, or Inf values.

Usage

check_all_finite(x, label = "data")

Arguments

Value

TRUE (invisibly) if all values are finite. Stops otherwise.

Warn about common errors in combining data and datatype.

Description

Warn about common errors in combining data and datatype.

Usage

check_data_and_settings_consistency(
  index,
  data,
  datatype,
  intent,
  force = FALSE
)

Arguments

Note

The checks in here are in no way exhaustive.

Check that a file is large enough to contain the expected data payload.

Description

Compares the expected data size against the file size on disk. Stops with an error if the file is too small (truncated or corrupt).

Usage

check_file_size(filepath, header_bytes, data_bytes)

Arguments

Value

logical, TRUE (invisibly) if the file is large enough. Stops with an error otherwise.

Accept the input forms of a set of annotations.

Description

Accept the input forms of a set of annotations.

Usage

cifti.annot.list(annots, structure = NULL)

Arguments

Value

a named list of fs.annot instances, named by canonical brain structure name.

Collect the vertices of each region of an annotation.

Description

Collect the vertices of each region of an annotation.

Usage

cifti.annot.parcels(annot, structure_name, default_label_name = "unknown")

Arguments

Value

a named list of integer vectors, one entry per region that contains at least one vertex: the 0-based vertex indices of the region, in ascending order. The entries are ordered like the label table of the annotation (the atlas order).

Create an array like the input, with a different first dimension.

Description

Create an array like the input, with a different first dimension.

Usage

cifti.array.with.new.first.dim(data, first_dim_size)

Arguments

Value

an array of NA of the data type of data, with the new first dimension and all other dimensions of data.

Assign rows of an array, reordered or repeated.

Description

Assign rows of an array, reordered or repeated.

Usage

cifti.assign.rows(target, to, from, data)

Arguments

Value

target with the requested rows assigned.

Group axes into MatrixIndicesMap elements.

Description

A CIFTI-2 file describes its matrix dimensions with MatrixIndicesMap elements, and the format says that the same element must be used for both dimensions when they describe the same thing. This is the case for connectome files (a .dconn or .pconn has the same brainordinates or parcels in both dimensions), and Connectome Workbench writes such a file with a single element that applies to both dimensions, while nibabel writes one per dimension. The merged form is what this writer produces.

Usage

cifti.axes.to.maps(axes)

Arguments

Value

a list of lists with the entries 'axis' (the axis) and 'dims' (the matrix dimensions it describes).

Create a CIFTI-2 axis for brain models.

Description

A brain model axis describes which surface vertices and volume voxels a matrix dimension of a CIFTI-2 file contains, in the order in which they appear in the matrix. This is the mapping of a dense file (.dscalar, .dtseries, .dlabel, .dconn), and of the files that mix dense and parcellated data.

The index ranges of the models are computed from the index lists, so the models cover the dimension without gaps, which the format requires. A structure may appear in several models (e.g. as a surface and as a volume part in a grayordinates file), and the order of the models is the order of the matrix indices.

Usage

cifti.axis.brain.models(models, surfaces = NULL, volume = NULL)

Arguments

Value

a named list with the entries 'type', 'brain_models', 'surfaces' and 'volumes', an axis to be passed to cifti.header.from.axes or write.cifti.

See Also

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

Examples

axis <- cifti.axis.brain.models(list(
  cifti.brain.model.surface("lh", 10L),
  cifti.brain.model.surface("rh", 12L)))
axis$type

Build the axis for a set of maps.

Description

Build the axis for a set of maps.

Usage

cifti.axis.for.maps(map_names, nx, template_map_axis = NULL)

Arguments

Value

an axis, see cifti.axis.scalars.

Create a CIFTI-2 axis from a template file.

Description

Read the axes of an existing CIFTI-2 file, so that a new file can be written with the same mapping. This is the recommended way to write a file for real data: the mapping of an HCP grayordinates file (which vertices are in the file, and which volume voxels) can not be invented, it has to come from the file the data was derived from.

Usage

cifti.axis.from.template(x, dim = NULL)

Arguments

Value

the axis of the requested dimension (a named list, see cifti.axis.brain.models), or a list of axes (one per dimension; note that a file whose dimensions share a single XML mapping returns the same axis for both, as two entries).

See Also

Other cifti functions: cifti.axis.brain.models(), 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.parcellated.cifti(), write.fs.parcellation.cifti(), write.fs.series.cifti()

Examples

cifti_file <- system.file("extdata", "cifti", "tiny.dscalar.nii", package = "freesurferformats")
axes <- cifti.axis.from.template(cifti_file)
length(axes)
axes[[2L]]$type

Create a CIFTI-2 axis for label maps.

Description

See cifti.axis.scalars; a labels axis is the same thing with integer label keys instead of scalar values, and it stores the label table that defines the keys.

Usage

cifti.axis.labels(names = NULL, label_tables = NULL, metadata = NULL)

Arguments

Value

a named list with the entries 'type' and 'named_maps', an axis to be passed to cifti.header.from.axes or write.cifti.

See Also

Other cifti functions: cifti.axis.brain.models(), cifti.axis.from.template(), 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.parcellated.cifti(), write.fs.parcellation.cifti(), write.fs.series.cifti()

Examples

label_table <- data.frame(key = 0:1, red = c(1, 0), green = c(1, 0.5), blue = c(1, 1),
                          alpha = c(0, 1), label = c("???", "PARCEL_A"))
axis <- cifti.axis.labels("parcellation", label_tables = list(label_table))
axis$named_maps[[1]]$labels$label

Create a CIFTI-2 axis for named maps (internal helper).

Description

Create a CIFTI-2 axis for named maps (internal helper).

Usage

cifti.axis.named.maps(names, metadata, label_tables, type)

Arguments

Value

a named list with the entries 'type' and 'named_maps'.

Create a CIFTI-2 axis for parcels.

Description

A parcel axis describes the parcels of a parcellated matrix dimension (the mapping of .pscalar, .ptseries, .pconn and the second dimension of .pdconn). As for brain models, the index of a parcel is its position in the list.

Usage

cifti.axis.parcels(parcels, surfaces = NULL, volume = NULL)

Arguments

Value

a named list with the entries 'type', 'parcels', 'surfaces' and 'volumes', an axis to be passed to cifti.header.from.axes or write.cifti.

See Also

Other cifti functions: cifti.axis.brain.models(), cifti.axis.from.template(), cifti.axis.labels(), 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.parcellated.cifti(), write.fs.parcellation.cifti(), write.fs.series.cifti()

Examples

axis <- cifti.axis.parcels(list(
  cifti.parcel("PARCEL_A", list(CORTEX_LEFT = 0:2)),
  cifti.parcel("PARCEL_B", list(CORTEX_LEFT = 3:5))))
length(axis$parcels)

Create a CIFTI-2 parcels axis from brain surface annotations.

Description

A parcellated CIFTI-2 file stores no label table, it describes each parcel by its name and by the vertices (per brain structure) and volume voxels it contains. This function builds such a parcels axis from brain surface annotations (see read.fs.annot), which assign a region label to every vertex of a hemisphere, so that data that was computed per region of an atlas (a FreeSurfer parcellation, a Schaefer atlas, ...) can be written to a parcellated file.

The vertices of a parcel are collected by the name of the region, not by its label key: the hemispheres of an atlas usually use the same names for the same region, but the names often carry a hemisphere marker (e.g. L_superiorfrontal in one hemisphere and R_superiorfrontal in the other, or ⁠7Networks_LH_Vis_1⁠ and ⁠7Networks_RH_Vis_1⁠), and a parcel of a parcellated CIFTI-2 file is a region that spans the structures it occurs in. The markers are removed before the names are compared, see cifti.region.name.without.hemisphere for the exact rules. Vertices whose label is not in the label table of the annotation (the medial wall, which is usually the 'unknown' region with key 0) form a parcel like any other, named default_label_name: a parcellated file has no 'no value' case, and dropping the medial wall silently would change the data.

Usage

cifti.axis.parcels.from.annot(
  annots,
  structure = NULL,
  parcel_names = NULL,
  default_label_name = "unknown"
)

Arguments

Value

an axis of type 'CIFTI_INDEX_TYPE_PARCELS', see cifti.axis.parcels, to be passed to write.cifti or to one of the writers that accept it (e.g. write.fs.parcellated.cifti).

See Also

Other cifti functions: cifti.axis.brain.models(), cifti.axis.from.template(), cifti.axis.labels(), cifti.axis.parcels(), 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.parcellated.cifti(), write.fs.parcellation.cifti(), write.fs.series.cifti()

Examples

lh_annot_file <- system.file("extdata", "lh.aparc.annot.gz", package = "freesurferformats")
lh_annot <- read.fs.annot(lh_annot_file)
axis <- cifti.axis.parcels.from.annot(lh_annot, structure = "lh")
length(axis$parcels)
axis$parcels[[1L]]$name

Create a CIFTI-2 axis for scalar or label maps.

Description

A scalars axis holds a set of maps (e.g. the myelin map and the cortical thickness of a subject in one .dscalar file), a labels axis holds a set of label maps (one per parcellation in a .dlabel file). Both are described by their map names; a labels axis can additionally have a label table per map, which maps the integer label keys in the data to names and colors.

Usage

cifti.axis.scalars(names = NULL, metadata = NULL)

Arguments

Value

a named list with the entries 'type' and 'named_maps', an axis to be passed to cifti.header.from.axes or write.cifti.

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

Examples

axis <- cifti.axis.scalars(c("thickness", "area"))
length(axis$named_maps)

Create a CIFTI-2 axis for a series.

Description

A series axis describes a dimension that holds an ordered sequence of samples, usually the time points of a .dtseries or .ptseries file. The value of series index i (0-based) is (start + i * step) * 10^exponent, in the unit that unit names.

Usage

cifti.axis.series(
  number_of_series_points,
  start = 0,
  step = 1,
  exponent = 0L,
  unit = "SECOND"
)

Arguments

Value

a named list with the entries 'type' and 'series', an axis to be passed to cifti.header.from.axes or write.cifti.

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

Examples

axis <- cifti.axis.series(10L, start = 0, step = 0.72, unit = "SECOND")
axis$series$number_of_series_points

The number of matrix entries an axis covers.

Description

The number of matrix entries an axis covers.

Usage

cifti.axis.size(axis)

Arguments

Value

integer, the size of that matrix dimension.

Get the surface sizes of an axis as a named vector.

Description

Get the surface sizes of an axis as a named vector.

Usage

cifti.axis.surface.sizes(axis)

Arguments

Value

named integer vector or NULL, the number of vertices per structure, see cifti.axis.brain.models.

Create the Surface elements of an axis.

Description

Create the Surface elements of an axis.

Usage

cifti.axis.surfaces(surfaces)

Arguments

Value

a list of lists with the entries 'brain_structure' and 'surface_number_of_vertices', or NULL.

Create a CIFTI-2 brain model entry for a surface.

Description

A surface brain model entry describes a set of surface vertices that one matrix dimension of a CIFTI-2 file contains, e.g. one hemisphere. The vertex indices are 0-based and refer to the vertices of the surface mesh that the file is defined on. If they are NULL, the model covers all vertices of the surface, which is only allowed if their number matches the size of the index range (the reader validates this, and the writer computes the range from the index list).

Usage

cifti.brain.model.surface(
  structure,
  surface_number_of_vertices,
  vertices = NULL
)

Arguments

Value

a named list, one brain model entry, to be passed to cifti.axis.brain.models.

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

Examples

model <- cifti.brain.model.surface("lh", 10L, vertices = 0:4)
model$index_count

Create a CIFTI-2 brain model entry for volume voxels.

Description

A volume brain model entry describes the voxels of one subcortical structure, as 0-based IJK indices into the voxel grid of the volume that is part of the same axis (see cifti.volume). If the indices are NULL, the model covers all voxels of that grid.

Usage

cifti.brain.model.volume(structure, voxel_indices_ijk = NULL)

Arguments

Value

a named list, one brain model entry, to be passed to cifti.axis.brain.models.

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

Examples

voxels <- matrix(c(0L, 0L, 2L, 1L, 0L, 2L), ncol = 3L, byrow = TRUE)
model <- cifti.brain.model.volume("CEREBELLUM", voxels)
model$index_count

Get the brainordinate dimension of a CIFTI-2 file.

Description

Find the matrix dimension of a CIFTI-2 file that holds the brain structures. Most files have exactly one (dimension 1 for a .dscalar, .dtseries or .dlabel, dimension 0 for the special case of a .dpconn-style file), while connectome files like a .dconn have brain models in both dimensions.

Usage

cifti.brainordinate.dim(cii)

Arguments

Value

integer, the dimension. Stops with a descriptive error if there is no brainordinate dimension or if there are two.

Get all matrix dimensions of a CIFTI-2 file that hold brain models.

Description

A single MatrixIndicesMap element can apply to both matrix dimensions (this is the case for connectome files like .dconn and .pconn), so the dimensions have to be counted, not the mapping elements.

Usage

cifti.brainordinate.dims(cii)

Arguments

Value

integer vector, the dimensions that contain brain models (usually one, two for a file like .dconn).

Check a list of axes and name the dimensions.

Description

Check a list of axes and name the dimensions.

Usage

cifti.check.axes(axes)

Arguments

Value

the list, with the axes named by their matrix dimension.

Check and prepare the data for a set of axes.

Description

Check and prepare the data for a set of axes.

Usage

cifti.check.data.for.axes(data, axes)

Arguments

Value

the data as an array with the dimensions of the axes.

Check a vector of 0-based indices.

Description

Check a vector of 0-based indices.

Usage

cifti.check.index.list(indices, what, max_index = NULL)

Arguments

Value

the indices as an integer vector.

Check a matrix index selection.

Description

Check a matrix index selection.

Usage

cifti.check.index.selection(selection, max_index, what, filepath)

Arguments

Value

the selection as an integer vector, or NULL.

Check a label table for writing.

Description

Check a label table for writing.

Usage

cifti.check.label.table(label_table, map_idx)

Arguments

Value

the label table, or NULL.

Check that an object is an fs.cifti instance.

Description

Check that an object is an fs.cifti instance.

Usage

cifti.check.object(cii)

Arguments

Value

the object, invisibly.

Compute the index ranges of brain model entries.

Description

The IndexOffset and IndexCount fields of a brain model entry say which matrix entries it covers. They are derived from the index lists (and from the surface sizes or the volume for a model that covers everything), and they have to cover the dimension without gaps, so they are always computed here rather than taken from the caller.

Usage

cifti.compute.index.ranges(models, volume = NULL)

Arguments

Value

the models, with index_offset and index_count set.

Determine the two axes of a connectome file.

Description

Determine the two axes of a connectome file.

Usage

cifti.connectome.axes(axes, template_cii = NULL)

Arguments

Value

a list of two axes, named by matrix dimension.

Assemble the data values of all vertices for a file without a template.

Description

Assemble the data values of all vertices for a file without a template.

Usage

cifti.data.for.all.vertices(data, structures, what = "data")

Arguments

Value

a matrix with one row per vertex (structures one after the other) and one column per map.

Accept the input forms of a CIFTI-2 connectome.

Description

Accept the input forms of a CIFTI-2 connectome.

Usage

cifti.data.for.connectome(filepath, rows = NULL, columns = NULL)

Arguments

Value

an fs.cifti.data object, see read.cifti.

Select the data values of the grayordinates of a file.

Description

Select the data values of the grayordinates of a file.

Usage

cifti.data.for.grayordinates(data, structures, index_table, what)

Arguments

Value

a matrix with one row per grayordinate (in file order) and one column per map.

Accept the input forms of a CIFTI-2 data object.

Description

Accept the input forms of a CIFTI-2 data object.

Usage

cifti.data.object(x)

Arguments

Value

an fs.cifti.data object, see read.cifti.

Get the per-structure data of one structure.

Description

Get the per-structure data of one structure.

Usage

cifti.data.per.structure(data, structure_name, what)

Arguments

Value

a matrix with one row per vertex of the complete surface and one column per map.

Determine the structures of per-vertex data.

Description

Determine the structures of per-vertex data.

Usage

cifti.data.structures(data, structure = NULL)

Arguments

Value

character vector of canonical structure names, or NULL if the data are not a named list and no structure was given.

The number of vertices of the surface of one structure.

Description

The number of vertices of the surface of one structure.

Usage

cifti.data.surface.size(data, structure_name)

Arguments

Value

integer, the number of vertices.

Get the dense data matrix of one structure for the user-facing readers.

Description

Workhorse of read.fs.morph.cifti and friends: like cifti.structure.data, but requires the structure to have a surface part and returns the per-vertex matrix directly. This keeps the user-facing functions working for the structures they support today, and turns the unsupported ones into a descriptive error.

Usage

cifti.dense.structure.matrix(x, structure)

Arguments

Value

a numeric matrix, one row per surface vertex, one column per index of the other matrix dimension.

Get axis labels for a matrix dimension of a CIFTI-2 file.

Description

Get a label for each index of one matrix dimension of a CIFTI-2 file, e.g. the map names of a .dscalar, the parcel names of a .pconn or identifiers for the grayordinates of a dense file. This is what read.cifti uses to name the dimensions of the data array.

Usage

cifti.dim.labels(cii, dim = 0L)

Arguments

Value

character vector of length cii$matrix$dim_sizes[dim + 1], the labels, or NULL if no labels are known for this kind of dimension.

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

Examples

cifti_file <- system.file("extdata", "cifti", "tiny.ptseries.nii", package = "freesurferformats")
cii <- read.cifti.header(cifti_file)
cifti.dim.labels(cii, dim = 1L)

Move one dimension of an array to the front.

Description

Move one dimension of an array to the front.

Usage

cifti.dim.to.front(data, dim)

Arguments

Value

the array with the requested dimension first, and all other dimensions in their original order.

Check whether a file looks like a CIFTI-1 file.

Description

This is a heuristic used to produce a helpful error message when a CIFTI-1 file is passed to the reader: CIFTI-1 files are NIFTI-1 files (not NIFTI-2), and this function searches the first bytes of the file for the string 'CIFTI'. It is not used for any other purpose.

Usage

cifti.file.looks.like.cifti1(filepath)

Arguments

Value

logical, whether the file looks like a CIFTI-1 file.

Check whether a file is a CIFTI-2 file (internal helper).

Description

Cheap and silent check whether a file is a CIFTI-2 file, i.e. a NIFTI v2 file with a header extension of code 32, the extension that holds the CIFTI XML metadata. The format dispatchers (read.fs.morph(), read.fs.volume()) use it to give a helpful error: the payload of a CIFTI-2 file is a matrix whose dimensions the XML describes, not a volume or a per-vertex vector, so reading it with the NIFTI reader silently returns values in an order that means nothing.

Usage

cifti.file.looks.like.cifti2(filepath)

Arguments

Value

logical, whether the file is a CIFTI-2 file. A file that does not exist or cannot be parsed is reported as FALSE.

Get the standard CIFTI-2 file type for a set of axes.

Description

Look up the file type that the format defines for the combination of matrix index types of the axes, see cifti.file.types.

Usage

cifti.file.type.for.axes(axes)

Arguments

Value

a one row data.frame, see cifti.file.types, or a row with intent_code = 3000 ('ConnUnknown') and empty file name extension for a combination that the standard does not define.

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

Examples

axis_brain <- cifti.axis.brain.models(list(cifti.brain.model.surface("lh", 10L)))
type <- cifti.file.type.for.axes(list(cifti.axis.scalars("m"), axis_brain))
type$extension

The CIFTI-2 file type a file name names.

Description

The CIFTI-2 file type a file name names.

Usage

cifti.file.type.for.extension(filepath)

Arguments

Value

character string, the standard file name extension the name ends with (e.g. '.pscalar.nii'), or the empty string if it does not end with one of them.

The standard CIFTI-2 file types.

Description

The nine standard CIFTI-2 file types, as defined by the format: which matrix index types the two matrix dimensions must have, the file name extension, and the NIFTI intent code and name that identify the type in the file header. The extension of a file decides which entry is used when writing, and a mismatch between the file name and the axes of the data is an error.

Usage

cifti.file.types()

Value

a data.frame with one row per file type and the columns 'extension', 'intent_code', 'intent_name', 'dim0_type' and 'dim1_type'.

Get the brainordinate table of a CIFTI-2 file.

Description

Get the mapping from the matrix indices of one dimension to the individual surface vertices and volume voxels a CIFTI-2 file contains. This is the per-index version of the table returned by cifti.structures, which reports index ranges instead of single indices. It is useful to find out which vertex or voxel a data row belongs to, or to find the data index of a vertex or voxel.

Note that the same vertex or voxel can only appear once per dimension (the matrix has one entry per brainordinate), but a structure can be split over several brain model entries, and the vertices of a grayordinates file are a subset of the vertices of the surface it refers to.

Usage

cifti.grayordinates(cii, dim = 0L)

Arguments

Value

a data.frame with one row per index of the matrix dimension and the columns 'index' (integer, 0-based matrix index), 'structure' (character string, the brain structure as spelled in the file), 'structure_short' (without the CIFTI_STRUCTURE_ prefix), 'model_type' ('SURFACE' or 'VOXELS'), 'vertex_index' (integer, 0-based index of the vertex in the surface for surface models, NA for volume models) and 'i', 'j', 'k' (integer, 0-based voxel indices for volume models, NA for surface models).

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

Examples

cifti_file <- system.file("extdata", "cifti", "tiny.dscalar.nii", package = "freesurferformats")
cii <- read.cifti.header(cifti_file)
grayordinates <- cifti.grayordinates(cii, dim = 1L)
head(grayordinates)

Build the brainordinate table of an axis.

Description

Build the brainordinate table of an axis.

Usage

cifti.grayordinates.for.axes(axis)

Arguments

Value

a data.frame, see cifti.grayordinates.

Expand one brain model entry into a brainordinate table.

Description

Expand one brain model entry into a brainordinate table.

Usage

cifti.grayordinates.for.model(map, model)

Arguments

Value

a data.frame, see cifti.grayordinates.

Create the CIFTI-2 XML metadata for a set of axes.

Description

Build the CIFTI-2 XML document (the part of a CIFTI-2 file that describes what the data matrix contains) from a set of axes. This is the inverse of the XML parsing that read.cifti.header performs: pass the result of this function to cifti.parse.xml or to read.cifti.header (after storing it in a file) and you get back the axes you put in.

Usage

cifti.header.from.axes(axes, metadata = NULL)

Arguments

Value

character string, the CIFTI-2 XML document.

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

Examples

axis_series <- cifti.axis.series(4L, start = 0, step = 2.5)
axis_brain <- cifti.axis.brain.models(list(
  cifti.brain.model.surface("lh", 10L),
  cifti.brain.model.surface("rh", 12L)))
xml <- cifti.header.from.axes(list(axis_series, axis_brain))
cat(substr(xml, 1, 200))

Accept the input forms of a CIFTI-2 header.

Description

Accept the input forms of a CIFTI-2 header.

Usage

cifti.header.of(x)

Arguments

Value

an fs.cifti object, see read.cifti.header.

The short name of a CIFTI-2 matrix index type.

Description

The short name of a CIFTI-2 matrix index type.

Usage

cifti.index.type.short(type)

Arguments

Value

character string, the type without the prefix, e.g. 'BRAIN_MODELS'.

The CIFTI-2 index types (mapping types).

Description

The CIFTI-2 index types (mapping types).

Usage

cifti.index.types()

Check whether an axis describes a connectome dimension.

Description

Check whether an axis describes a connectome dimension.

Usage

cifti.is.connectome.axis(axis)

Arguments

Value

logical, whether the axis holds brainordinates or parcels.

Get a label table from a CIFTI-2 label file.

Description

Get the label table of one label map (a .dlabel file can contain several maps). The label table maps integer label keys to names and RGBA colors, and is the CIFTI analogue of a FreeSurfer color lookup table.

Usage

cifti.label.table(cii, dim = 0L, map = 1L)

Arguments

Value

a data.frame with one row per label and the columns 'key' (integer, the label key used in the data), 'red', 'green', 'blue', 'alpha' (numeric, in range 0 to 1) and 'label' (character string, the label name), plus 'x', 'y', 'z' (numeric, the optional label coordinates; NA if not present in the file). Returns NULL if the specified matrix dimension does not contain label maps, or if the specified map has no label table.

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

Examples

cifti_file <- system.file("extdata", "cifti", "tiny.dlabel.nii", package = "freesurferformats")
cii <- read.cifti.header(cifti_file)
cifti.label.table(cii, dim = 0L, map = 1L)

Convert a label table to the format the writer expects.

Description

Convert a label table to the format the writer expects.

Usage

cifti.label.table.for.writing(label_table)

Arguments

Value

a data.frame with the columns 'key', 'red', 'green', 'blue', 'alpha' and 'label', or NULL.

Get the CIFTI indices map for a matrix dimension.

Description

Get the single MatrixIndicesMap (mapping) that describes the given matrix dimension. A CIFTI-2 file can have several mappings, and one mapping can apply to several dimensions (this is the case for connectome files like .dconn and .pconn).

Usage

cifti.map.for.dim(cii, dim)

Arguments

Value

the indices map, a named list, see read.cifti.header.

Get the name of one named map of a CIFTI-2 file.

Description

Get the name of one named map of a CIFTI-2 file.

Usage

cifti.map.name(cii, dim, map = 1L)

Arguments

Value

character string, the map name, or NULL if the map is unnamed.

Describe a CIFTI-2 index type for humans.

Description

Describe a CIFTI-2 index type for humans.

Usage

cifti.map.type.description(type)

Arguments

Value

character string, a short description.

Determine the sizes of the CIFTI matrix dimensions.

Description

The CIFTI-2 matrix dimensions 0, 1, ... are stored in the dim field of the NIFTI-2 header, starting at its 6th entry (R index vectors are 1-based, so matrix dimension 0 is entry 6). The dimension order in the XML refers to matrix dimensions, so a MatrixIndicesMap with AppliesToMatrixDimension="0" describes the 6th entry of dim.

Usage

cifti.matrix.dim.sizes(niiheader, filepath = "")

Arguments

Value

integer vector, the sizes of the matrix dimensions.

Merge explicitly given axes with the axes of a template.

Description

Merge explicitly given axes with the axes of a template.

Usage

cifti.merge.axes(axes, template_cii)

Arguments

Value

the merged list of axes, named by matrix dimension.

The CIFTI-2 brain model types.

Description

The CIFTI-2 brain model types.

Usage

cifti.model.types()

Build the NIFTI-2 header of a CIFTI-2 file.

Description

CIFTI-2 files are NIFTI-2 files whose header has a fixed shape: the matrix dimensions are stored in the dim field (dimension 0 in dim[5], dimension 1 in dim[6], which is why dim[0] is 6 for a two-dimensional matrix), the intent code names the file type, the voxel sizes, the scaling and the geometry fields are unused (the geometry of a CIFTI-2 file is in its XML), and the data start after the header extension that holds the XML.

Usage

cifti.nifti.header.for.axes(axes, intent_code, intent_name)

Arguments

Value

a named list, a NIFTI-2 header as returned by read.nifti2.header.

Get the other matrix dimension of a 2-dimensional CIFTI-2 matrix.

Description

Get the other matrix dimension of a 2-dimensional CIFTI-2 matrix.

Usage

cifti.other.dim(cii, dim)

Arguments

Value

integer, the other matrix dimension. Stops for files with more than two matrix dimensions.

Create a CIFTI-2 parcel.

Description

Create one parcel, i.e. a named set of surface vertices (per structure) and volume voxels. The name is the only label a parcellated file has: the position in the list of parcels is the parcel index, and the reader returns the names.

Usage

cifti.parcel(name, vertices = NULL, voxel_indices_ijk = NULL)

Arguments

Value

a named list, one parcel, to be passed to cifti.axis.parcels.

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

Examples

parcel <- cifti.parcel("PARCEL_A", list(CORTEX_LEFT = 0:2, CORTEX_RIGHT = 4:5))
parcel$name

Get the parcel table of a CIFTI-2 file.

Description

Get the parcels for one matrix dimension of a parcellated CIFTI-2 file. A parcel is a named set of surface vertices and/or volume voxels; its index is its position in the list (CIFTI-2 parcels have no index attribute). The vertex lists themselves are in the field 'vertices' of the fs.cifti object, see read.cifti.header.

Usage

cifti.parcels(cii, dim = 0L)

Arguments

Value

a data.frame with one row per parcel and the columns 'index' (integer, 0-based parcel index), 'name' (character string, the parcel name), 'num_vertices' (integer, the total number of surface vertices in this parcel) and 'num_voxels' (integer, the number of volume voxels in this parcel). The result is ordered by parcel index.

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

Examples

cifti_file <- system.file("extdata", "cifti", "tiny.ptseries.nii", package = "freesurferformats")
cii <- read.cifti.header(cifti_file)
cifti.parcels(cii, dim = 1L)

Get the parcels axis of a template file.

Description

Get the parcels axis of a template file.

Usage

cifti.parcels.axis.of(template_cii)

Arguments

Value

the parcels axis of the file, see cifti.axis.parcels.

Read and validate an attribute value of an XML node.

Description

Read and validate an attribute value of an XML node.

Usage

cifti.parse.attr(node, attr_name, required = FALSE, context = "")

Arguments

Value

character string, or NA_character_ if the attribute is absent and not required.

Parse the BrainModel elements of a MatrixIndicesMap element.

Description

Parse the BrainModel elements of a MatrixIndicesMap element.

Usage

cifti.parse.brain.models(node, filepath = "")

Arguments

Value

a list of lists, or NULL if there are no BrainModel elements.

Parse a required or optional child element holding integer values.

Description

Parse a required or optional child element holding integer values.

Usage

cifti.parse.child.int.vector(node, child_name, filepath = "")

Arguments

Value

integer vector, or NULL if the child element is missing or empty.

Parse the optionally present VoxelIndicesIJK child element as a matrix.

Description

Parse the optionally present VoxelIndicesIJK child element as a matrix.

Usage

cifti.parse.child.voxel.indices(node, filepath = "")

Arguments

Value

an n x 3 integer matrix of 0-based voxel indices, or NULL if the child element is missing or empty.

Parse one MatrixIndicesMap element.

Description

Parse one MatrixIndicesMap element.

Usage

cifti.parse.indices.map(node, dim_sizes, filepath = "")

Arguments

Value

a named list, see read.cifti.header.

Parse a whitespace-separated list of integers from XML text content.

Description

Parse a whitespace-separated list of integers from XML text content.

Usage

cifti.parse.int.vector(text, what = "an element", context = "")

Arguments

Value

integer vector. Empty integer vector for empty input.

Parse a CIFTI LabelTable element.

Description

Parse a CIFTI LabelTable element.

Usage

cifti.parse.label.table(node)

Arguments

Value

a data.frame with the columns 'key', 'red', 'green', 'blue', 'alpha', 'label', 'x', 'y' and 'z', or NULL if the node is missing.

Parse the MetaData element of a CIFTI XML node.

Description

Parse the MetaData element of a CIFTI XML node.

Usage

cifti.parse.metadata(node)

Arguments

Value

a named list of character strings, the metadata entries in file order. Empty list if the node has no metadata.

Parse the NamedMap elements of a MatrixIndicesMap element.

Description

Parse the NamedMap elements of a MatrixIndicesMap element.

Usage

cifti.parse.named.maps(node, filepath = "")

Arguments

Value

a list of lists with the entries 'name', 'metadata' and 'labels', or NULL if there are no NamedMap elements.

Parse a whitespace-separated list of numbers from XML text content.

Description

Parse a whitespace-separated list of numbers from XML text content.

Usage

cifti.parse.numeric.vector(text, what = "an element", context = "")

Arguments

Value

numeric vector. Empty numeric vector for empty input.

Parse the Parcel elements of a MatrixIndicesMap element.

Description

Parse the Parcel elements of a MatrixIndicesMap element.

Usage

cifti.parse.parcels(node, filepath = "")

Arguments

Value

a list of lists, or NULL if there are no Parcel elements.

Parse the series attributes of a MatrixIndicesMap element.

Description

Parse the series attributes of a MatrixIndicesMap element.

Usage

cifti.parse.series(node, filepath = "")

Arguments

Value

a named list with the entries 'number_of_series_points', 'start', 'step', 'exponent' and 'unit', or NULL if the element has no series attributes.

Parse the Surface elements of a MatrixIndicesMap element.

Description

Parse the Surface elements of a MatrixIndicesMap element.

Usage

cifti.parse.surfaces(node, filepath = "")

Arguments

Value

a list of lists with the entries 'brain_structure' and 'surface_number_of_vertices', or NULL if there are no Surface elements.

Parse the Volume elements of a MatrixIndicesMap element.

Description

Parse the Volume elements of a MatrixIndicesMap element.

Usage

cifti.parse.volumes(node, filepath = "")

Arguments

Value

a list of lists with the entries 'dimensions', 'meter_exponent' and 'transformation_matrix', or NULL if there are no Volume elements.

Parse the CIFTI XML metadata.

Description

Parse the CIFTI XML metadata.

Usage

cifti.parse.xml(xml_text, filepath = "", niiheader = NULL)

Arguments

Value

an fs.cifti object, see read.cifti.header.

Prepare per-vertex data for writing to a CIFTI-2 file.

Description

Common work of the user-facing CIFTI-2 writers: turn data that are given for the complete surface into the matrix of a dense CIFTI-2 file, i.e. one row per map (or series point, or label map) and one column per brainordinate, in the order of the grayordinates of the file.

Usage

cifti.prepare.surface.data(
  data,
  structure = NULL,
  template = NULL,
  what = "data"
)

Arguments

Value

a named list with the entries 'matrix' (the data matrix to write), 'axes' (the axes, with the brainordinate axis filled in and the other axis left NULL), 'template' (the template object or NULL) and 'template_map_axis' (the axis of the template for the other matrix dimension, or NULL).

Read the data matrix of a CIFTI-2 file.

Description

Read the data matrix of a CIFTI-2 file.

Usage

cifti.read.matrix(cii, rows = NULL, columns = NULL)

Arguments

Value

the data array, see read.cifti.

Read the requested matrix rows of a CIFTI-2 file.

Description

Workhorse of read.cifti.rows: read some indices of matrix dimension 0 without reading the rest of the rows. If a column selection is given, only those columns are read (they are contiguous blocks of the file), otherwise the file is read once, in chunks, keeping the requested rows.

Usage

cifti.read.rows(cii, rows, columns = NULL, chunk_values = 4000000L)

Arguments

Value

a numeric matrix with one row per requested row index.

Read raw values from the data section of a CIFTI-2 file.

Description

Read raw values from the data section of a CIFTI-2 file.

Usage

cifti.read.values(cii, num_values, skip_values = 0L, fh = NULL)

Arguments

Value

vector of values, see read.nifti.values.

Remove hemisphere markers from region names of a parcellation.

Description

Region names of brain atlases often carry a marker that identifies the hemisphere a region belongs to, e.g. L_superiorfrontal / R_superiorfrontal, pericalcarine_LH / pericalcarine_RH, or ⁠7Networks_LH_Vis_1⁠ / ⁠7Networks_RH_Vis_1⁠. The same region of the two hemispheres has to be recognized as one parcel when building a parcel axis for a CIFTI-2 file, so these markers are removed here.

A marker that is removed is one of L, R, LH, RH, Left or Right (matched case-insensitively), at the start of the name or at its end, followed or preceded by ⁠_⁠ or -, or enclosed by two separators anywhere in the name (in which case the two separators collapse into one). Names without such a marker are returned unchanged, and so are names that consist of nothing but a marker.

Usage

cifti.region.name.without.hemisphere(region_names)

Arguments

Value

character vector, the names without hemisphere markers.

Get the series information of a CIFTI-2 file.

Description

Get the description of the series dimension of a CIFTI-2 file, e.g. the time points of a .dtseries or .ptseries file. The time (or other unit) of the series index i is (start + i * step) * 10^exponent, with i starting at 0.

Usage

cifti.series.info(cii, dim = 0L)

Arguments

Value

a named list with the entries 'number_of_series_points' (integer), 'start' (numeric), 'step' (numeric), 'exponent' (integer) and 'unit' (character string, one of 'SECOND', 'HERTZ', 'METER', 'RADIAN'), or NULL if the specified matrix dimension is not a series. To check whether a dimension is a series, inspect the field 'type' of the corresponding entry of cii$matrix$indices_maps.

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

Examples

cifti_file <- system.file("extdata", "cifti", "tiny.dtseries.nii", package = "freesurferformats")
cii <- read.cifti.header(cifti_file)
cifti.series.info(cii, dim = 0L)

Refuse to read a CIFTI file as a volume or morphometry file.

Description

The generic readers of this package dispatch on the file name, and a CIFTI file is a NIFTI file as far as the name is concerned: read.fs.morph() used to interpret a .dscalar.nii as a NIFTI morphometry file and silently returned the raw matrix as a per-vertex vector (for the official Conte69 .dtseries, a 121,902 element vector of a 60,951 x 2 matrix, i.e. plausible looking numbers in an order that means nothing), and read.fs.volume() failed with the unrelated 'This is not a one-file NIFTI format' message of oro.nifti. This function detects the CIFTI files and stops with an error that names the reader to use instead, see read.cifti.

The check only costs a header read, and only for files whose name ends with .nii or .nii.gz, since a CIFTI file always has such a name.

Usage

cifti.stop.if.cifti(filepath)

Arguments

Value

NULL, invisibly. Stops if the file is a CIFTI file.

Refuse a CIFTI-2 file name for a file that is not a CIFTI-2 file.

Description

The writers of this package that are not CIFTI writers (write.fs.morph(), write.fs.volume()) derive the format from the file name, and a CIFTI-2 file name looks like a NIFTI name. Writing a NIFTI file under a name like .dscalar.nii would produce a file whose content contradicts its name: this package (and Connectome Workbench) refuse to read it, because the name promises the CIFTI XML metadata that describes what the matrix dimensions contain. This function turns that into an error that names the writer to use instead.

Usage

cifti.stop.if.cifti.name(filepath)

Arguments

Value

NULL, invisibly. Stops if the name is one of the standard CIFTI-2 file names.

Normalize a CIFTI brain structure name.

Description

CIFTI brain structure names are written in several spellings by different software: Connectome Workbench uses CIFTI_STRUCTURE_CORTEX_LEFT, nibabel also accepts CortexLeft, and this package uses the aliases lh and rh (and also left/right) for the cortical surfaces. This function normalizes all of them to the canonical ⁠CIFTI_STRUCTURE_*⁠ spelling.

Usage

cifti.structure.canonical(brain_structure)

Arguments

Value

character string, the canonical structure name (e.g. 'CIFTI_STRUCTURE_CORTEX_LEFT'), or NA_character_ if the input is NA.

Extract the data of one brain structure from a CIFTI-2 file.

Description

Get the data values of a single brain structure (e.g. one hemisphere) from a CIFTI-2 file, reconstructed for the full surface. The result has one row per vertex of the surface (in the order of the surface, which is the order the vertices have in the surface mesh files) and one column per index of the other matrix dimension of the file. Vertices of the surface that have no value in the file are reported as NA: grayordinates files have a reduced mesh (the medial wall vertices are missing), and returning the values for the complete surface is what makes such files usable together with the standard surface meshes of a subject.

Volume structures (a brain model of type 'CIFTI_MODEL_TYPE_VOXELS', which subcortical structures use) cannot be expanded like this, because the voxels a structure consists of are not a rectangular block of a volume and are not ordered in any meaningful way. For those, the data values are returned together with the voxel indices and the affine transformation that maps them to coordinates, see the Value section.

Usage

cifti.structure.data(x, structure = NULL, dim = NULL)

Arguments

Value

If 'structure' is a single structure: a named list with the entries 'structure' (character string, the canonical name of the structure, e.g. 'CIFTI_STRUCTURE_CORTEX_LEFT'), 'structure_short' (the name without the prefix, e.g. 'CORTEX_LEFT'), 'model_type' (character string, one of 'SURFACE', 'VOXELS' or 'SURFACE_AND_VOXELS'), 'surface' and 'volume'. If 'structure' is NULL: a named list of such lists, one per structure, named by the short structure name.

For a selection that contains a surface model, the 'surface' entry holds a numeric (or integer) array with one row per vertex of the full surface and the remaining dimensions of the data, with NA for vertices that the file does not contain. Its dimensions beyond the first are named like in read.cifti. If the selection contains no surface model, 'surface' is NULL.

For a selection that contains a volume model, the 'volume' entry holds a named list with the entries 'values' (an array like 'surface', but with one row per voxel of the structure instead of per surface vertex), 'voxel_indices_ijk' (an n x 3 integer matrix of 0-based voxel indices, in the same order as the rows of 'values'), 'dimensions' (integer vector of length 3, the dimensions of the volume the voxel indices refer to) and 'transformation_matrix' and 'meter_exponent' (the 4x4 row-major matrix from the file that maps the voxel indices to coordinates in units of 10^meter_exponent, and the exponent). If the selection contains no volume model, 'volume' is NULL.

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

Examples

cifti_file <- system.file("extdata", "cifti", "tiny.dscalar.nii", package = "freesurferformats")
cii <- read.cifti(cifti_file)
lh_data <- cifti.structure.data(cii, "lh")
dim(lh_data$surface)
# vertices beyond the end of the mesh in the file are NA:
sum(is.na(lh_data$surface[, 1]))

# Volume structures are returned with their voxel indices:
vol_file <- system.file("extdata", "cifti", "tiny_volume.dscalar.nii",
                        package = "freesurferformats")
vol_cii <- read.cifti(vol_file)
cerebellum <- cifti.structure.data(vol_cii, "CEREBELLUM")
cerebellum$volume$voxel_indices_ijk

Get the matrix dimension a brain structure lives in.

Description

The counterpart of cifti.other.dim for a structure name: look up the dimension of the file that contains brain models for the given structure. Needed by the user-facing readers, which get a structure name from the user and must decide which dimension of the data matrix it refers to.

Usage

cifti.structure.data.dim(cii, structure)

Arguments

Value

integer, the matrix dimension.

Extract the data of one brain structure (internal).

Description

Extract the data of one brain structure (internal).

Usage

cifti.structure.data.one(cii, map, brainordinates, data, structure)

Arguments

Value

a named list, see cifti.structure.data.

Resolve a user-supplied structure specifier to a canonical name.

Description

Accept the structure spellings the user-facing readers support: a structure name in any of the supported spellings, or the index of a structure in the file (deprecated, but part of the documented interface of the readers).

Usage

cifti.structure.from.specifier(cii, brain_structure)

Arguments

Value

character string, the canonical structure name.

Get the short name of a CIFTI brain structure.

Description

Strip the CIFTI_STRUCTURE_ prefix from a brain structure name, normalizing it first, see cifti.structure.canonical.

Usage

cifti.structure.short(brain_structure)

Arguments

Value

character string, the structure name without the prefix (e.g. 'CORTEX_LEFT').

Get the brain model table of a CIFTI-2 file.

Description

Get the brain model entries for one matrix dimension of a CIFTI-2 file, i.e. the mapping from matrix indices to surface vertices or volume voxels. Note that a brain structure can appear in several brain model entries: a grayordinates file can contain a surface part and a volume part for the same structure, and a structure can be split into several index ranges. Always use the index ranges from this table to map data values, never the structure names.

Usage

cifti.structures(cii, dim = 0L)

Arguments

Value

a data.frame with one row per brain model entry and the columns 'structure' (character string, the brain structure in the spelling used in the file), 'structure_short' (character string, the normalized name without the CIFTI_STRUCTURE_ prefix, e.g. 'CORTEX_LEFT'), 'model_type' ('SURFACE' or 'VOXELS'), 'index_offset' (integer, 0-based index of the first matrix entry covered by this brain model), 'index_count' (integer, the number of matrix entries covered) and 'surface_number_of_vertices' (integer, the number of vertices of the complete surface, for surface models; NA for volume models). Use index_offset and index_count to extract the data values for a brain model from the data matrix.

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

Examples

cifti_file <- system.file("extdata", "cifti", "tiny.dscalar.nii", package = "freesurferformats")
cii <- read.cifti.header(cifti_file)
cifti.structures(cii, dim = 1L)

Subset one dimension of an array.

Description

Subset one dimension of an array.

Usage

cifti.subset.dim(data, dim, selection)

Arguments

Value

the subset, with the dimensions of data preserved.

Get the number of vertices of one surface of a CIFTI-2 mapping.

Description

Get the size of the complete surface a brain model refers to. The Surface elements of the mapping are used if the file has them, otherwise the SurfaceNumberOfVertices attributes of the brain models are used: the Surface elements are optional, and the files written by Connectome Workbench (including the official CIFTI-2 example files) do not contain any, they report the surface size in the brain models only.

Usage

cifti.surface.vertex.count(map, structure)

Arguments

Value

integer, the number of vertices, or NA_integer_ if the structure has no surface model in this mapping.

Get the number of vertices of the surfaces declared in a CIFTI mapping.

Description

Get the number of vertices of the surfaces declared in a CIFTI mapping.

Usage

cifti.surface.vertex.counts(map)

Arguments

Value

named integer vector, the number of vertices per canonical brain structure short name (e.g. 'CORTEX_LEFT'). Empty if the mapping declares no surfaces.

Validate the axes of a CIFTI-2 file.

Description

Check the things about a set of axes that make a file invalid rather than just unusual: the sizes of the axes, the index ranges of the brain models, the structures a volume model or a parcel refers to, and the label keys of a label table.

Usage

cifti.validate.axes(axes)

Arguments

Value

NULL, invisibly. Stops with a descriptive error.

Validate the brain model entries of a CIFTI mapping.

Description

Validate the brain model entries of a CIFTI mapping.

Usage

cifti.validate.brain.models(map, dim_size, filepath = "")

Arguments

Value

NULL, invisibly. Stops with a descriptive error if an entry is inconsistent.

Check that all matrix dimensions are described exactly once.

Description

Check that all matrix dimensions are described exactly once.

Usage

cifti.validate.dims.coverage(indices_maps, dim_sizes, filepath = "")

Arguments

Value

NULL, invisibly. Stops if a dimension is described twice or not at all.

Check the file extension against the axes of the data.

Description

A CIFTI-2 file name states the file type (.dscalar, .pdconn, ...), and the type decides which matrix index types the two dimensions have. A file whose name contradicts its content is silently misread by other software, so this is an error.

Usage

cifti.validate.file.extension(filepath, file_type)

Arguments

Value

NULL, invisibly. Stops if the file name names a different file type.

Check that all indices are within a valid range.

Description

Check that all indices are within a valid range.

Usage

cifti.validate.index.range(indices, max_index, what, filepath = "")

Arguments

Value

NULL, invisibly. Stops with a descriptive error if an index is out of range.

Validate a parsed CIFTI MatrixIndicesMap.

Description

Check that the mapping is consistent with the size of the matrix dimension it describes, and that the index ranges it declares are valid. These checks exist because a mismatch would silently misalign the data.

Usage

cifti.validate.indices.map(map, filepath = "")

Arguments

Value

NULL, invisibly. Stops with a descriptive error if the mapping is inconsistent.

Validate the parcels of a CIFTI mapping.

Description

Validate the parcels of a CIFTI mapping.

Usage

cifti.validate.parcels(map, filepath = "")

Arguments

Value

NULL, invisibly. Stops with a descriptive error if a parcel refers to vertices outside of a declared surface.

Check the safety limit for reading a CIFTI-2 data matrix.

Description

Check the requested allocation against the package safety limit (see validate_allocation_size) and add a CIFTI specific hint to the error message if it is exceeded: the data of a large file can be read in parts by selecting matrix columns, which is not possible in the same way for other image formats.

Usage

cifti.validate.read.size(dims, bytes_per_elem, filepath)

Arguments

Value

NULL, invisibly. Stops if the limit is exceeded.

Create a CIFTI-2 axis for a volume.

Description

A volume axis describes the voxel grid that the volume brain models of a CIFTI-2 file refer to: its dimensions and the 4x4 transformation matrix that maps the (0-based) IJK voxel indices to coordinates. The matrix is stored row by row in the file, and the coordinates it produces are in units of 10^meter_exponent (which is -3, i.e. millimeters, for the files that Connectome Workbench writes).

Usage

cifti.volume(dimensions, transformation_matrix, meter_exponent = -3L)

Arguments

Value

a named list with the entries 'dimensions', 'meter_exponent' and 'transformation_matrix', to be passed to cifti.axis.brain.models or cifti.axis.parcels.

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

Examples

volume <- cifti.volume(c(4L, 4L, 4L), diag(c(2, 2, 2, 1)))
volume$dimensions

Add a MatrixIndicesMap element to the Matrix element.

Description

Add a MatrixIndicesMap element to the Matrix element.

Usage

cifti.xml.add.indices.map(matrix_node, axis, dims)

Arguments

Value

NULL, invisibly. The element is added as a child of matrix_node.

Add a MetaData element to an XML node.

Description

Add a MetaData element to an XML node.

Usage

cifti.xml.add.metadata(node, metadata)

Arguments

Value

NULL, invisibly. The element is added as a child of node.

Format an integer vector for an XML text node.

Description

Format an integer vector for an XML text node.

Usage

cifti.xml.int.vector(x)

Arguments

Value

character string, the values separated by single spaces.

Format a number like the reference implementations do.

Description

Connectome Workbench writes fixed point values with 10 decimal places in the XML (e.g. SeriesStep="2.5000000000"), and this keeps the output comparable with the files it writes. Colors of a label table are written with the precision the file had, which is 3 decimal places in the official example files.

Usage

cifti.xml.num(x, decimals = 10L)

Arguments

Value

character string.

Format a numeric vector for an XML text node.

Description

Format a numeric vector for an XML text node.

Usage

cifti.xml.num.vector(x, decimals = 10L)

Arguments

Value

character string, the values separated by single spaces.

The CIFTI version this package writes.

Description

The CIFTI version this package writes.

Usage

cifti.xml.version()

Value

character string, '2'.

Find vertex index closest to given query coordinate using Euclidean distance.

Description

Find vertex index closest to given query coordinate using Euclidean distance.

Usage

closest.vert.to.point(surface, point_coords)

Arguments

Value

named list with entries: 'vertex_id' integer vector, the index of the closest vertex, and 'dist': double vector, the Euclidean distance to that vertex.

See Also

Other Euclidean distance util functions: vertex.euclid.dist(), vertexdists.to.point()

Extract color lookup table (LUT) from annotation.

Description

Extract a colortable lookup table (LUT) from an annotation. Such a LUT can also be read from files like FREESURFER_HOME/FreeSurferColorLUT.txt or saved as a file, check the 'See Also' section below.

Usage

colortable.from.annot(annot, compute_colorcode = FALSE)

Arguments

Value

the colortable data.frame extracted from the annotation.

See Also

Other atlas functions: atlas.from.lut.and.csv(), read.fs.annot(), read.fs.colortable(), write.atlas.to.lut.and.csv(), write.fs.annot(), write.fs.annot.gii(), write.fs.colortable()

Other colorLUT functions: read.fs.colortable(), write.fs.colortable()

Examples

annotfile <- system.file("extdata", "lh.aparc.annot.gz",
  package = "freesurferformats", mustWork = TRUE
)
annot <- read.fs.annot(annotfile)
colortable <- colortable.from.annot(annot)
head(colortable)

Compute the bounding box of a set of coordinates.

Description

Compute the bounding box of a set of coordinates.

Usage

coord.bbox(coords)

Arguments

Value

numeric vector of length 6, c(xmin, xmax, ymin, ymax, zmin, zmax), or NULL if there are no rows.

Turn coordinate vector into string.

Description

Turn coordinate vector into string.

Usage

coord.to.key(coord, digits = 6L)

Arguments

Value

character string

Delete all data in the package cache.

Description

Delete all data in the package cache.

Usage

delete_all_opt_data()

Value

integer. The return value of the unlink() call: 0 for success, 1 for failure. See the unlink() documentation for details.

Detect the format of a DTI tract file.

Description

Detect the format of a DTI tract file.

Usage

detect.dti.tract.format(filepath)

Arguments

Value

character string, one of 'tck', 'tsf' or 'trk'.

Apply a spatial transformation matrix to the given coordinates.

Description

Apply a spatial transformation matrix to the given coordinates.

Usage

doapply.transform.mtx(coords, mtx, as_mat = FALSE)

Arguments

Value

the coords after applying the transformation. If coords was nx3, nx3 is returned, otherwise nx4.

Examples

coords_tf <- doapply.transform.mtx(c(1.0, 1.0, 1.0), mni152reg())
coords_tf
doapply.transform.mtx(coords_tf, solve(mni152reg()))

Download optional data for the freesurferformats package.

Description

Ensure that the optional data is available locally in the package cache. Will try to download the data only if it is not available. This data is not required for the package to work, but it is used in the examples, in the unit tests and also in the example code from the vignette. Downloading it is highly recommended. The downloaded data files are owned by their respective copyright holders and are subject to their respective licenses; see the file 'inst/COPYRIGHTS' for attribution and license details.

Usage

download_opt_data(
  dl_from = c("rcmd.org", "github_fsf_release"),
  scheme = c("https", "http")
)

Arguments

Value

Named list. The list has entries: "available": vector of strings. The names of the files that are available in the local file cache. You can access them using get_optional_data_file(). "missing": vector of strings. The names of the files that this function was unable to retrieve.

Compute the bounding box of all tract coordinates in a file.

Description

Streams through the tract file and returns the bounding box of all coordinates, without keeping the coordinates in memory. This is useful to determine the axis limits for plotting a large tractogram.

Usage

dti.track.bbox(filepath, chunk_values = 4e+06)

Arguments

Value

numeric vector of length 6, c(xmin, xmax, ymin, ymax, zmin, zmax), or NULL if the file contains no coordinates. The coordinates are in the coordinate system used by the file, see the note in read.dti.trk.

Examples

## Not run: 
bbox <- dti.track.bbox("brain.tck");

## End(Not run)

Count the tracts in a DTI tract file.

Description

Counts the tracts in a TRK, TCK or TSF file without reading their coordinates, so this works on arbitrarily large tractograms with a small and constant amount of memory. This is the equivalent of tckinfo <file> -count in MRtrix.

Usage

dti.track.count(filepath, chunk_values = 4e+06)

Arguments

Value

integer, the number of tracts in the file. Note that this can differ from the count entry in the file header, which the MRtrix documentation explicitly describes as unreliable, and which does not count empty tracts.

Examples

## Not run: 
dti.track.count("brain.tck");

## End(Not run)

Create an iterator over the tracts of a DTI tract file.

Description

Reads a TRK, TCK or TSF file tract by tract, so that a tractogram of any size can be processed with a constant amount of memory. This is the low-level interface behind dti.track.count and friends, use it when neither reading a subset (max_tracks, skip_tracks, bbox in read.dti.tck) nor one of the aggregate functions fits your use case.

The returned object is an environment with the following entries:

• next.track(): returns the next tract (a n x 3 matrix for TCK, a numeric vector of per-point values for TSF, and a list with the entries coords, num_points, scalars and properties for TRK, just like tracks[[i]] does for the readers), or NULL when there are no more tracts.

• close(): closes the underlying file connection. It is safe to call this more than once, and it is also called automatically when the iterator is garbage collected.

• tracks.read: the number of tracts returned so far.

• filepath, format: the file and its detected format.

Usage

dti.track.iterator(
  filepath,
  skip_tracks = 0L,
  bbox = NULL,
  chunk_values = 4e+06
)

Arguments

Value

the iterator environment, see the description.

Examples

## Not run: 
itr <- dti.track.iterator("brain.tck");
total_points <- 0;
while (!is.null(track <- itr$next.track())) {
  total_points <- total_points + nrow(track);
}
itr$close();

## End(Not run)

Compute Euclidean distance.

Description

Compute Euclidean distance.

Usage

euclidian.dist(x1, x2)

Arguments

Value

the Euclidean distance between x1 and x2.

Convert quadrangular faces or polygons to triangular ones.

Description

Convert quadrangular faces or polygons to triangular ones.

Usage

faces.quad.to.tris(quad_faces)

Arguments

Value

2nx3 integer matrix, the indices of the vertices making up the 2n tris faces.

Note

This function does no fancy remeshing, it simply splits each quad into two triangles.

See Also

Other mesh functions: read.fs.surface(), read.fs.surface.asc(), read.fs.surface.bvsrf(), read.fs.surface.geo(), read.fs.surface.gii(), read.fs.surface.ico(), read.fs.surface.obj(), read.fs.surface.off(), read.fs.surface.ply(), read.fs.surface.vtk(), read.mesh.brainvoyager(), read_nisurface(), read_nisurfacefile(), write.fs.surface(), write.fs.surface.asc(), write.fs.surface.byu(), write.fs.surface.gii(), write.fs.surface.mz3(), write.fs.surface.vtk()

Convert tris faces to quad faces by simple merging.

Description

This is experimental. Note that it can only work if the number of 'tris_faces' is even, as two consecutive tris-faces will be merged into one quad face. We could set the index to NA in that case, but I do not know how FreeSurfer handles this, so we do not guess.

Usage

faces.tris.to.quad(tris_faces)

Arguments

Value

n/2x4 integer matrix, the indices of the vertices making up the n quad faces.

Note

This function does not implement proper remeshing of tri-meshes to quad-meshes. Use a proper mesh library if you need that.

Get connection to a binary file, gz or not.

Description

Get connection to a binary file, gz or not.

Usage

fileopen.gz.or.not(filepath)

Arguments

Open a connection for writing, with gzip support based on the file name.

Description

Open a connection for writing, with gzip support based on the file name.

Usage

fileopen.write.gz.or.not(filepath)

Arguments

Value

a connection, either a gzfile or a plain file connection.

Check whether filepath ends with extension.

Description

Check whether filepath ends with extension.

Usage

filepath.ends.with(filepath, extensions)

Arguments

Value

logical, whether the filepath end with one of the extensions.

Check which rows of a matrix consist of finite values only.

Description

Check which rows of a matrix consist of finite values only.

Usage

finite.rows(mat)

Arguments

Value

logical vector with one entry per row.

Write fixed width integers to one or several lines.

Description

Write fixed width integers to one or several lines.

Usage

fixed.vec.format.int(
  vdata,
  num_chars_per_entry,
  max_entries_per_line = NULL,
  align_right = TRUE
)

Arguments

Value

vector of character strings, the formatted data lines.

Flip a 2D matrix.

Description

Flip a 2D matrix.

Usage

flip2D(slice, how = "horizontally")

Arguments

Value

2D matrix, the flipped matrix.

Flip a 3D array along an axis.

Description

Flip the slice of an 3D array horizontally or vertically along an axis. This leads to an output array with identical dimensions.

Usage

flip3D(volume, axis = 1L, how = "horizontally")

Arguments

Value

a 3D image volume, flipped around the axis. The dimensions are identical to the dimensions of the input image.

See Also

Other volume math: rotate3D()

Format a number of bytes for human consumption.

Description

Used in the error messages of validate_allocation_size, so that sizes below one gigabyte stay readable. A limit of a few hundred kilobytes would otherwise be reported as '0.00 GB', which is useless when debugging a failed read.

Usage

format_bytes_human(num_bytes)

Arguments

Value

character string, the size with a unit.

Read 3-byte integer.

Description

Read a 3-byte integer from a binary file handle. Advances the pointer accordingly.

Usage

fread3(filehandle)

Arguments

Value

integer, The read integer.

Determine morphometry file extension from format

Description

Given a morphometry file format, derive the proper file extension.

Usage

fs.get.morph.file.ext.for.format(format)

Arguments

Value

file ext, string. The standard file extension for the format. (May be an empty string for some formats.)

See Also

Other morphometry functions: fs.get.morph.file.format.from.filename(), read.fs.curv(), read.fs.mgh(), read.fs.morph(), read.fs.morph.gii(), read.fs.volume(), read.fs.weight(), write.fs.curv(), write.fs.label.gii(), write.fs.mgh(), write.fs.morph(), write.fs.morph.asc(), write.fs.morph.gii(), write.fs.morph.ni1(), write.fs.morph.ni2(), write.fs.morph.smp(), write.fs.morph.txt(), write.fs.weight(), write.fs.weight.asc()

Determine morphometry file format from filename

Description

Given a morphometry file name, derive the proper file format, based on the end of the string. Case is ignored, i.e., cast to lowercase before checks. If the filepath ends with "mgh", returns format "mgh". For suffix "mgz", returns "mgz" format. For all others, returns "curv" format.

Usage

fs.get.morph.file.format.from.filename(filepath)

Arguments

Value

format, string. The format, one of c("mgz", "mgh", "curv", "gii", "smp").

See Also

Other morphometry functions: fs.get.morph.file.ext.for.format(), read.fs.curv(), read.fs.mgh(), read.fs.morph(), read.fs.morph.gii(), read.fs.volume(), read.fs.weight(), write.fs.curv(), write.fs.label.gii(), write.fs.mgh(), write.fs.morph(), write.fs.morph.asc(), write.fs.morph.gii(), write.fs.morph.ni1(), write.fs.morph.ni2(), write.fs.morph.smp(), write.fs.morph.txt(), write.fs.weight(), write.fs.weight.asc()

Constructor for fs.patch

Description

Constructor for fs.patch

Usage

fs.patch(vertices, faces = NULL)

Arguments

Value

instance of class fs.patch

See Also

Other patch functions: read.fs.patch(), read.fs.patch.asc(), write.fs.patch()

Examples

num_vertices <- 6L
# a tiny patch
vertices <- matrix(rep(0., num_vertices * 5), ncol = 5)
vertices[, 1] <- seq.int(num_vertices)
# 1-based vertex indices
vertices[, 2:4] <- matrix(rnorm(num_vertices * 3, 8, 2), ncol = 3)
# vertex coords
vertices[, 5] <- rep(0L, num_vertices)
# is_border
vertices[3, 5] <- 1L
# set a vertex to be a border vertex
patch <- fs.patch(vertices)
patch

Get an rgl tmesh3d instance from a brain surface mesh.

Description

Convert fs.surface to tmesh without the rgl package.

Usage

fs.surface.to.tmesh3d(surface)

Arguments

Value

a tmesh3d instance representing the surface, see rgl::tmesh3d for details. It has classes mesh3d and shape3d.

Create an fs.tracts instance from a compact tract representation.

Description

Creates the compact container used by the DTI tract readers and writers. Reading a track file with read.dti.tck, read.dti.trk or read.dti.tsf returns instances of this class, and this function is the way to build one from your own data, e.g., to write a tractogram that was assembled or edited in R with write.dti.tck or write.dti.trk.

Usage

fs.tracts(coords, lengths, scalars = NULL, properties = NULL, kind = "tck")

Arguments

Value

an fs.tracts instance.

Examples

# Two tracts, the first with two points and the second with one.
coords <- matrix(c(0, 0, 0, 1, 1, 1, 5, 5, 5), ncol = 3, byrow = TRUE);
tracts <- fs.tracts(coords, lengths = c(2L, 1L));
length(tracts);
tracts[[1]];

Get the concatenated coordinates of fs.tracts instances.

Description

Returns all tract coordinates as a single N x 3 matrix, with the tracts concatenated along the rows. This is the compact representation used internally, and the fastest way to access all coordinates, e.g., for plotting or for computing a bounding box.

Usage

fs.tracts.coords(tracts)

Arguments

Value

numeric matrix with 3 columns and one row per point of all tracts.

Examples

## Not run: 
tck <- read.dti.tck("brain.tck");
coords <- fs.tracts.coords(tck$tracks);
bbox <- apply(coords, 2, range);

## End(Not run)

Get the number of tracts.

Description

Get the number of tracts.

Usage

fs.tracts.count(tracts)

Arguments

Value

integer, the number of tracts.

Get the number of points of each tract.

Description

Returns one integer per tract, the number of points it consists of. The coordinates of tract i are the rows (cumsum(c(1, lengths))[i]):(cumsum(lengths)[i]) of fs.tracts.coords().

Usage

fs.tracts.lengths(tracts)

Arguments

Value

integer vector with one entry per tract.

Examples

## Not run: 
tck <- read.dti.tck("brain.tck");
lengths <- fs.tracts.lengths(tck$tracks);
mean(lengths);

## End(Not run)

Get the total number of points of all tracts.

Description

Get the total number of points of all tracts.

Usage

fs.tracts.point.count(tracts)

Arguments

Value

integer, the total number of points.

Create an fs.transform instance.

Description

An fs.transform is a linear transformation matrix together with the coordinate spaces that it maps between. It is the common representation that all transformation file format readers and writers in this package return and accept, so that a matrix read from a file always states what its numbers mean: a bare 4x4 matrix does not tell whether it maps voxel indices or world coordinates, in which direction it goes, or whether the voxel indices are zero- or one-based.

The matrix field always maps from the source to the target, i.e., applying it to a coordinate means ⁠target_coord = matrix \%*\% c(source_coord, 1)⁠, which is the same convention that doapply.transform.mtx uses. The inverse of the transformation is never stored, see invert.fs.transform.

Usage

fs.transform(
  matrix,
  space_in = NA_character_,
  space_out = NA_character_,
  voxel_base = NA_integer_,
  src = NULL,
  dst = NULL,
  format = NA_character_,
  source = NULL,
  type = NULL,
  ...
)

Arguments

Value

an fs.transform instance.

Compute the matrix that maps FSL voxel coordinates of a volume to FSL world coordinates.

Description

FSL does not use the world coordinates of the image header. Its tools work in a space in which the voxel axes have unit length (the voxel sizes are divided out) and in which the first voxel axis points to the left, i.e. the transformation has a negative determinant, which is why FSL calls its images 'radiological'. For a volume whose header already uses that convention, the FSL space equals the header space; otherwise the first axis is flipped, and the origin of that axis is moved to the other end of the volume.

This function implements the mapping that both MRtrix3 (in ⁠transformconvert ... flirt_import⁠) and FreeSurfer (in lta_convert --infsl) apply, and it was verified against both of them on real data: the resulting transformation matrix is identical to the one of these tools up to numerical precision, while the plain composition of the header voxel-to-RAS matrices is not (it differs by more than 100 mm on real data).

Usage

fsl.scaled.voxel.matrix(geometry)

Arguments

Value

4x4 numerical matrix, the transformation from (zero-based) voxel indices to FSL world coordinates.

Write 3-byte integer.

Description

Write a 3-byte integer to a binary file handle.

Usage

fwrite3(filehandle, data)

Arguments

Determine endianness of TRK file.

Description

Determine endianness of TRK file.

Usage

get.dti.trk.endianness(filepath)

Arguments

Value

endina character string. one of 'little' or 'big'.

Note

This function checks endiannes via the header size field of the file header, which must be 1000 for TRK files when read with correct enianness. It will stop if the file is not in TRK format, i.e., if the field is not 1000 in any endianness.

Compute MGH orientation string and direction

Description

Compute MGH orientation string and direction

Usage

get.slice.orientation(Mdc)

Arguments

Value

named list with entries: orientation_string: character string of length 3, one uppercase letter per axis. direction_name: slice direction, character string, one of 'sagittal', 'coronal', 'axial' or 'unknown'.

Get the configured maximum allocation size in bytes.

Description

Returns the maximum number of bytes that the package is allowed to allocate when reading binary data payloads. The limit is resolved in this order: (1) environment variable FREESURFERFORMATS_MAX_ALLOC_BYTES, (2) R option freesurferformats.max_alloc_bytes, (3) the hard-coded default of 2 GB. Set the limit to Inf to disable the check.

Usage

get_max_alloc_bytes()

Value

a single numeric value, the maximum allocation size in bytes.

Access a single file from the package cache by its file name.

Description

Access a single file from the package cache by its file name.

Usage

get_opt_data_filepath(filename, mustWork = TRUE)

Arguments

Value

string. The full path to the file in the package cache or the empty string if there is no such file available. Use this in your application code to open the file.

Write data to a gifti file.

Description

Write data to a gifti file.

Usage

gifti_writer(filepath, ...)

Arguments

References

https://www.nitrc.org/frs/download.php/2871/GIFTI_Surface_Format.pdf

Examples

## Not run: 
outfile <- tempfile(fileext = ".gii")
dataarrays <- list(rep(3.1, 3L), matrix(seq(6), nrow = 2L))
gifti_writer(outfile, dataarrays, datatype = c("NIFTI_TYPE_FLOAT32", "NIFTI_TYPE_INT32"))

## End(Not run)

Get GIFTI XML representation of data.

Description

Creates a GIFTI XML tree from your datasets (vectors and matrices). The tree can be further modified to add additional data, or written to a file as is to produce a valid GIFTI file (see gifti_xml_write).

Usage

gifti_xml(
  data_array,
  intent = "NIFTI_INTENT_SHAPE",
  datatype = "NIFTI_TYPE_FLOAT32",
  encoding = "GZipBase64Binary",
  endian = "LittleEndian",
  transform_matrix = NULL,
  force = FALSE
)

Arguments

Value

xml tree, see xml2 package. One could modify this tree as needed using xml2 functions, e.g., add metadata.

Note

Unless you want to modify the returned tree manually, you should not need to call this function. Use gifti_writer instead.

References

See https://www.nitrc.org/frs/download.php/2871/GIFTI_Surface_Format.pdf

See Also

The example for gifti_xml_write shows how to modify the tree.

Examples

## Not run: 
my_data_sets <- list(rep(3.1, 3L), matrix(seq(6) + 0.1, nrow = 2L))
transforms <- list(NA, list(
  "transform_matrix" = diag(4), "data_space" = "NIFTI_XFORM_UNKNOWN",
  "transformed_space" = "NIFTI_XFORM_UNKNOWN"
))
xmltree <- gifti_xml(my_data_sets, datatype = "NIFTI_TYPE_FLOAT32", transform_matrix = transforms)
# Verify that the tree is a valid GIFTI file:
gifti_xsd <- "https://www.nitrc.org/frs/download.php/158/gifti.xsd"
xml2::xml_validate(xmltree, xml2::read_xml(gifti_xsd))

## End(Not run)

Add metadata to GIFTI XML tree.

Description

Add metadata to GIFTI XML tree.

Usage

gifti_xml_add_global_metadata(xmltree, metadata_named_list, as_cdata = TRUE)

Arguments

Value

the modified tree.

Note

Assumes that there already exists a global MetaData node. Also not that this is not supposed to be used for adding metadata to datarrays.

Examples

## Not run: 
xmltree <- gifti_xml(list(rep(3.1, 3L), matrix(seq(6) + 0.1, nrow = 2L)))
newtree <- gifti_xml_add_global_metadata(xmltree, list("User" = "Me", "Weather" = "Great"))
gifti_xsd <- "https://www.nitrc.org/frs/download.php/158/gifti.xsd"
xml2::xml_validate(newtree, xml2::read_xml(gifti_xsd))

## End(Not run)

Write XML tree to a gifti file.

Description

Write XML tree to a gifti file.

Usage

gifti_xml_write(filepath, xmltree, options = c("as_xml", "format"))

Arguments

References

https://www.nitrc.org/frs/download.php/2871/GIFTI_Surface_Format.pdf

Examples

## Not run: 
outfile <- tempfile(fileext = ".gii")
my_data_sets <- list(rep(3.1, 3L), matrix(seq(6) + 0.1, nrow = 2L))
xmltree <- gifti_xml(my_data_sets, datatype = "NIFTI_TYPE_FLOAT32")
# Here we add global metadata:
xmltree <- gifti_xml_add_global_metadata(xmltree, list("User" = "Me", "Day" = "Monday"))
# Validating your XML never hurts
gifti_xsd <- "https://www.nitrc.org/frs/download.php/158/gifti.xsd"
xml2::xml_validate(xmltree, xml2::read_xml(gifti_xsd))
gifti_xml_write(outfile, xmltree)
# Write your custom tree to a file.

## End(Not run)

Add a label tabel from an annotation to a GIFTI XML tree.

Description

Computes the LabelTable XML node for the given annotation and adds it to the XML tree.

Usage

giftixml_add_labeltable_from_annot(xmltree, annot)

Arguments

Value

XML tree from xml2, the modified tree with the LabelTable added below the root node.

Add a standard label tabel for to a GIFTI XML tree.

Description

This label table is suitable for labels in the FreeSurfer sense, i.e., if only a positive label (1) and a negative label (0) exist in the label data.

Usage

giftixml_add_labeltable_posneg(xmltree)

Arguments

Value

XML tree from xml2, the modified tree with the LabelTable added below the root node.

Compute the first row of every group in a concatenated matrix.

Description

Compute the first row of every group in a concatenated matrix.

Usage

group.start.rows(lengths)

Arguments

Value

integer vector with one entry per group.

Check which groups have at least one point inside a box.

Description

Check which groups have at least one point inside a box.

Usage

groups.in.bbox(points, lengths, bbox)

Arguments

Value

logical vector with one entry per group.

Guess whether a file is gzipped.

Description

Guess whether a file is gzipped, based on the file extension.

Usage

guess.filename.is.gzipped(filepath, gz_extensions = c(".gz", ".mgz"))

Arguments

Value

logical, whether this function thinks the file is gzipped.

Determine the format of a transformation file.

Description

Guess the format of a transformation file from its extension and its content. Content is needed because the extension '.mat' is used by FSL for text matrices and by ANTs/ITK for binary transformations, which have nothing in common. A file that is identified as an ITK/ANTs transformation is reported as such instead of failing with a parse error, since that format is not supported yet.

Usage

guess.transform.format(filepath)

Arguments

Value

character string, the file format, one of 'xfm', 'dat', 'lta' or 'fslmat'.

Determine the format of a transformation file to write.

Description

Guess the transformation file format from the file name extension, for the formats this package can write.

Usage

guess.writable.transform.format(filepath)

Arguments

Value

character string, the file format.

Check for pandoc availability on system.

Description

Check for pandoc availability on system.

Usage

has_pandoc()

Value

logical, whether Pandoc is available.

Check which rows of a matrix consist of infinite values only.

Description

Check which rows of a matrix consist of infinite values only.

Usage

infinite.rows(mat)

Arguments

Value

logical vector with one entry per row.

Convert 32 bit integer to RGB color as described in Brainvoyager SRF file spec.

Description

Convert 32 bit integer to RGB color as described in Brainvoyager SRF file spec.

Usage

int.to.col.brainvoyager(int_val)

Arguments

Value

an rgb color

Build the affine that undoes an orientation transform.

Description

This is the equivalent of nibabel.orientations.inv_ornt_aff(): given an orientation and the shape of the array it was applied to, it returns the affine that maps coordinates in the transformed space back to coordinates in the original space.

Usage

inv.ornt.aff(ornt, shape)

Arguments

Value

a 4x4 numeric matrix.

Invert a transformation.

Description

Compute the transformation that undoes the given one, i.e. the one that maps the target coordinates back to the source coordinates. The source and target of the result are swapped, along with the coordinate spaces, and the matrix is inverted. A transformation is never stored inverted, use this function when you need the reverse mapping.

Usage

invert.fs.transform(tf)

Arguments

Value

an fs.transform instance that maps from the target of tf back to its source.

Note

The format-specific fields of tf (e.g. the parsed header and the volume info of an LTA file, or the intensity of a register.dat file) describe the file that tf was read from and are therefore copied to the result unchanged. They are metadata, not part of the mapping.

See Also

Other header coordinate space: is.fs.transform(), mghheader.is.ras.valid(), mghheader.ras2vox(), mghheader.ras2vox.tkreg(), mghheader.scanner2tkreg(), mghheader.tkreg2scanner(), mghheader.vox2ras(), mghheader.vox2ras.tkreg(), print.fs.transform(), read.fs.transform(), read.fs.transform.dat(), read.fs.transform.fslmat(), read.fs.transform.itk(), read.fs.transform.lta(), read.fs.transform.xfm(), sm0to1(), sm1to0(), summary.fs.transform(), transform2lps(), transform2ras(), transform2voxel(), transform2world(), write.fs.transform(), write.fs.transform.dat(), write.fs.transform.fslmat(), write.fs.transform.itk(), write.fs.transform.lta(), write.fs.transform.xfm()

Examples

tf <- read.fs.transform(system.file("extdata", "talairach.xfm",
  package = "freesurferformats", mustWork = TRUE
))
tf_back <- invert.fs.transform(tf)
tf_back$space_in # the spaces are swapped
max(abs(tf_back$matrix %*% tf$matrix - diag(4))) # the identity

Determine the orientation of an affine's input axes.

Description

For each of the 3 input (voxel) axes, determines which output (world) axis it corresponds to and whether it is flipped. This is the simplified equivalent of nibabel.orientations.io_orientation(): the dominant output axis of every input axis is used, with output axes removed from consideration once they have been assigned. nibabel additionally applies a polar decomposition first, which only matters for affines that contain shear.

Usage

io.orientation(affine)

Arguments

Value

numeric matrix with 3 rows and 2 columns, as returned by io.orientation. Row i holds the 0-based output axis index and the direction (+1 or -1) of input axis i.

Check whether a file is an ANALYZE 7.5 file.

Description

Check whether a file is an ANALYZE 7.5 file.

Usage

is.analyze.file(filepath)

Arguments

Value

logical, whether the 348 byte header is an ANALYZE 7.5 header. This is the case when the header contains neither of the two NIFTI v1 magic strings, i.e. when the magic is empty. Files that use the ni1 magic are NIFTI v1 pair files, see read.nifti1.header, and files with the n+1 magic are single file NIFTI v1 files.

Note

Note that this function returns TRUE for any two-file header that does not carry a NIFTI magic, which is what "ANALYZE 7.5" means in practice: these files were written by ANALYZE itself, by SPM, by AFNI or by FreeSurfer. Only the fields of the ANALYZE specification are defined for them, but SPM stores extra information in fields that ANALYZE leaves unused, see read.fs.volume.analyze.

A file path that does not describe an existing pair file (for example a single file NIFTI image, or a file that does not exist) returns FALSE rather than an error.

Examples

hdrfile <- system.file("extdata", "analyze", "tiny_u8.hdr",
  package = "freesurferformats", mustWork = TRUE
)
is.analyze.file(hdrfile)

Check whether object is a bvsmp instance.

Description

Check whether object is a bvsmp instance.

Usage

is.bvsmp(x)

Arguments

Value

TRUE if its argument is an bvsmp instane (that is, has "bvsmp" amongst its classes) and FALSE otherwise.

Check whether object is an fs.annot

Description

Check whether object is an fs.annot

Usage

is.fs.annot(x)

Arguments

Value

TRUE if its argument is a brain surface annotation (that is, has "fs.annot" amongst its classes) and FALSE otherwise.

Check whether object is an fs.label

Description

Check whether object is an fs.label

Usage

is.fs.label(x)

Arguments

Value

TRUE if its argument is a brain surface label (that is, has fs.label amongst its classes) and FALSE otherwise.

Check whether object is an fs.surface

Description

Check whether object is an fs.surface

Usage

is.fs.surface(x)

Arguments

Value

TRUE if its argument is a brain surface (that is, has "fs.surface" amongst its classes) and FALSE otherwise.

Check whether an object is an fs.tracts instance.

Description

Check whether an object is an fs.tracts instance.

Usage

is.fs.tracts(x)

Arguments

Value

logical, TRUE if x is an fs.tracts instance.

Examples

is.fs.tracts("not tracts");

Check whether an object is an fs.transform instance.

Description

Check whether an object is an fs.transform instance.

Usage

is.fs.transform(x)

Arguments

Value

logical, whether x is an fs.transform instance.