Package 'freesurferformats'

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)

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)

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

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.)

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.

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);

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)

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)

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

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.

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

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

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

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)

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

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)

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

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

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

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)

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

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)

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))

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)

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

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)

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)

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

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)

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

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()

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)

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.

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()))

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.

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)

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)

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)

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()

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.

Description

Flip a 2D matrix.

Usage

flip2D(slice, how = "horizontally")

Arguments

Value

2D matrix, the flipped matrix.

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()

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()

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()

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

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.

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]];

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)

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)

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.

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)

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)

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)

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)

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.

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

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)

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.

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.

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.

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.

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");

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.

See Also

Other header coordinate space: invert.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
))
is.fs.transform(tf)
is.fs.transform("no transform")

Description

Check whether object is an fs.volume

Usage

is.fs.volume(x)

Arguments

Value

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

Description

Check whether object is an mghheader

Usage

is.mghheader(x)

Arguments

Value

TRUE if its argument is an MGH header (that is, has "mghheader" amongst its classes) and FALSE otherwise.

Description

Number of tracts in an fs.tracts instance.

Usage

## S3 method for class 'fs.tracts'
length(x)

Arguments

Value

integer, the number of tracts.

Description

Get file names of optional data files which are available in the local package cache. You can access these files with get_optional_data_file().

Usage

list_opt_data()

Value

vector of strings. The file names available, relative to the package cache.

Description

Compute RAS coords of center voxel.

Usage

mghheader.centervoxelRAS.from.firstvoxelRAS(header, first_voxel_RAS)

Arguments

Value

numerical vector of length 3, the RAS coordinate of the center voxel. Also known as CRAS or center RAS.

Description

Compute MGH volume orientation string.

Usage

mghheader.crs.orientation(header)

Arguments

Value

character string of length 3, one uppercase letter per axis. Each of the three position is a letter from the alphabet: ⁠LRISAP?⁠. The meaning is L for left, R for right, I for inferior, S for superior, P for posterior, A for anterior. If the direction cannot be computed, all three characters are ⁠?⁠ for unknown. Of course, each axis (L/R, I/S, A/P) is only represented once in the string.

Description

In the FreeSurfer sense, conformed means that the volume is in coronal primary slice direction, has dimensions 256x256x256 and a voxel size of 1 mm in all 3 directions. The slice direction can only be determined if the header contains RAS information, if it does not, the volume is not conformed.

Usage

mghheader.is.conformed(header)

Arguments

Value

logical, whether the volume is conformed.

Description

Check whether header contains valid ras information

Usage

mghheader.is.ras.valid(header)

Arguments

Value

logical, whether header contains valid ras information (according to the ras_good_flag).

See Also

Other header coordinate space: invert.fs.transform(), is.fs.transform(), 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

brain_image <- system.file("extdata", "brain.mgz",
  package = "freesurferformats",
  mustWork = TRUE
)
vdh <- read.fs.mgh(brain_image, with_header = TRUE)
mghheader.is.ras.valid(vdh$header)

Description

Compute MGH primary slice direction

Usage

mghheader.primary.slice.direction(header)

Arguments

Value

character string, the slice direction. One of 'sagittal', 'coronal', 'axial' or 'unknown'.

Description

This is also known as the 'scanner' or 'native' ras2vox. It is the inverse of the respective vox2ras, see mghheader.vox2ras.

Usage

mghheader.ras2vox(header)

Arguments

Value

4x4 numerical matrix, the transformation matrix

See Also

sm1to0

Other header coordinate space: invert.fs.transform(), is.fs.transform(), mghheader.is.ras.valid(), 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

brain_image <- system.file("extdata", "brain.mgz",
  package = "freesurferformats",
  mustWork = TRUE
)
vdh <- read.fs.mgh(brain_image, with_header = TRUE)
mghheader.ras2vox(vdh$header)

Description

This is also known as the 'tkreg' ras2vox. It is the inverse of the respective vox2ras, see mghheader.vox2ras.tkreg.

Usage

mghheader.ras2vox.tkreg(header)

Arguments

Value

4x4 numerical matrix, the transformation matrix

See Also

sm1to0

Other header coordinate space: invert.fs.transform(), is.fs.transform(), mghheader.is.ras.valid(), mghheader.ras2vox(), 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

brain_image <- system.file("extdata", "brain.mgz",
  package = "freesurferformats",
  mustWork = TRUE
)
vdh <- read.fs.mgh(brain_image, with_header = TRUE)
mghheader.ras2vox.tkreg(vdh$header)

Description

This is also known as the 'scanner2tkreg' matrix. Note that this is a RAS-to-RAS matrix. It is the inverse of the 'tkreg2scanner' matrix, see mghheader.tkreg2scanner.

Usage

mghheader.scanner2tkreg(header)

Arguments

Value

4x4 numerical matrix, the transformation matrix

See Also

Other header coordinate space: invert.fs.transform(), is.fs.transform(), mghheader.is.ras.valid(), mghheader.ras2vox(), mghheader.ras2vox.tkreg(), 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

brain_image <- system.file("extdata", "brain.mgz",
  package = "freesurferformats",
  mustWork = TRUE
)
vdh <- read.fs.mgh(brain_image, with_header = TRUE)
mghheader.scanner2tkreg(vdh$header)

Description

This is also known as the 'tkreg2scanner' matrix. Note that this is a RAS-to-RAS matrix. It is the inverse of the 'scanner2tkreg' matrix, see mghheader.scanner2tkreg.

Usage

mghheader.tkreg2scanner(header)

Arguments

Value

4x4 numerical matrix, the transformation matrix

See Also

Other header coordinate space: invert.fs.transform(), is.fs.transform(), mghheader.is.ras.valid(), mghheader.ras2vox(), mghheader.ras2vox.tkreg(), mghheader.scanner2tkreg(), 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

brain_image <- system.file("extdata", "brain.mgz",
  package = "freesurferformats",
  mustWork = TRUE
)
vdh <- read.fs.mgh(brain_image, with_header = TRUE)
mghheader.tkreg2scanner(vdh$header)

Description

Update mghheader fields from vox2ras matrix.

Usage

mghheader.update.from.vox2ras(header, vox2ras)

Arguments

Value

a named list representing the header

Description

This is also known as the 'scanner' or 'native' vox2ras. It is the inverse of the respective ras2vox, see mghheader.ras2vox.

Usage

mghheader.vox2ras(header)

Arguments

Value

4x4 numerical matrix, the transformation matrix

See Also

sm0to1

Other header coordinate space: invert.fs.transform(), is.fs.transform(), mghheader.is.ras.valid(), mghheader.ras2vox(), mghheader.ras2vox.tkreg(), mghheader.scanner2tkreg(), mghheader.tkreg2scanner(), 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

brain_image <- system.file("extdata", "brain.mgz",
  package = "freesurferformats",
  mustWork = TRUE
)
vdh <- read.fs.mgh(brain_image, with_header = TRUE)
mghheader.vox2ras(vdh$header)

Description

This is also known as the 'tkreg' vox2ras. It is the inverse of the respective ras2vox, see mghheader.ras2vox.tkreg.

Usage

mghheader.vox2ras.tkreg(header)

Arguments

Value

4x4 numerical matrix, the transformation matrix

See Also

sm0to1

Other header coordinate space: invert.fs.transform(), is.fs.transform(), mghheader.is.ras.valid(), mghheader.ras2vox(), mghheader.ras2vox.tkreg(), mghheader.scanner2tkreg(), mghheader.tkreg2scanner(), mghheader.vox2ras(), 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

brain_image <- system.file("extdata", "brain.mgz",
  package = "freesurferformats",
  mustWork = TRUE
)
vdh <- read.fs.mgh(brain_image, with_header = TRUE)
mghheader.vox2ras.tkreg(vdh$header)

Description

Compute vox2vox matrix between two volumes.

Usage

mghheader.vox2vox(header_from, header_to)

Arguments

Value

4x4 numerical matrix, the transformation matrix

Description

The uses the 4x4 matrix from the FreeSurfer CoordinateSystems documentation.

Usage

mni152reg()

Note

There are better ways to achieve this transformation than using this matrix, see Wu et al., 'Accurate nonlinear mapping between MNI volumetric and FreeSurfer surface coordinate system', Hum Brain Mapp. 2018 Sep; 39(9): 3793–3808. doi: 10.1002/hbm.24213. The mentioned method is available in R from the 'regfusionr' package (GitHub only atom, not on CRAN).

Examples

coords_tf <- doapply.transform.mtx(c(10.0, -20.0, 35.0), mni152reg())
coords_tf
#  10.695, -18.409, 36.137
doapply.transform.mtx(coords_tf, solve(mni152reg()))

Description

Create NIFTI v1 header suitable for given data.

Usage

ni1header.for.data(niidata, allow_fshack = FALSE, pair = FALSE)

Arguments

Value

a NIFTI v1 header (see ni1header.template) in which the datatype, bitpix, dim and dim_raw fields have been set to values suitable for the given data. Feel free to change the other fields.

Description

Create a template NIFTI v1 header. You will have to adapt it for your use case.

Usage

ni1header.template(pair = FALSE)

Arguments

Value

named list, the NIFTI v1 header. All fields are present and filled with values of a proper type. Whether or not they make sense is up to you, but you will most likely have to adapt at least the following fields to your data: dim_raw, datatype, bitpix.

Note

Commonly used data type settings are: for signed integers datatype = 8L and bitpix = 32L; for floats datatype = 16L and bitpix = 32L. See the NIFTI v1 standard for more options. You may want to call ni1header.for.data instead of this function.

See Also

ni1header.for.data

Description

Create NIFTI v2 header suitable for given data.

Usage

ni2header.for.data(niidata)

Arguments

Value

a NIFTI v2 header (see ni2header.template) in which the datatype, bitpix, dim and dim_raw fields have been set to values suitable for the given data. Feel free to change the other fields.

Description

Create a template NIFTI v2 header. You will have to adapt it for your use case.

Usage

ni2header.template()

Value

named list, the NIFTI v2 header. All fields are present and filled with values of a proper type. Whether or not they make sense is up to you, but you will most likely have to adapt at least the following fields to your data: dim_raw, datatype, bitpix.

Note

Commonly used data type settings are: for signed integers datatype = 8L and bitpix = 32L; for floats datatype = 16L and bitpix = 32L. See the NIFTI v2 standard for more options. You may want to call ni2header.for.data instead of this function.

The 'magic' field of a NIFTI v2 file must be the string 'n+2'. Versions of this package before 1.1.0 wrote the NIFTI v1 magic 'n+1' here, which violates the standard and makes other software (nibabel, Connectome Workbench) refuse the file; write.nifti2 writes the full 8 byte magic of the standard.

See Also

ni2header.for.data

Description

Compute data dimensions from the 'dim' field of the NIFTI (v1 or v2) header.

Usage

nifti.datadim.from.dimfield(dimfield)

Arguments

Value

integer vector of length <= 7. The lengths of the used data dimensions. The 'dim' field always has length 8, and the first entry is the number of actually used dimensions. The return value is constructed by stripping the first field and returning the used fields.

See Also

Other NIFTI helper functions: nifti.datadim.to.dimfield()

Examples

nifti.datadim.from.dimfield(c(3, 256, 256, 256, 1, 1, 1, 1))

Description

Compute NIFTI dim field for data dimension.

Usage

nifti.datadim.to.dimfield(datadim)

Arguments

Value

NIFTI header dim field, an integer vector of length 8

See Also

Other NIFTI helper functions: nifti.datadim.from.dimfield()

Examples

nifti.datadim.to.dimfield(c(256, 256, 256))

Description

Determine whether a NIFTI file uses the FreeSurfer hack.

Usage

nifti.file.uses.fshack(filepath)

Arguments

Value

logical, whether the file header contains the FreeSurfer format hack. See read.nifti1.header for details. This function detects NIFTI v2 files, but as they cannot contain the hack, it will always return FALSE for them.

Note

Applying this function to files which are not in NIFTI format will result in an error. See nifti.file.version to determine whether a file is a NIFTI file.

Description

Determine NIFTI file version information and whether file is a NIFTI file.

Usage

nifti.file.version(filepath)

Arguments

Value

integer, the NIFTI file version. One if 1 for NIFTI v1 files, 2 for NIFTI v2 files, or NULL if the file is not a NIFTI file.

Description

Perform basic sanity checks on NIFTI header data. These are in no way meant to be exhaustive.

Usage

nifti.header.check(niiheader, nifti_version = 1L)

Arguments

Value

logical, whether the check was okay

Description

NIFTI v2 files can store arbitrary data in header extensions, in the area between the header and the voxel data. This function creates such an extension. Pass the result to write.nifti2, which writes it to the file, and later read it back with read.nifti2.header plus nifti2.get.extension.

Usage

nifti2.extension(ecode, content = NULL)

Arguments

Value

named list with the entries 'ecode' and 'content', representing one NIFTI v2 header extension.

See Also

nifti2.get.extension, nifti2.extension.text

Other nifti2 extensions: nifti2.extension.content(), nifti2.extension.size(), nifti2.extension.text(), nifti2.get.extension()

Description

Convert the payload of a header extension to a character string. The trailing NUL bytes, which are only used to pad the extension to a multiple of 16 bytes, are removed. Note that embedded NUL bytes cannot be represented in an R string and are removed as well, so this function is only meaningful for text payloads (like the CIFTI2 XML metadata).

Usage

nifti2.extension.text(extension)

Arguments

Value

character string, the payload of the extension. The string is marked as UTF-8 encoded, which is the encoding required by the NIFTI standard.

See Also

Other nifti2 extensions: nifti2.extension(), nifti2.extension.content(), nifti2.extension.size(), nifti2.get.extension()

Description

Retrieve one header extension from a NIFTI v2 header, by its extension code. See nifti2.extension for details on header extensions.

Usage

nifti2.get.extension(niiheader, ecode)

Arguments

Value

the extension (a named list with entries 'ecode' and 'content', see nifti2.extension), or NULL if the header contains no extension with this code.

See Also

nifti2.extension.text

Other nifti2 extensions: nifti2.extension(), nifti2.extension.content(), nifti2.extension.size(), nifti2.extension.text()

Description

Create a NIFTI v1 header from the header information contained in an fs.volume instance.

Usage

nii1header.for.mgh(mgh, endian = "little", pair = FALSE)

Arguments

Value

a NIFTI v1 header structure (see ni1header.template). Note that the header may or may not contain full RAS information, depending on whether the source fs.volume contained such information or not. If the MGH header does not have valid RAS information, the qform and sform codes will be set to 0 (unknown).

Note

This is intended to be used with write.nifti1, which allows users to convert MGH/MGZ data to NIFTI files.

See Also

Other nifti1 writers: write.fs.morph.ni1(), write.nifti1()

Description

Print a tract file iterator.

Usage

## S3 method for class 'dti.track.iterator'
print(x, ...)

Arguments

Value

the iterator, invisibly.

Description

Print description of a brain atlas or annotation.

Usage

## S3 method for class 'fs.annot'
print(x, ...)

Arguments

Description

Print an fs.cifti instance.

Usage

## S3 method for class 'fs.cifti'
print(x, ...)

Arguments

Value

the instance, invisibly.

See Also

Other cifti functions: cifti.axis.brain.models(), cifti.axis.from.template(), cifti.axis.labels(), cifti.axis.parcels(), cifti.axis.parcels.from.annot(), cifti.axis.scalars(), cifti.axis.series(), cifti.brain.model.surface(), cifti.brain.model.volume(), cifti.dim.labels(), cifti.file.type.for.axes(), cifti.grayordinates(), cifti.header.from.axes(), cifti.label.table(), cifti.parcel(), cifti.parcels(), cifti.series.info(), cifti.structure.data(), cifti.structures(), cifti.volume(), print.fs.cifti.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()

Description

Print an fs.cifti.data instance.

Usage

## S3 method for class 'fs.cifti.data'
print(x, ...)

Arguments

Value

the instance, invisibly.

See Also

Other cifti functions: cifti.axis.brain.models(), cifti.axis.from.template(), cifti.axis.labels(), cifti.axis.parcels(), cifti.axis.parcels.from.annot(), cifti.axis.scalars(), cifti.axis.series(), cifti.brain.model.surface(), cifti.brain.model.volume(), cifti.dim.labels(), cifti.file.type.for.axes(), cifti.grayordinates(), cifti.header.from.axes(), cifti.label.table(), cifti.parcel(), cifti.parcels(), cifti.series.info(), cifti.structure.data(), cifti.structures(), cifti.volume(), print.fs.cifti(), print.fs.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()

Description

Print an fs.connectome instance.

Usage

## S3 method for class 'fs.connectome'
print(x, ...)

Arguments

Value

the instance, invisibly.

See Also

Other cifti functions: cifti.axis.brain.models(), cifti.axis.from.template(), cifti.axis.labels(), cifti.axis.parcels(), cifti.axis.parcels.from.annot(), cifti.axis.scalars(), cifti.axis.series(), cifti.brain.model.surface(), cifti.brain.model.volume(), cifti.dim.labels(), cifti.file.type.for.axes(), cifti.grayordinates(), cifti.header.from.axes(), cifti.label.table(), cifti.parcel(), cifti.parcels(), cifti.series.info(), cifti.structure.data(), cifti.structures(), cifti.volume(), print.fs.cifti(), print.fs.cifti.data(), 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()

Description

Print description of a brain surface label.

Usage

## S3 method for class 'fs.label'
print(x, ...)

Arguments