Type:	Package
Title:	Tools for Reading, Writing, Viewing and Manipulating CIFTI Files
Version:	0.17.4
Maintainer:	Amanda Mejia <mandy.mejia@gmail.com>
Description:	CIFTI files contain brain imaging data in "grayordinates," which represent the gray matter as cortical surface vertices (left and right) and subcortical voxels (cerebellum, basal ganglia, and other deep gray matter). 'ciftiTools' provides a unified environment for reading, writing, visualizing and manipulating CIFTI-format data. It supports the "dscalar," "dlabel," and "dtseries" intents. Grayordinate data is read in as a "xifti" object, which is structured for convenient access to the data and metadata, and includes support for surface geometry files to enable spatially-dependent functionality such as static or interactive visualizations and smoothing.
License:	GPL-3
URL:	https://github.com/mandymejia/ciftiTools
BugReports:	https://github.com/mandymejia/ciftiTools/issues
Depends:	R (≥ 3.5.0)
Imports:	fields, gifti (> 0.7.5), grDevices, oro.nifti, RNifti, RColorBrewer, rgl, viridisLite, xml2
Suggests:	covr, ggplot2, ggpubr, grid, gridExtra, htmlwidgets, manipulateWidget, webshot2, knitr, rmarkdown, png, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Encoding:	UTF-8
RoxygenNote:	7.3.2
Language:	en-US
NeedsCompilation:	no
Packaged:	2025-01-23 21:08:40 UTC; ddpham
Author:	Amanda Mejia [aut, cre], Damon Pham [aut], John Muschelli [ctb]
Repository:	CRAN
Date/Publication:	2025-01-23 22:20:02 UTC

ciftiTools: Tools for Reading and Visualizing CIFTI Brain Files

Description

Here are groups of commonly-used functions in ciftiTools:

Details

Functions for reading in CIFTI or GIFTI data:

read_xifti:

Read in a CIFTI file as a "xifti"

read_xifti2:

Read in GIFTI files as a "xifti"

as.xifti:

Combine numeric data to form a "xifti"

read_surf:

Read in a surface GIFTI file as a "surf"

info_cifti:

Read the metadata in a CIFTI file

load_surf:

Read in a surface included in ciftiTools

load_parc:

Read in a parcellation included in ciftiTools

Functions for writing CIFTI or GIFTI data:

write_cifti:

Write a "xifti" to a CIFTI file

write_xifti2:

Write a "xifti" to GIFTI and NIFTI files

write_metric_gifti:

Write a numeric data matrix to a metric GIFTI file

write_surf_gifti:

Write a "surf" to a surface GIFTI file

write_subcort_nifti:

Write subcortical data to NIFTI files

separate_cifti:

Separate a CIFTI file into GIFTI and NIFTI files

Functions for manipulating "xifti"s:

apply_xifti:

Apply a function along the rows or columns of the "xifti" data matrix

combine_xifti:

Combine multiple "xifti"s with non-overlapping brain structures

convert_xifti:

Convert the intent of a "xifti"

merge_xifti:

Concatenate data matrices from multiple "xifti"s

newdata_xifti:

Replace the data matrix in a "xifti"

remove_xifti:

Remove a brain structure or surface from a "xifti"

select_xifti:

Select data matrix columns of a "xifti"

transform_xifti:

Apply a univariate transformation to a "xifti" or pair of "xifti"s

add_surf:

Add surfaces to a "xifti"

move_from_mwall:

Move medial wall vertices back into the "xifti" data matrix

move_to_mwall:

Move rows with a certain value into the "xifti" medial wall mask

S3 methods for "xifti"s:

summary and print:

Summarize the contents.

as.matrix:

Convert data to a locations by measurements numeric matrix.

dim:

Obtain number of locations and number of measurements.

plot:

Visualize the cortical surface and/or subcortical data.

+, -, *, /, ^, %%, %/%:

Operation between a "xifti" and a scalar, or between two "xifti"s.

abs, ceiling, exp, floor, log, round, sign, and sqrt:

Univariate transformation of "xifti" data.

Functions for working with surfaces:

read_surf:

Read in a surface GIFTI file as a "surf"

is.surf:

Verify a "surf"

write_surf_gifti:

Write a "surf" to a surface GIFTI file

view_surf:

Visualize a "surf"

resample_surf:

Resample a "surf"

rotate_surf:

Rotate the geometry of a "surf"

Author(s)

Maintainer: Amanda Mejia mandy.mejia@gmail.com

Authors:

• Damon Pham damondpham@gmail.com (ORCID)

Other contributors:

• John Muschelli muschellij2@gmail.com (ORCID) [contributor]

See Also

Useful links:

• https://github.com/mandymejia/ciftiTools

• Report bugs at https://github.com/mandymejia/ciftiTools/issues

Message on attach

Description

Direct user to indicate Connectome Workbench path and check gifti package version.

Usage

.onAttach(...)

Arguments

Value

NULL, invisibly

ROI_brainstructures

Description

ROI_brainstructures

Arguments

"ROY_BIG_BL" color palette

Description

"ROY_BIG_BL", the default palette from the Connectome Workbench.

Usage

ROY_BIG_BL(min = 0, max = 1, mid = NULL, half = NULL, pos_half = FALSE)

Arguments

Details

Yields the landmark color hex codes and values for the "ROY_BIG_BL" palette. This is the same color palette as the default Connectome Workbench palette. Source: https://github.com/Washington-University/workbench/blob/master/src/Files/PaletteFile.cxx

Value

A data.frame with two columns: "color" (character: color hex codes) and "value" (numeric)

See Also

Other coloring: expand_color_pal(), make_color_pal(), use_color_pal()

"xifti" S3 Math methods

Description

Math methods for "xifti" objects.

Usage

## S3 method for class 'xifti'
Math(x, ...)

Arguments

Details

Uses transform_xifti.

"xifti" S3 Ops methods

Description

Ops methods for "xifti" objects.

Usage

## S3 method for class 'xifti'
Ops(e1, e2 = NULL)

Arguments

Details

Uses transform_xifti.

"xifti" S3 Summary methods

Description

Summary methods for "xifti" objects.

Usage

## S3 method for class 'xifti'
Summary(..., na.rm = FALSE)

Arguments

Add HCP surface(s) to a "xifti"

Description

Add left or right cortical surface geometry from the HCP S1200 release to a "xifti" object.

Usage

add_surf(xifti, surfL = NULL, surfR = NULL)

Arguments

Details

surfL will be added to xifti$surf$cortex_left and surfR will be added to xifti$surf$cortex_right. Any existing surfaces will be overwritten.

If the resolutions of the data and surfaces do not match, the surfaces will be resampled to match the resolution of the data. The barycentric resampling method, which is recommended for anatomical surfaces, will be used.

Value

the "xifti" object with added surface geometry components.

See Also

Other manipulating xifti: apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Other surface-related: boundary_mask_surf(), edit_mask_surf(), even_vert_samp(), is.surf(), load_surf(), mask_surf(), read_surf(), resample_surf(), rotate_surf(), surf_area(), view_surf(), write_surf_gifti()

All integers?

Description

Check if a data vector or matrix is all integers.

Usage

all_integers(x)

Arguments

Value

Logical. Is x all integers?

Apply function over locations in each parcel

Description

Apply a function across all locations in each parcel, for a pair of data and parcellation "xifti" objects that are in registration with one another. By default, the mean value in each parcel is calculated.

Usage

apply_parc(
  xii,
  parc,
  FUN = mean,
  mwall_value = NA,
  return_as = c("matrix", "xifti"),
  ...
)

Arguments

Value

A P \times Q matrix, where P is the number of parcels and Q is the length of the output of FUN. (For mean, Q = 1).

See Also

Other parcellation-related: load_parc(), load_sub_parc(), parc_add_subcortex(), parc_borders(), parc_vals_to_xifti()

Other manipulating xifti: add_surf(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Apply a function along the rows or columns of a "xifti"

Description

Apply a many-to-N function (e.g. mean) to the rows or columns of a "xifti". If applied row-wise, a "xifti" with N data column(s) is returned. (If the "xifti" had the dlabel intent, and values that are not labels are created, then it is converted to dscalar.) If applied column-wise, a numeric matrix with N rows is returned.

For univariate functions, use transform_xifti instead.

Usage

apply_xifti(xifti, margin = c(1, 2), FUN, ...)

Arguments

Value

A "xifti" if margin == 1, or a numeric matrix if margin == 2

See Also

Other manipulating xifti: add_surf(), apply_parc(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

area_original_Param

Description

area_original_Param

Arguments

area_target_Param

Description

area_target_Param

Arguments

Convert a "xifti" to a matrix

Description

Converts a "xifti" to a matrix by concatenating the data from each brainstructure along the rows. Surfaces and metadata are discarded.

Usage

## S3 method for class 'xifti'
as.matrix(x, subcortex_by_bs = FALSE, ...)

Arguments

Value

The input as a matrix. Each brainstructure's data is concatenated.

Format metric data as a "gifti"

Description

Format a V \times T numeric matrix (V vertices, T measurements) or a length-T list of length-V numeric vectors as a "gifti" using a template "gifti". The brain hemisphere (left or right) must be indicated.

Usage

as.metric_gifti(
  data,
  hemisphere = c("left", "right"),
  intent = "NONE",
  data_type = NULL
)

Arguments

Details

If data is already a "gifti", data$data will be used and any metadata will be overwritten by the template or discarded.

Value

The "gifti"

Format surface data as a "gifti"

Description

Format a "surf" or a list with elements "pointset" and "triangle" as a "gifti" using a template "gifti". The brain hemisphere (left or right) must be indicated.

Usage

as.surf_gifti(surf, hemisphere = c("left", "right"))

Arguments

Value

The "gifti"

Assemble a "xifti" from data

Description

Assembles cortical data, subcortical data, and/or surface geometry to form a "xifti". The inputs must be data objects (vectors, matrices or arrays, depending on the argument).

Usage

as.xifti(
  cortexL = NULL,
  cortexL_mwall = NULL,
  cortexR = NULL,
  cortexR_mwall = NULL,
  mwall_values = c(NA, NaN),
  subcortVol = NULL,
  subcortLabs = NULL,
  subcortMask = NULL,
  surfL = NULL,
  surfR = NULL,
  col_names = NULL,
  HCP_32k_auto_mwall = TRUE,
  validate = TRUE
)

as_xifti(
  cortexL = NULL,
  cortexL_mwall = NULL,
  cortexR = NULL,
  cortexR_mwall = NULL,
  mwall_values = c(NA, NaN),
  subcortVol = NULL,
  subcortLabs = NULL,
  subcortMask = NULL,
  surfL = NULL,
  surfR = NULL
)

as.cifti(
  cortexL = NULL,
  cortexL_mwall = NULL,
  cortexR = NULL,
  cortexR_mwall = NULL,
  mwall_values = c(NA, NaN),
  subcortVol = NULL,
  subcortLabs = NULL,
  subcortMask = NULL,
  surfL = NULL,
  surfR = NULL
)

as_cifti(
  cortexL = NULL,
  cortexL_mwall = NULL,
  cortexR = NULL,
  cortexR_mwall = NULL,
  mwall_values = c(NA, NaN),
  subcortVol = NULL,
  subcortLabs = NULL,
  subcortMask = NULL,
  surfL = NULL,
  surfR = NULL
)

Arguments

Details

Each data or surface component is optional. Metadata components (cortex[L/R]_mwall, subcortLabs, and subcortMask) will be ignored if its corresponding data component is not provided. If no data or surface components are provided, then the template_xifti will be returned.

If cortical data are provided without a corresponding medial wall mask, or if the provided mask is invalid or empty, then the medial wall will be inferred from data rows that are constantly a value in mwall_values. But if mwall_values is NULL, no attempt to infer the medial wall will be made and the medial wall metadata entry will be NULL.

The total number of grayordinates will be G = (V_L - mwall_L) + (V_R - mwall_R) + V_S: V_L - mwall_L left vertices, V_R - mwall_R right vertices and V_S subcortical voxels. T, the total number of measurements (columns of data), must be the same for each brainstructure.

Value

A "xifti"

See Also

Other reading: info_cifti(), load_parc(), load_surf(), read_cifti(), read_surf(), read_xifti2()

Assure this is a parcellation

Description

Assure an input "xifti" object represents a parcellation. Keep only the first column if multiple columns are present.

Usage

assure_parc(parc)

Arguments

Value

parc, if it's a parcellation.

Boundary region of a mask

Description

Identify the vertices within boundary_width edges of a vertex in the input mask on a triangular mesh. Returns a logical indicating if a vertex is within boundary_width edges of the mask.

Usage

boundary_mask_surf(faces, mask, boundary_width = 10)

Arguments

Value

A length-V logical vector. Each entry corresponds to the vertex with the same index. The value is true if a vertex is within boundary_width edges of a vertex in the mask, but is not within the mask itself.

See Also

Other surface-related: add_surf(), edit_mask_surf(), even_vert_samp(), is.surf(), load_surf(), mask_surf(), read_surf(), resample_surf(), rotate_surf(), surf_area(), view_surf(), write_surf_gifti()

brainstructures

Description

brainstructures

Arguments

Check CIFTI type

Description

Check that a CIFTI's NIFTI intent matches its file name extension.

Usage

check_cifti_type(intent, extn)

Arguments

Value

If the intent is supported, returns TRUE. If the intent is not supported, an error is raised.

Validate a ciftiTools option and value

Description

Checks if a ciftiTools option and value are valid.

Usage

ciftiTools.checkOption(opt, val = NULL)

Arguments

Value

The (corrected) val

ciftiTools files

Description

CIFTI and surface GIFTI files included in the ciftiTools package

Usage

ciftiTools.files()

Details

The CIFTI files are from NITRC: cifti-2_test_data-1.2.zip at https://www.nitrc.org/frs/?group_id=454

The surfaces are from the HCP and are included according to these data use terms: Data were provided [in part] by the Human Connectome Project, WU-Minn Consortium (Principal Investigators: David Van Essen and Kamil Ugurbil; 1U54MH091657) funded by the 16 NIH Institutes and Centers that support the NIH Blueprint for Neuroscience Research; and by the McDonnell Center for Systems Neuroscience at Washington University.

Only the inflated surfaces are available as GIFTI files. To access the other surfaces included in the package (very inflated and midthickness), see load_surf.

Value

a list of file paths

Get a ciftiTools option

Description

Gets an R option (with prefix "ciftiTools_") value. See ciftiTools.listOptions.

Usage

ciftiTools.getOption(opt)

Arguments

Value

The value, val

List ciftiTools options

Description

List ciftiTools options

Usage

ciftiTools.listOptions()

Value

data.frame describing the options

Set a ciftiTools option

Description

Sets an R option (with prefix "ciftiTools_"). See ciftiTools.listOptions.

Usage

ciftiTools.setOption(opt, val)

Arguments

Value

The new value, val

Print suppressible message

Description

Print message only if ciftiTools Option "suppress_msgs" is FALSE.

Usage

ciftiTools_msg(msg)

Arguments

Value

NULL, invisibly

Print suppressible warning

Description

Print warning only if ciftiTools Option "suppress_msgs" is FALSE.

Usage

ciftiTools_warn(warn)

Arguments

Value

NULL, invisibly

Get CIFTI component suffix default

Description

Get the default file name suffix for a certain type of GIFTI/NIFTI file

Usage

cifti_component_suffix(label, GIFTI_type = "func")

Arguments

Value

The default file name suffix

cifti_fname

Description

cifti_fname

Arguments

Combine "xifti"s with non-overlapping brain structures

Description

Combine two to three "xifti"s with non-overlapping brain structures into a single "xifti". The names, intent, and surfaces of the first will be used, if present. To add more surfaces to the result, use add_surf.

Usage

combine_xifti(..., xii_list = NULL, meta = c("first", "all"))

Arguments

Value

A "xifti" with data from the inputs

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Confirm the Connectome Workbench command path

Description

Confirm that the path to the Connectome Workbench executable is valid. (For example, if the "wb_path" option was relative and the user changed the current working directory, the path is no longer valid.)

Usage

confirm_wb_cmd_path(wb_path)

Arguments

Value

NULL, invisibly

Convert "xifti"

Description

Convert the intent of a CIFTI file or "xifti" object

Usage

convert_xifti(
  x,
  to = c("dscalar", "dtseries", "dlabel"),
  cifti_target_fname = NULL,
  ...
)

convert_to_dlabel(
  x,
  cifti_target_fname = NULL,
  levels_old = NULL,
  levels = NULL,
  labels = NULL,
  nsig = Inf,
  colors = "Set2",
  add_white = TRUE,
  return_conversion_table = FALSE
)

convert_to_dscalar(x, cifti_target_fname = NULL, names = NULL)

convert_to_dtseries(
  x,
  cifti_target_fname = NULL,
  time_start = 0,
  time_step = 1,
  time_unit = c("second", "hertz", "meter", "radian")
)

Arguments

Value

If x is a CIFTI, the target is a "dlabel" and return_conversion_table, a length-2 list with the first entry being the ".dlabel" "xifti" and the second being the conversion table. Otherwise, the "xifti" or the output CIFTI file name is directly returned.

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Examples

## Not run: 
# Example: change label names
levels_old <- xii$meta$cifti$labels[[1]]$Key
newLabels <- paste0("New Label #", seq(length(levels_old)))
xii <- convert_to_dlabel(xii, levels_old=levels_old, levels=levels_old, labels=newLabels)
# Example: add an empty level
levels_old <- xii$meta$cifti$labels[[1]]$Key
levels_old <- c(levels_old, max(levels_old)+1)
labels <- c(rownames(xii$meta$cifti$labels[[1]]), "Empty")
xii <- convert_to_dlabel(xii, levels_old=levels_old, levels=levels_old, labels=labels)
# Example: set all but the lowest value to the same value & re-label
levels_old <- xii$meta$cifti$labels[[1]]$Key
levels <- ifelse(levels_old==min(levels_old), min(levels_old), min(levels_old)+1)
labels <- ifelse(levels_old==min(levels_old), "Minimum", "Not minimum")
xii <- convert_to_dlabel(xii, levels_old=levels_old, levels=levels, labels=labels)

## End(Not run)

Convert coordinate list to volume

Description

Converts a sparse coordinate list to its non-sparse volumetric representation.

Usage

coordlist_to_vol(coords, fill = FALSE)

Arguments

Value

The volumetric data

Crop image

Description

Crop whitespace from image

Usage

crop_image(x, dims = seq(2))

Arguments

Value

The cropped image

Crop a 3D array

Description

Remove empty (zero-valued) edge slices from a 3D array.

Usage

crop_vol(x)

Arguments

Dimensions of a "xifti"

Description

Returns the number of rows (vertices + voxels) and columns (measurements) in the "xifti" data.

Usage

## S3 method for class 'xifti'
dim(x)

Arguments

Value

The number of rows and columns in the "xifti" data.

Distance from mask on surface

Description

Identify the vertices within boundary_width edges of a vertex in the input mask on a triangular mesh. Returns the number of edges a vertex is away from the closest mask vertex.

Usage

dist_from_mask_surf(faces, mask, boundary_width = 10)

Arguments

Value

A length-V numeric vector. Each entry corresponds to the vertex with the same index. For vertices within the boundary, the value will be the number of vertices away from the closest vertex in the input mask. Vertices inside the input mask but at the edge of it (i.e. the vertices that define the boundary) will have value 0. Then, all other vertices will have value -1.

Edit mask on surface

Description

Erode, dilate, or get the borders of a mask along the cortical surface

Usage

edit_mask_surf(
  x,
  mwall = NULL,
  surf = NULL,
  hemisphere = c("left", "right"),
  do = c("erode", "dilate", "borders"),
  depth = 1
)

erode_mask_surf(
  x,
  mwall = NULL,
  surf = NULL,
  hemisphere = c("left", "right"),
  depth = 1
)

dilate_mask_surf(
  x,
  mwall = NULL,
  surf = NULL,
  hemisphere = c("left", "right"),
  depth = 1
)

Arguments

Details

The depth of the edit is determined by the number of edges between the vertices. To erode or dilate based on spatial distance (mm), see -cifti-dilate and -cifti-erode.

Value

x after erosion or dilation.

See Also

Other surface-related: add_surf(), boundary_mask_surf(), even_vert_samp(), is.surf(), load_surf(), mask_surf(), read_surf(), resample_surf(), rotate_surf(), surf_area(), view_surf(), write_surf_gifti()

Evenly sample vertices of mesh

Description

Get a subset of the mesh vertices that are spatially evenly-sampled, by resampling the mesh and choosing the original vertices closest (Euclidian distance) to the new vertices.

Usage

even_vert_samp(surf, n_vert)

Arguments

Value

An integer vector giving the indices of the vertices in the subset.

See Also

Other surface-related: add_surf(), boundary_mask_surf(), edit_mask_surf(), is.surf(), load_surf(), mask_surf(), read_surf(), resample_surf(), rotate_surf(), surf_area(), view_surf(), write_surf_gifti()

Interpolates between entries in the input palette to make a larger palette with COLOR_RES entries.

Description

Interpolates between entries in the input palette to make a larger palette with COLOR_RES entries.

Usage

expand_color_pal(pal, COLOR_RES = 255)

Arguments

Value

A data.frame with two columns: "color" (character: color hex codes) and "value" (numeric)

See Also

Other coloring: ROY_BIG_BL(), make_color_pal(), use_color_pal()

Expect these "xifti"s to match

Description

Raise an error if the "xifti"s do not match.

Usage

expect_equal_xifti(xii1, xii2)

Arguments

Details

cifti$intent is only compared if it exists for both files. cifti$brainstructures and cifti$misc are not compared.

Value

TRUE, invisibly

faces

Description

faces

Arguments

Fix GIFTI medial wall

Description

Replace implicit medial wall values (not indicated in ROI, but are in mwall_values) with explicit medial wall values (indicated in ROI) in a metric GIFTI file.

Usage

fix_gifti_mwall(
  metric_fname,
  fixed_metric_fname,
  ROI_fname,
  fixed_ROI_fname,
  mwall_values = c(NA, NaN)
)

Arguments

Value

NULL, invisibly

Fix a "xifti"

Description

Make adjustments to a putative "xifti" so that it is valid. Each adjustment is reported.

Usage

fix_xifti(xifti, verbose = TRUE)

Arguments

Details

Right now it: coerces the data to numeric matrices; adds the "Other" level to the subcortex labels.

Value

The fixed "xifti"

Flatten a "xifti"

Description

Concatenates the data in a "xifti" object row-wise to form a single matrix.

Usage

flatten_xifti(xifti, medial_wall = NULL, subcort_order = "alphabetical")

Arguments

Details

If all brain structures are present, and if is.null(medial_wall) and subcort_order=="alphabetical" (the default arguments), then the result will be identical to the matrix obtained with the Connectome Workbench command -cifti-export-dense-mapping.

Value

The flattened "xifti", a data matrix

Format a path

Description

Normalize and validate a path (optionally, within a certain directory).

Usage

format_path(path, dir = NULL, mode = NA)

Arguments

Value

The normalized path, or NULL if the path was NULL.

Get CIFTI file extension

Description

Get CIFTI file extension

Usage

get_cifti_extn(cifti_fname)

Arguments

Value

Character file extension of CIFTI file, e.g. "dtseries.nii", "dscalar.nii"

Extract data-related metadata from CIFTI

Description

Extract data-related metadata from CIFTI header XML (second "MatrixIndicesMap" entry)

Usage

get_data_meta_from_cifti_xml(xml, intent = 3000)

Arguments

Value

The metadata, a list

Extract intent-specific metadata from CIFTI

Description

Extract intent-specific Metadata from CIFTI header XML (first "MatrixIndicesMap" entry)

Usage

get_intn_meta_from_cifti_xml(xml, intent = 3000)

Arguments

Value

The metadata, a list

Get kwargs

Description

Get the names of the arguments of a function as a character vector.

Usage

get_kwargs(fun)

Arguments

Value

The names of the arguments of fun as a character vector

Extract misc metadata from CIFTI

Description

Extract misc metadata from CIFTI header XML ("Metadata" entry)

Usage

get_misc_meta_from_cifti_xml(xml, intent = 3000)

Arguments

Value

The metadata, a list

Get the Connectome Workbench command path

Description

Retrieves the path to the Connectome Workbench executable from a file path that may point to the executable itself, or to the Workbench folder which contains it (i.e., "path/to/workbench/bin_linux64/wb_command" or "path/to/workbench".)

Usage

get_wb_cmd_path(wb_path)

Arguments

Value

The path to the Connectome Workbench executable

Get NIFTI header (of a CIFTI)

Description

Wrapper for Connectome Workbench command -nifti-information [fname] -print-header

Usage

header_cifti(cifti_fname)

Arguments

Value

The header, as a character vector

idx

Description

idx

Arguments

Impute "xifti" data

Description

Impute locations using the values of neighboring locations.

Usage

impute_xifti(
  xifti,
  mask = NULL,
  impute_FUN = function(x) {
     mean(x, na.rm = TRUE)
 },
  ...
)

Arguments

Details

Cortex vertices will be imputed using the five or six other vertices which share a face. Subcortex voxels will be imputed using the up to six immediate neighbors.

Note that during imputation, locations in mask, as well as the medial wall for the cortex, are temporarily set to NA.

Note that handling of NA values and the mask slightly differs from the cortex and subcortex. impute_FUN like mean will behave similarly, but functions which change depending on the amount of neighbor locations with NA values may differ. impute_FUN should handle NA values accordingly. For most use cases, it will make sense to pass na.rm=TRUE to ... if impute_FUN is a summary function like mean.

Value

The input xifti with imputed data values.

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Infer resolution from "xifti" and surfaces

Description

Infer the numbers of vertices on each cortex of a "xifti" object. Also supports the result of info_cifti.

Usage

infer_resolution(xifti, surfL = NULL, surfR = NULL)

Arguments

Value

The inferred resolutions for the left and right cortex.

Get CIFTI metadata

Description

Get CIFTI metadata from the NIFTI header and XML using the Connectome Workbench command -nifti-information. The information is formatted as the meta component in a "xifti" object (see template_xifti), and includes:

1. medial wall masks for the left and right cortex

2. the subcortical labels (ordered spatially)

3. the subcortical mask

4. other NIFTI intent-specific metadata

Usage

info_cifti(cifti_fname)

infoCIfTI(cifti_fname)

infocii(cifti_fname)

Arguments

Details

Additional metadata depends on the type of CIFTI file:

"dtseries"

time_start:

Start time

time_step:

The TR

time_unit:

Unit of time

"dscalar"

names:

Name of each data column

"dlabels"

names:

( Names of each data column.)

labels:

( List of L \times 5 data.frames. Row names are the label names. Column names are Key, Red, Green, Blue, and Alpha. List entry names are the names of each data column.)

Value

The metadata component of a "xifti" for the input CIFTI file

Connectome Workbench

This function interfaces with the "-nifti-information" Workbench command.

Label Levels

xifti$meta$subcort$labels is a factor with the following levels:

1. Cortex-L

2. Cortex-R

3. Accumbens-L

4. Accumbens-R

5. Amygdala-L

6. Amygdala-R

7. Brain Stem

8. Caudate-L

9. Caudate-R

10. Cerebellum-L

11. Cerebellum-R

12. Diencephalon-L

13. Diencephalon-R

14. Hippocampus-L

15. Hippocampus-R

16. Pallidum-L

17. Pallidum-R

18. Putamen-L

19. Putamen-R

20. Thalamus-L

21. Thalamus-R

These correspond to the same structures as given by ft_read_cifti in the cifti-matlab MATLAB toolbox. Note that the first two levels (left and right cortex) are not used.

See Also

Other reading: as.xifti(), load_parc(), load_surf(), read_cifti(), read_surf(), read_xifti2()

Validate a 3d binary mask

Description

Check if object is a 3D binary mask.

Usage

is.3D_mask(x)

Arguments

Details

This is a helper function for is.xifti.

Requirements: the mask must be a boolean 3D array. TRUE should indicate voxels included in the mask, whereas FALSE should indicate voxels outside of it.

Value

Logical. Is x a valid subcortical mask?

Validate a "xifti" object

Description

Check if object is valid for a "xifti". This alias for is.xifti is offered as a convenience, and a message will warn the user. We recommend using is.xifti instead.

Usage

is.cifti(x, messages = TRUE)

is_cifti(x, messages = TRUE)

isCIfTI(x, messages = TRUE)

Arguments

Details

Requirements: it is a list with the same structure as template_xifti. The size of each data entry must be compatible with its corresponding mask (medial wall for the cortex and volumetric mask for the subcortex). Metadata should be present if and only if the corresponding data is also present. The surfaces can be present whether or not the cortex data are present.

See the "Label Levels" section for the requirements of xifti$meta$subcort$labels.

Value

Logical. Is x a valid "xifti"?

Label Levels

xifti$meta$subcort$labels is a factor with the following levels:

1. Cortex-L

2. Cortex-R

3. Accumbens-L

4. Accumbens-R

5. Amygdala-L

6. Amygdala-R

7. Brain Stem

8. Caudate-L

9. Caudate-R

10. Cerebellum-L

11. Cerebellum-R

12. Diencephalon-L

13. Diencephalon-R

14. Hippocampus-L

15. Hippocampus-R

16. Pallidum-L

17. Pallidum-R

18. Putamen-L

19. Putamen-R

20. Thalamus-L

21. Thalamus-R

These correspond to the same structures as given by ft_read_cifti in the cifti-matlab MATLAB toolbox. Note that the first two levels (left and right cortex) are not used.

See Also

Other common: read_cifti(), resample_cifti(), smooth_cifti(), view_xifti(), write_cifti()

Is this an existing file path?

Description

Simple check if something is an existing file.

Usage

is.fname(x)

Arguments

Value

Logical. Is x an existing file?

Validate a numeric matrix

Description

Check if object is a numeric matrix.

Usage

is.nummat(x)

Arguments

Details

This is a helper function for is.xifti.

Value

Logical. Is x a valid numeric matrix?

Validate a factor vector of subcortical labels

Description

Check if object is a factor vector of subcortical structures.This is a helper function for is.xifti.

Usage

is.subcort_labs(x)

Arguments

Details

Requirements: see the "Label Levels" section for the expected factor levels.

Value

Logical. Is x a factor vector of subcortical structures?

Label Levels

xifti$meta$subcort$labels is a factor with the following levels:

1. Cortex-L

2. Cortex-R

3. Accumbens-L

4. Accumbens-R

5. Amygdala-L

6. Amygdala-R

7. Brain Stem

8. Caudate-L

9. Caudate-R

10. Cerebellum-L

11. Cerebellum-R

12. Diencephalon-L

13. Diencephalon-R

14. Hippocampus-L

15. Hippocampus-R

16. Pallidum-L

17. Pallidum-R

18. Putamen-L

19. Putamen-R

20. Thalamus-L

21. Thalamus-R

These correspond to the same structures as given by ft_read_cifti in the cifti-matlab MATLAB toolbox. Note that the first two levels (left and right cortex) are not used.

Validate a "surf" object (vertices + faces)

Description

Check if object is valid for xifti$surf$cortex_left or xifti$surf$cortex_right, where xifti is a "xifti" object.

Usage

is.surf(x)

Arguments

Details

This is a helper function for is.xifti.

Requirements: the "surf" must be a list of three components: "vertices", "faces", and "hemisphere". The first two should each be a numeric matrix with three columns. The values in "vertices" represent spatial coordinates whereas the values in "faces" represent vertex indices defining the face. Thus, values in "faces" should be integers between 1 and the number of vertices. The last list entry, "hemisphere", should be "left", "right", or NULL indicating the brain hemisphere which the surface represents.

Value

Logical. Is x a valid "surf"?

See Also

Other surface-related: add_surf(), boundary_mask_surf(), edit_mask_surf(), even_vert_samp(), load_surf(), mask_surf(), read_surf(), resample_surf(), rotate_surf(), surf_area(), view_surf(), write_surf_gifti()

Validate a "xifti" object.

Description

Check if object is valid for a "xifti" object.

Usage

is.xifti(x, messages = TRUE)

is_xifti(x, messages = TRUE)

Arguments

Details

Requirements: it is a list with the same structure as template_xifti. The size of each data entry must be compatible with its corresponding mask (medial wall for the cortex and volumetric mask for the subcortex). Metadata should be present if and only if the corresponding data is also present. The surfaces can be present whether or not the cortex data are present.

See the "Label Levels" section for the requirements of xifti$meta$subcort$labels.

Value

Logical. Is x a valid "xifti" object?

Label Levels

xifti$meta$subcort$labels is a factor with the following levels:

1. Cortex-L

2. Cortex-R

3. Accumbens-L

4. Accumbens-R

5. Amygdala-L

6. Amygdala-R

7. Brain Stem

8. Caudate-L

9. Caudate-R

10. Cerebellum-L

11. Cerebellum-R

12. Diencephalon-L

13. Diencephalon-R

14. Hippocampus-L

15. Hippocampus-R

16. Pallidum-L

17. Pallidum-R

18. Putamen-L

19. Putamen-R

20. Thalamus-L

21. Thalamus-R

These correspond to the same structures as given by ft_read_cifti in the cifti-matlab MATLAB toolbox. Note that the first two levels (left and right cortex) are not used.

Validate the "data" component of a "xifti" object

Description

Check if object is valid for xifti$data, where xifti is a "xifti" object.

Usage

is.xifti_data(x)

Arguments

Details

This is a helper function for is.xifti.

Requirements: a list with entries "cortex_left", "cortex_right", and "subcort". Each must be either NULL or a numeric matrix with grayordinates along the rows and measurements along the columns. The cortical matrices should have the same number of rows (vertices), and all should have the same number of columns (measurements). At least one data entry should be present.

Value

Logical. Is x a valid "data" component?

Validate the "meta" component of a "xifti" object

Description

Check if object is valid for xifti$meta, where xifti is a "xifti" object.

Usage

is.xifti_meta(x)

Arguments

Details

This is a helper function for is.xifti.

Requirements: the structure must match that of the "meta" component of template_xifti.

Value

Logical. Is x a valid "meta" component?

labels

Description

labels

Label Levels

xifti$meta$subcort$labels is a factor with the following levels:

1. Cortex-L

2. Cortex-R

3. Accumbens-L

4. Accumbens-R

5. Amygdala-L

6. Amygdala-R

7. Brain Stem

8. Caudate-L

9. Caudate-R

10. Cerebellum-L

11. Cerebellum-R

12. Diencephalon-L

13. Diencephalon-R

14. Hippocampus-L

15. Hippocampus-R

16. Pallidum-L

17. Pallidum-R

18. Putamen-L

19. Putamen-R

20. Thalamus-L

21. Thalamus-R

These correspond to the same structures as given by ft_read_cifti in the cifti-matlab MATLAB toolbox. Note that the first two levels (left and right cortex) are not used.

Load a parcellation included in ciftiTools

Description

Load a parcellation included in ciftiTools.

Usage

load_parc(
  name = c("Schaefer_100", "Schaefer_400", "Schaefer_1000", "Yeo_7", "Yeo_17")
)

Arguments

Details

When using these parcellations, please cite the corresponding paper(s):

1. Yeo, B. T. T. et al. The organization of the human cerebral cortex estimated by intrinsic functional connectivity. J Neurophysiol 106, 1125-1165 (2011).

2. Schaefer, A. et al. Local-Global Parcellation of the Human Cerebral Cortex from Intrinsic Functional Connectivity MRI. Cereb Cortex 28, 3095-3114 (2018).

3. Kong, R. et al. Individual-Specific Areal-Level Parcellations Improve Functional Connectivity Prediction of Behavior. Cerebral Cortex (2021+) doi:10.1093/cercor/bhab101.

Note that the Schaefer parcels have been matched to networks from Kong (2021+).

Value

The parcellation as a dlabel "xifti" with one column. Each key represents one unique parcel.

See Also

Other reading: as.xifti(), info_cifti(), load_surf(), read_cifti(), read_surf(), read_xifti2()

Other parcellation-related: apply_parc(), load_sub_parc(), parc_add_subcortex(), parc_borders(), parc_vals_to_xifti()

Load subcortical parcellation

Description

Load the MNI subcortical parcellation included in ciftiTools as a "dlabel" "xifti" object.

Usage

load_sub_parc()

Details

Colors are based on https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT

Value

The subcortical parcellation

See Also

Other parcellation-related: apply_parc(), load_parc(), parc_add_subcortex(), parc_borders(), parc_vals_to_xifti()

Load a "surf" included in ciftiTools

Description

Load a "surf" object from one of the three 32k anatomical surfaces included in ciftiTools.

Usage

load_surf(
  hemisphere = c("left", "right"),
  name = c("inflated", "very inflated", "midthickness"),
  resamp_res = NULL
)

Arguments

Details

The surfaces are from the HCP and are included according to these data use terms: Data were provided [in part] by the Human Connectome Project, WU-Minn Consortium (Principal Investigators: David Van Essen and Kamil Ugurbil; 1U54MH091657) funded by the 16 NIH Institutes and Centers that support the NIH Blueprint for Neuroscience Research; and by the McDonnell Center for Systems Neuroscience at Washington University.

Value

The "surf" object

See Also

Other reading: as.xifti(), info_cifti(), load_parc(), read_cifti(), read_surf(), read_xifti2()

Other surface-related: add_surf(), boundary_mask_surf(), edit_mask_surf(), even_vert_samp(), is.surf(), mask_surf(), read_surf(), resample_surf(), rotate_surf(), surf_area(), view_surf(), write_surf_gifti()

Make a color palette.

Description

Control the mapping of values to colors with colors, color_mode, and zlim.

Usage

make_color_pal(
  colors = NULL,
  color_mode = c("sequential", "qualitative", "diverging"),
  zlim = NULL
)

Arguments

Details

There are three kinds of arguments for colors: "ROY_BIG_BL", the name of a ColorBrewer palette (see RColorBrewer::brewer.pal.info and colorbrewer2.org), the name of a viridisLite palette, or a character vector of color names.

If colors=="ROY_BIG_BL", the "ROY_BIG_BL" palette will be used. It is the same palette as the default for the Connectome Workbench application (https://github.com/Washington-University/workbench/blob/master/src/Files/PaletteFile.cxx). The midpoint will be colored black. From the midpoint toward the upper bound, colors will proceed from black to red to yellow. From the midpoint toward the lower bound, colors will proceed from black to blue to purple to green to aqua. Here is how each color mode behaves if colors=="ROY_BIG_BL":

color_mode=="sequential"

Only half of the palette will be used. If zlim is length 2, the higher value will be the maximum and the lower value will be the minimum. Set zlim[1] > zlim[2] to reverse the color scale. (Note that the second half, black –> red –> yellow, is used by default. To use the negative half specify colors=="ROY_BIG_BL_neg" instead. It will also be used automatically by xifti_read_surface when the data range is negative.) zlim can also be length 10, in which case each value corresponds to the position of an individual color in the half palette.

color_mode=="qualitative"

"ROY_BIG_BL" is not recommended for qualitative data, so a warning will be issued. Palette colors will be selected from the landmark "ROY_BIG_BL" colors, with interpolated colors added if the number of colors in the palette (18) is less than this range. zlim should be a single number: the number of unique colors to get.

color_mode=="diverging"

If zlim is length 2 or 3, the lowest number will be the lower bound and the highest number will be the upper bound. If zlim is length 3, the middle number will be the midpoint (black). The lower and upper bounds will be aqua and yellow, respectively, except if zlim is in descending order, in which case the color scale will be reversed (lowest is yellow; highest is aqua). zlim can also be length 19, in which case each value corresponds to the position of an individual color in the palette.

If colors is the name of an RColorBrewer palette (see RColorBrewer::brewer.pal.info) or viridisLite palette, the colors in that palette will be used, and the following behavior applies. If colors is a character vector of color names (hex codes or standard R color names), the following behavior applies directly:

color_mode=="sequential"

If zlim is length 2, the higher value will be the maximum and the lower value will be the minimum. Set zlim[1] > zlim[2] to reverse the color scale. zlim can also be the same length as the palette, in which case each value corresponds to the position of an individual color in the palette.

color_mode=="qualitative"

zlim should be a single number: the number of unique colors to get. Color interpolation will be used if the number of colors in the palette is less than this range. If length(zlim)==length(colors), each color will be mapped to each corresponding value.

color_mode=="diverging"

If zlim is length 2 or 3, the lowest number will be the lower bound and the highest number will be the upper bound. If zlim is length 3, the middle number will be the midpoint. Set zlim in descending order to reverse the color scale. zlim can also be the same length as the palette, in which case each value corresponds to the position of an individual color in the palette.

Value

A data.frame with two columns: "color" (character: color hex codes) and "value" (numeric)

See Also

Other coloring: ROY_BIG_BL(), expand_color_pal(), use_color_pal()

Make the cortical components of a "xifti"

Description

Coerce a path to a GIFTI file, metric or label "gifti" object, data matrix or vector to a data matrix representing cortical data (and optionally a corresponding mask). That is, entries for xifti$data$cortex_\[left/right\] and xifti$meta$cortex$medial_wall_mask$\[left/right\]. If cortex is a path to a GIFTI file or a metric "gifti", any column names or a non-empty label table will also be extracted.

Usage

make_cortex(
  cortex,
  mwall = NULL,
  idx = NULL,
  cortex_is_masked = NULL,
  rm_blank_mwall = TRUE,
  rm_bad_mwall = TRUE,
  mwall_values = NULL,
  side = NULL,
  mwall_source = NULL
)

Arguments

Value

A list with components "data", "mwall", "col_names" and "labels".

Make the subcortical components of a "xifti"

Description

Coerce subcortical data into valid entries for xifti$data$subcort and xifti$meta$subcort. The data arguments can be matrices/arrays or NIFTI file paths. If the mask is not provided, it will be inferred from the labels.

Usage

make_subcort(vol, labs, mask = NULL, idx = NULL, validate_mask = FALSE)

Arguments

Details

To read in the labels as the primary data, use the labels NIFTI for both vol and labs.

Value

A list with components "data", "labels", "mask", and "trans_mat". The first two will be vectorized and ordered spatially.

The volume can be recovered using: vol <- unvec_vol(data, mask, fill=NA) labs <- unvec_vol(labels, mask, fill=0)

Label Levels

xifti$meta$subcort$labels is a factor with the following levels:

1. Cortex-L

2. Cortex-R

3. Accumbens-L

4. Accumbens-R

5. Amygdala-L

6. Amygdala-R

7. Brain Stem

8. Caudate-L

9. Caudate-R

10. Cerebellum-L

11. Cerebellum-R

12. Diencephalon-L

13. Diencephalon-R

14. Hippocampus-L

15. Hippocampus-R

16. Pallidum-L

17. Pallidum-R

18. Putamen-L

19. Putamen-R

20. Thalamus-L

21. Thalamus-R

These correspond to the same structures as given by ft_read_cifti in the cifti-matlab MATLAB toolbox. Note that the first two levels (left and right cortex) are not used.

Make the subcortical transformation matrix

Description

Make the transformation matrix for the subcortical volume from the sform data in the header.

Usage

make_trans_mat(nii_fname)

Arguments

Value

4x4 matrix representing the transformation matrix. (This includes the last row, c(0,0,0,1)).

Assemble a "xifti" object

Description

Assembles cortical data, subcortical data, and/or surface geometry to form a "xifti" object. The inputs can be file paths, GIFTI or NIFTI files which have been read in, or data objects (vectors, matrices or arrays, depending on the argument). See as.xifti for a user-function wrapper that only works with data objects.

Usage

make_xifti(
  cortexL = NULL,
  cortexL_mwall = NULL,
  cortexR = NULL,
  cortexR_mwall = NULL,
  subcortVol = NULL,
  subcortLabs = NULL,
  subcortMask = NULL,
  mwall_values = c(NA, NaN),
  cifti_info = NULL,
  surfL = NULL,
  surfR = NULL,
  idx = NULL,
  col_names = NULL,
  HCP_32k_auto_mwall = TRUE,
  read_dir = NULL,
  validate = TRUE
)

Arguments

Details

Each data or surface component is optional. Metadata components (cortex[L/R]_mwall, subcortLabs, and subcortMask) will be ignored if its corresponding data component is not provided. If no data or surface components are provided, then the template_xifti will be returned.

If cortical data are provided without a corresponding medial wall mask, or if the provided mask is invalid or empty, then the medial wall will be inferred from data rows that are constantly a value in mwall_values. But if mwall_values is NULL, no attempt to infer the medial wall will be made and the medial wall metadata entry will be NULL.

The total number of grayordinates will be G = (V_L - mwall_L) + (V_R - mwall_R) + V_S: V_L - mwall_L left vertices, V_R - mwall_R right vertices and V_S subcortical voxels. T, the total number of measurements (columns of data), must be the same for each brainstructure.

Value

A "xifti" object; see template_xifti

Label Levels

xifti$meta$subcort$labels is a factor with the following levels:

1. Cortex-L

2. Cortex-R

3. Accumbens-L

4. Accumbens-R

5. Amygdala-L

6. Amygdala-R

7. Brain Stem

8. Caudate-L

9. Caudate-R

10. Cerebellum-L

11. Cerebellum-R

12. Diencephalon-L

13. Diencephalon-R

14. Hippocampus-L

15. Hippocampus-R

16. Pallidum-L

17. Pallidum-R

18. Putamen-L

19. Putamen-R

20. Thalamus-L

21. Thalamus-R

These correspond to the same structures as given by ft_read_cifti in the cifti-matlab MATLAB toolbox. Note that the first two levels (left and right cortex) are not used.

mask: vertices

Description

mask: vertices

Arguments

Mask surface

Description

Mask a surface mesh.

Usage

mask_surf(surf, mask)

Arguments

Details

Apply a binary mask to a "surf" object (list of vertices and corresponding faces). Vertices not in the mask are removed, and faces (triangles) with any vertices not in the mask are removed. Finally, vertex numbering for the new faces matrix is corrected.

Value

The masked "surf" object.

See Also

Other surface-related: add_surf(), boundary_mask_surf(), edit_mask_surf(), even_vert_samp(), is.surf(), load_surf(), read_surf(), resample_surf(), rotate_surf(), surf_area(), view_surf(), write_surf_gifti()

Apply Mask With Boundary To Mesh

Description

Make a boundary around a mask with two levels of decimation, and apply to a mask.

Usage

mask_with_boundary_surf(
  vertices,
  faces,
  mask,
  width1 = 4,
  k1 = 2,
  width2 = 6,
  k2 = 3
)

Arguments

Details

The boundary consists of a width1-vertex-wide middle region and a width2-vertex-wide outer region, for a total of width1 + width2 layers of vertices surrounding the input mask. In the first layer, every k1 vertex within every k1 layer (beginning with the innermost layer) is retained; the rest are discarded. In the second layer, every k2 vertex within every k2 layer (beginning with the innermost layer) is retained; the rest are discarded. It is recommended to make width1 a multiple of k1 and width2 a multiple of k2.

Default boundary: a 4-vertex wide middle region with triangles twice as long, and a 6-vertex wide outer region with triangles three times as long.

Value

A new mesh (list with components vertices and faces)

Do these character vectors match exactly?

Description

Checks if a user-defined character vector matches an expected character vector. That is, they share the same lengths and entries in the same order. For vectors of the same lengths, the result is all(a == b).

Usage

match_exactly(
  user,
  expected,
  fail_action = c("message", "warning", "stop", "nothing")
)

Arguments

Details

Attributes are ignored.

Value

Logical. Do user and expected match?

Match user inputs to expected values

Description

Match each user input to an expected/allowed value.

Usage

match_input(
  user,
  expected,
  fail_action = c("stop", "warning", "message", "nothing"),
  user_value_label = NULL
)

Arguments

Details

Raise a warning if either several user inputs match the same expected value, or at least one could not be matched to any expected value. ciftiTools uses this function to match keyword arguments for a function call. Another use is to match brainstructure labels ("left", "right", or "subcortical").

Value

The matched user inputs

Merges two kwargs

Description

Merge two kwarg lists. If a kwarg is present in both lists but with different values, an error is raised.

Usage

merge_kwargs(
  kwargsA,
  kwargsB,
  labelA = "first kwarg(s)",
  labelB = "second kwarg(s)",
  extraMsg = "[DEFAULT]"
)

Arguments

Value

A list with the union of kwargsA and kwargsB

Concatenate "xifti"s

Description

Concatenate "xifti" objects along the columns. They must have the same brainstructures and resolutions. The first "xifti"'s metadata will be retained, including its intent.

Usage

merge_xifti(..., xifti_list = NULL)

Arguments

Value

The concatenated "xifti"

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Move data locations from medial wall

Description

Move all medial wall locations into the cortical data matrices by assigning them a specific value (e.g. NA).

Usage

move_from_mwall(xifti, value = NA, name = "Medial_Wall", RGBA = c(1, 1, 1, 0))

Arguments

Value

The "xifti" with re-organized data and medial wall masks

See Also

move_to_mwall

unmask_cortex

Move data locations from subcortex mask

Description

Move subcortex mask locations into the subcortex data matrix by assigning them a specific value (e.g. NA).

Usage

move_from_submask(
  xifti,
  new_mask,
  value = NA,
  label_value = "Other",
  name = "Other",
  RGBA = c(1, 1, 1, 0)
)

Arguments

Value

The "xifti" with re-organized data and subcortex masks

See Also

move_to_submask

unmask_cortex

Move data locations to the medial wall

Description

Move cortical data locations with a specific value(s) to the medial wall mask. For example, dlabel CIFTIs often have medial wall vertices set to a specific key value, rather than a medial wall mask. This function can move those data locations from the data matrix to the medial wall mask in the metadata.

Usage

move_to_mwall(xifti, values = c(NA, NaN), drop = FALSE)

Arguments

Value

The "xifti" with re-organized data and medial wall masks

See Also

move_from_mwall

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Move data locations to the subcortex mask

Description

Move subcortex data locations with a specific value(s) to the subcortex mask.

Usage

move_to_submask(xifti, values = c(NA, NaN), drop = FALSE)

Arguments

Value

The "xifti" with re-organized data and subcortex masks

See Also

move_from_submask

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Counts the number of columns in a "xifti".

Description

Counts the number of columns in the "xifti" data. Doesn't bother to validate the input.

Usage

ncol_xifti(xifti)

Value

The number of columns in the "xifti" data.

Replace the data in a "xifti"

Description

Replace the data in a "xifti" with new data from a data matrix.

Usage

newdata_xifti(xifti, newdata, newnames = NULL, subcortex_by_bs = FALSE)

Arguments

Details

If the "xifti" has V grayordinates and T measurements\, newdata should be a V \times Q matrix. If Q is not equal to T, then any column names or label tables will be removed. (A "dlabel" will be converted to a "dscalar".)

Value

The new "xifti"

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Counts the number of rows (vertices + voxels) in a "xifti".

Description

Counts the number of data locations in the "xifti" data. Doesn't bother to validate the input.

Usage

nrow_xifti(xifti)

Arguments

Value

The number of rows in the "xifti" data.

original_fnames: for remapping

Description

original_fnames: for remapping

Arguments

original_fnames: for resampling

Description

original_fnames: for resampling

Arguments

Pad a 3D Array

Description

Pad a 3D array by a certain amount in each direction, along each dimension. This effectively undoes a crop.

Usage

pad_vol(x, padding, fill = NA)

uncrop_vol(x, padding, fill = NA)

Arguments

Value

The padded array

Add subcortex to cortical parcellation

Description

Add the subcortex, with each brain structure as a separate parcel, to a "dlabel" cortical parcellation.

Usage

parc_add_subcortex(parc, parc_sub = "MNI")

Arguments

Value

The new parcellation with added subcortical data and labels.

See Also

Other parcellation-related: apply_parc(), load_parc(), load_sub_parc(), parc_borders(), parc_vals_to_xifti()

Parcellation borders

Description

Identify vertices which lie on the border of different parcels.

Usage

parc_borders(parc, surf = NULL, hemisphere = c("left", "right"))

Arguments

Value

Logical vector the same length as parc indicating if the vertex lies on a border.

See Also

Other parcellation-related: apply_parc(), load_parc(), load_sub_parc(), parc_add_subcortex(), parc_vals_to_xifti()

Make parcellation mean matrix

Description

Create a matrix that compute the average value for each parcel.

Usage

parc_mean_mat(parc)

Arguments

Details

From a single-column "dlabel" "xifti" object, make a K \times V matrix where row k is a vector corresponding to the kth Key value, with 1/k_i at locations with that key value, and 0 elsewhere. k_i is the total number of locations inside Key k. So, the sum of each row will be 1, and each column will only have exactly one non-zero value (because each location only has one Key value) except medial wall locations will have all zeroes.

Multiplying the result of parc_mean_mat with a V \times T matrix of timeseries data, e.g. from as.matrix(dlabel_xii), will yield the average value for each Key.

Value

The parcellation matrix

Convert parcellation values to "xifti"

Description

From a parcellation and a corresponding value matrix, make a "xifti" object that has the value vector of each parcel across its locations.

Usage

parc_vals_to_xifti(parc, vals)

Arguments

Value

A "xifti" object

See Also

Other parcellation-related: apply_parc(), load_parc(), load_sub_parc(), parc_add_subcortex(), parc_borders()

S3 method: plot surface

Description

Visualize a single surface

Usage

## S3 method for class 'surf'
plot(x, ...)

Arguments

S3 method: use view_xifti to plot a "xifti" object

Description

S3 method: use view_xifti to plot a "xifti" object

Usage

## S3 method for class 'xifti'
plot(x, ...)

Arguments

Order Vertices on Circular Manifold

Description

Order vertices on circular manifold by radians (after 2D CMDS projection).

Usage

radial_order_surf(vertices)

Arguments

Value

Index ordering of vertices

Read a CIFTI file

Description

Read in a CIFTI file as a "xifti" object.

Usage

read_cifti(
  cifti_fname = NULL,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = "existing",
  idx = NULL,
  resamp_res = NULL,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)

readCIfTI(
  cifti_fname = NULL,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = "existing",
  idx = NULL,
  resamp_res = NULL,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)

readcii(
  cifti_fname = NULL,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = "existing",
  idx = NULL,
  resamp_res = NULL,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)

read_xifti(
  cifti_fname = NULL,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = "existing",
  idx = NULL,
  resamp_res = NULL,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  flat = FALSE,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)

Arguments

Details

First, metadata is obtained with info_cifti. Then, if no resampling is requested, the -cifti-convert -to-gifti-ext Workbench Command is used to "flatten" the data and save it as a metric or label GIFTI file, which is read in and separated by brainstructure according to the metadata (read_cifti_convert). Otherwise, if sampling is requested, then the CIFTI is separated into its GIFTI and NIFTI components, resampled, and then re-assembled (read_cifti_separate). The former is much faster for large CIFTI files, so the latter is only used when necessary for resampling.

If cifti_fname is not provided, then only the surfaces are read in.

Value

If !flat, a "xifti" object. Otherwise, a T \times G matrix (T measurements, G grayordinates).

Connectome Workbench

This function interfaces with the "-cifti-convert" Workbench command if resampling is not needed, and the "-cifti-separate" Workbench command if resampling is needed.

Label Levels

xifti$meta$subcort$labels is a factor with the following levels:

1. Cortex-L

2. Cortex-R

3. Accumbens-L

4. Accumbens-R

5. Amygdala-L

6. Amygdala-R

7. Brain Stem

8. Caudate-L

9. Caudate-R

10. Cerebellum-L

11. Cerebellum-R

12. Diencephalon-L

13. Diencephalon-R

14. Hippocampus-L

15. Hippocampus-R

16. Pallidum-L

17. Pallidum-R

18. Putamen-L

19. Putamen-R

20. Thalamus-L

21. Thalamus-R

These correspond to the same structures as given by ft_read_cifti in the cifti-matlab MATLAB toolbox. Note that the first two levels (left and right cortex) are not used.

See Also

Other common: is.cifti(), resample_cifti(), smooth_cifti(), view_xifti(), write_cifti()

Other reading: as.xifti(), info_cifti(), load_parc(), load_surf(), read_surf(), read_xifti2()

Read a CIFTI file quickly

Description

Read a CIFTI file by exporting it as a single GIFTI using -cifti-convert -to-gifti-ext (read_cifti_flat), and obtaining the brainordinate mapping using -cifti-export-dense-mapping (info_cifti).

Usage

read_cifti_convert(
  cifti_fname,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = "existing",
  idx = NULL,
  mwall_values = c(NA, NaN),
  verbose = FALSE,
  ...
)

Arguments

Value

A "xifti" object. See is.xifti.

Read only the data matrix in a CIFTI file

Description

Reads the CIFTI data matrix by converting it to a GIFTI using the -cifti-convert -to-gifti-ext Connectome Workbench command. The result will be a T \times G matrix (T measurements, G non-empty grayordinates). All brainstructures in the CIFTI will be obtained, with no indication for which brainstructure each brainordinate corresponds to. Medial wall vertices and voxels outside the subcortical mask will not be included. No spatial information is included. This is the fastest way to read in CIFTI data.

Usage

read_cifti_flat(
  cifti_fname,
  keep = FALSE,
  gifti_fname = NULL,
  idx = NULL,
  write_dir = NULL
)

Arguments

Value

A T \times G matrix, where T is the number of measurements and G is the number of grayordinates in the CIFTI file.

Read a CIFTI file with optional resampling

Description

Read a CIFTI file by writing each component into a GIFTI and NIFTI file (separate_cifti), optionally resampling the GIFTIs, (resample_gifti), and then reading each separated component into R (make_xifti). Surfaces can also be provided; they will be resampled along with the CIFTI for viewing.

Usage

read_cifti_separate(
  cifti_fname,
  surfL_fname = NULL,
  surfR_fname = NULL,
  brainstructures = "existing",
  idx = NULL,
  resamp_res = NULL,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE
)

Arguments

Details

The subcortical component (NIFTI) is not resampled.

Value

A "xifti" object. See is.xifti.

read_dir: separated files

Description

read_dir: separated files

Arguments

Get a "surf" object

Description

Coerce a file path to a surface GIFTI, a "gifti" object, a list with entries "pointset" and "triangle", or a "surf" to a "surf".

Usage

read_surf(surf, expected_hemisphere = NULL, resamp_res = NULL)

make_surf(surf, expected_hemisphere = NULL, resamp_res = NULL)

Arguments

Value

The "surf": a list with components "vertices" (3D spatial locations), "faces" (defined by three vertices), and "hemisphere" ("left", "right", or NULL if unknown).

See Also

Other reading: as.xifti(), info_cifti(), load_parc(), load_surf(), read_cifti(), read_xifti2()

Other surface-related: add_surf(), boundary_mask_surf(), edit_mask_surf(), even_vert_samp(), is.surf(), load_surf(), mask_surf(), resample_surf(), rotate_surf(), surf_area(), view_surf(), write_surf_gifti()

Read in GIFTI files as a "xifti" object

Description

Read in GIFTI metric or label files as a "xifti" object. May also include surface geometry GIFTI files and perform resampling.

Usage

read_xifti2(
  cortexL = NULL,
  cortexL_mwall = NULL,
  cortexR = NULL,
  cortexR_mwall = NULL,
  mwall_values = c(NA, NaN),
  surfL = NULL,
  surfR = NULL,
  resamp_res = NULL,
  col_names = NULL,
  HCP_32k_auto_mwall = TRUE,
  read_dir = NULL,
  validate = TRUE
)

Arguments

Value

The "xifti" object containing all the data in the input giftis.

See Also

Other reading: as.xifti(), info_cifti(), load_parc(), load_surf(), read_cifti(), read_surf()

Remap CIFTI data

Description

Remap CIFTI data between two different spaces, such as between FreeSurfer fsaverage group data and fs_LR group data.

Usage

remap_cifti(
  x,
  cifti_target_fname = NULL,
  remap_method = c("adaptive", "barycentric"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  areaL_target_fname = NULL,
  areaR_target_fname = NULL,
  sphereL_original_fname = NULL,
  sphereR_original_fname = NULL,
  sphereL_target_fname = NULL,
  sphereR_target_fname = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE
)

remapCIfTI(
  x,
  cifti_target_fname = NULL,
  remap_method = c("adaptive", "barycentric"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  areaL_target_fname = NULL,
  areaR_target_fname = NULL,
  sphereL_original_fname = NULL,
  sphereR_original_fname = NULL,
  sphereL_target_fname = NULL,
  sphereR_target_fname = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE
)

remapcii(
  x,
  cifti_target_fname = NULL,
  remap_method = c("adaptive", "barycentric"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  areaL_target_fname = NULL,
  areaR_target_fname = NULL,
  sphereL_original_fname = NULL,
  sphereR_original_fname = NULL,
  sphereL_target_fname = NULL,
  sphereR_target_fname = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE
)

remap_xifti(
  x,
  cifti_target_fname = NULL,
  remap_method = c("adaptive", "barycentric"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  areaL_target_fname = NULL,
  areaR_target_fname = NULL,
  sphereL_original_fname = NULL,
  sphereR_original_fname = NULL,
  sphereL_target_fname = NULL,
  sphereR_target_fname = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE
)

Arguments

Details

Can accept a "xifti" object as well as a path to a CIFTI-file. If the input "xifti" object has surface geometry, it will be removed.

This function is in active development: its arguments and behavior may change greatly in future versions of the package.

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

remap_cifti wrapper

Description

Wrapper for remap_cifti. Calls resample_cifti_components using the original file names listed in the original_fnames argument and the target file names listed in the remap_fnames argument.

Usage

remap_cifti_wrapper(
  original_fnames,
  remap_fnames = NULL,
  remap_method = c("adaptive", "barycentric"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  areaL_target_fname = NULL,
  areaR_target_fname = NULL,
  sphereL_original_fname = NULL,
  sphereR_original_fname = NULL,
  sphereL_target_fname = NULL,
  sphereR_target_fname = NULL,
  read_dir = NULL,
  write_dir = NULL
)

Arguments

Value

The return value of the resample_cifti_components call

Remap GIFTI metric or label data

Description

Remap GIFTI metric or label data between two different spaces, such as between FreeSurfer fsaverage group data and fs_LR group data. This function is a wrapper to resample_gifti.

Usage

remap_gifti(
  original_fname,
  target_fname,
  hemisphere = c("left", "right"),
  remap_method = c("adaptive", "barycentric"),
  area_original_fname,
  area_target_fname,
  ROIcortex_original_fname,
  ROIcortex_target_fname,
  sphere_original_fname,
  sphere_target_fname
)

Arguments

Value

The remapped GIFTI file name, invisibly

Connectome Workbench

This function interfaces with the "-metric-resample", "-label-resample", and/or "-surface-resample" Workbench commands, depending on the input.

See Also

Other gifting: resample_gifti(), smooth_gifti()

Remove a component from a "xifti"

Description

Remove a brain structure, surface, or subcortical structure from a "xifti".

Usage

remove_xifti(xifti, remove = NULL, remove_sub = NULL)

Arguments

Value

The new "xifti" with the requested component(s) removed

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

resamp_method

Description

resamp_method

Arguments

resamp_res: optional

Description

resamp_res: optional

Arguments

resamp_res: required

Description

resamp_res: required

Arguments

Resample CIFTI data

Description

Performs spatial resampling of CIFTI data on the cortical surface by separating it into GIFTI and NIFTI files, resampling the GIFTIs, and then putting them together. (The subcortex is not resampled.)

Usage

resample_cifti(
  x = NULL,
  cifti_target_fname = NULL,
  surfL_original_fname = NULL,
  surfR_original_fname = NULL,
  surfL_target_fname = NULL,
  surfR_target_fname = NULL,
  resamp_res,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE
)

resampleCIfTI(
  x = NULL,
  cifti_target_fname = NULL,
  surfL_original_fname = NULL,
  surfR_original_fname = NULL,
  surfL_target_fname = NULL,
  surfR_target_fname = NULL,
  resamp_res,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE
)

resamplecii(
  x = NULL,
  cifti_target_fname = NULL,
  surfL_original_fname = NULL,
  surfR_original_fname = NULL,
  surfL_target_fname = NULL,
  surfR_target_fname = NULL,
  resamp_res,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE
)

resample_xifti(
  x = NULL,
  cifti_target_fname = NULL,
  surfL_original_fname = NULL,
  surfR_original_fname = NULL,
  surfL_target_fname = NULL,
  surfR_target_fname = NULL,
  resamp_res,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  write_dir = NULL,
  mwall_values = c(NA, NaN),
  verbose = TRUE
)

Arguments

Details

Can accept a "xifti" object as well as a path to a CIFTI-file.

If surface data is included, it will be resampled with the barycentric method even if resamp_method=="adaptive" because the barycentric method is recommended for surface geometry data.

Value

A named character vector of written files: "cifti" and potentially "surfL" (if surfL_original_fname was provided) and/or "surfR" (if surfR_original_fname was provided).

Connectome Workbench

This function interfaces with the "-metric-resample", "-label-resample", and/or "-surface-resample" Workbench commands, depending on the input.

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Other common: is.cifti(), read_cifti(), smooth_cifti(), view_xifti(), write_cifti()

Resample a series of GIFTIs related to a CIFTI file

Description

Performs spatial resampling of various CIFTI file components on the cortical surface. (The subcortical data is not resampled here.) GIFTI surface geometry files can additionally be included: see surfL_original_fname and surfR_original_fname.

Usage

resample_cifti_components(
  original_res = NULL,
  resamp_res = NULL,
  resamp_method = NULL,
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  areaL_target_fname = NULL,
  areaR_target_fname = NULL,
  cortexL_original_fname = NULL,
  cortexR_original_fname = NULL,
  cortexL_target_fname = NULL,
  cortexR_target_fname = NULL,
  ROIcortexL_original_fname = NULL,
  ROIcortexR_original_fname = NULL,
  ROIcortexL_target_fname = NULL,
  ROIcortexR_target_fname = NULL,
  sphereL_original_fname = NULL,
  sphereR_original_fname = NULL,
  sphereL_target_fname = NULL,
  sphereR_target_fname = NULL,
  surfL_original_fname = NULL,
  surfR_original_fname = NULL,
  surfL_target_fname = NULL,
  surfR_target_fname = NULL,
  read_dir = NULL,
  write_dir = NULL
)

Arguments

Details

Step 1: Generate spheres in the original and target resolutions Step 2: Use -metric-resample to resample surface/cortex files Step 3: Use -surface-resample to resample gifti files

Value

A named character vector of file paths to each resampled file

Get resampled file name default

Description

Get the default file name for a resampled file.

Usage

resample_cifti_default_fname(original_fname, resamp_res)

Arguments

Value

The default file name

Resample a CIFTI from a template

Description

Resample a CIFTI from a template, ensuring the new CIFTI's resolution matches that of the template.

Usage

resample_cifti_from_template(original_fname, template_fname, target_fname)

Arguments

Value

The target_fname, invisibly

Connectome Workbench

This function interfaces with the "-cifti-resample" Workbench command.

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), scale_xifti(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

resample_cifti wrapper

Description

Calls resample_cifti_components using the original file names listed in the original_fnames argument and the target file names listed in the resamp_fnames argument.

Usage

resample_cifti_wrapper(
  original_fnames,
  resamp_fnames = NULL,
  original_res,
  resamp_res,
  resamp_method = c("barycentric", "adaptive"),
  areaL_original_fname = NULL,
  areaR_original_fname = NULL,
  surfL_original_fname = NULL,
  surfR_original_fname = NULL,
  surfL_target_fname = NULL,
  surfR_target_fname = NULL,
  read_dir = NULL,
  write_dir = NULL
)

Arguments

Details

Currently used by read_cifti and resample_cifti.

Value

The return value of the resample_cifti_components call

Resample a GIFTI file (with its ROI)

Description

Perform spatial resampling of GIFTI data on the cortical surface (metric and label), or of GIFTI surface geometry data itself.

Usage

resample_gifti(
  original_fname,
  target_fname,
  hemisphere = c("left", "right"),
  file_type = NULL,
  original_res = NULL,
  resamp_res = NULL,
  resamp_method = c("barycentric", "adaptive"),
  area_original_fname = NULL,
  area_target_fname = NULL,
  ROIcortex_original_fname = NULL,
  ROIcortex_target_fname = NULL,
  sphere_original_fname = NULL,
  sphere_target_fname = NULL,
  read_dir = NULL,
  write_dir = NULL
)

resampleGIfTI(
  original_fname,
  target_fname,
  hemisphere,
  file_type = NULL,
  original_res = NULL,
  resamp_res,
  ROIcortex_original_fname = NULL,
  ROIcortex_target_fname = NULL,
  read_dir = NULL,
  write_dir = NULL
)

resamplegii(
  original_fname,
  target_fname,
  hemisphere,
  file_type = NULL,
  original_res = NULL,
  resamp_res,
  ROIcortex_original_fname = NULL,
  ROIcortex_target_fname = NULL,
  read_dir = NULL,
  write_dir = NULL
)

Arguments

Value

The resampled GIFTI file name, invisibly

Connectome Workbench

This function interfaces with the "-metric-resample", "-label-resample", and/or "-surface-resample" Workbench commands, depending on the input.

See Also

Other gifting: remap_gifti(), smooth_gifti()

Resample a "surf" object

Description

Resample a "surf" object by writing it to a GIFTI, using the Connectome Workbench to resample it, and then reading the new file. The barycentric resampling method, which is recommended for anatomical surfaces, will be used.

Usage

resample_surf(surf, resamp_res, hemisphere = c("left", "right"))

Arguments

Value

The new "surf"

Connectome Workbench

This function interfaces with the "-surface-resample" Workbench command.

See Also

Other surface-related: add_surf(), boundary_mask_surf(), edit_mask_surf(), even_vert_samp(), is.surf(), load_surf(), mask_surf(), read_surf(), rotate_surf(), surf_area(), view_surf(), write_surf_gifti()

Navigating and Embedding the Interactive Plots

Description

Navigating and Embedding the Interactive Plots

Navigating and Embedding the Interactive Plots

To navigate the interactive Open GL window and html widget, left click and drag the cursor to rotate the meshes. Use the scroll wheel or right click and drag to zoom. Press the scroll wheel and drag to change the field-of-view. For Open GL windows, execute snapshot to save the current window as a .png file, close3d to close the window, and view3d to programmatically control the perspective.

To embed an interactive plot in an R Markdown document, first execute rgl::setupKnitr() to prepare the document for embedding the widget. Then execute the plot command as you normally would to create a widget (i.e. without specifying fname, and by requesting more than one idx or by setting widget to TRUE). When the R Markdown document is knitted, the interactive widget should be displayed below the chunk in which the plot command was executed. See the vignette for an example.

Embedding the Static Plots

Description

Embedding the Static Plots

Embedding the Static Plots

To embed a static plot in an R Markdown document, first execute rgl::setupKnitr() to prepare the document for embedding the snapshot of the Open GL window. Then execute the plot command as you normally would to create an Open GL window (i.e. without specifying fname, and by requesting only one idx). In the options for the chunk in which the plot command is executed, set rgl=TRUE, format="png". You can also control the image dimensions here e.g. fig.height=3.8, fig.width=5. When the R Markdown document is knitted, the static plots should be displayed below the chunk in which the plot command was executed. See the vignette for an example.

Rotate a "surf" object

Description

Rotate a "surf". Can be used to adjust the mesh orientation prior to view_xifti_surface.

Usage

rotate_surf(surf, r1 = 0, r2 = 0, r3 = 0, units = c("radians", "degrees"))

Arguments

Value

The rotated "surf"

See Also

Other surface-related: add_surf(), boundary_mask_surf(), edit_mask_surf(), even_vert_samp(), is.surf(), load_surf(), mask_surf(), read_surf(), resample_surf(), surf_area(), view_surf(), write_surf_gifti()

Wrapper for Connectome Workbench Commands

Description

Runs a Connectome Workbench command that has already been formatted.

Usage

run_wb_cmd(cmd, intern = TRUE, ignore.stdout = NULL, ignore.stderr = NULL)

Arguments

Value

If intern==TRUE, the printed output of the command. If intern==FALSE, a logical indicating if the command finished successfully.

Scale CIFTI

Description

Scale CIFTI data. Similar to scale.

Usage

scale_xifti(xifti, center = TRUE, scale = TRUE)

Arguments

Value

The input "xifti" with scaled columns.

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), select_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Select columns of a "xifti"

Description

Select column indices to keep in a "xifti". Can also be used to reorder the columns.

Usage

select_xifti(xifti, idx, add_meta = "select")

Arguments

Value

The "xifti" with only the selected columns.

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), set_names_xifti(), smooth_cifti(), transform_xifti()

Separate a CIFTI file

Description

Separate a CIFTI file into GIFTI files for the cortical data and NIFTI files for the subcortical data and labels. ROIs can also be written to indicate the medial wall mask (cortex) and volume mask (subcortex). This uses the Connectome Workbench command -cifti-separate.

Usage

separate_cifti(
  cifti_fname,
  brainstructures = "existing",
  cortexL_fname = NULL,
  cortexR_fname = NULL,
  subcortVol_fname = NULL,
  subcortLabs_fname = NULL,
  ROI_brainstructures = "all",
  ROIcortexL_fname = NULL,
  ROIcortexR_fname = NULL,
  ROIsubcortVol_fname = NULL,
  write_dir = NULL
)

separateCIfTI(
  cifti_fname,
  brainstructures = "existing",
  cortexL_fname = NULL,
  cortexR_fname = NULL,
  subcortVol_fname = NULL,
  subcortLabs_fname = NULL,
  ROI_brainstructures = "all",
  ROIcortexL_fname = NULL,
  ROIcortexR_fname = NULL,
  ROIsubcortVol_fname = NULL,
  write_dir = NULL
)

separatecii(
  cifti_fname,
  brainstructures = "existing",
  cortexL_fname = NULL,
  cortexR_fname = NULL,
  subcortVol_fname = NULL,
  subcortLabs_fname = NULL,
  ROI_brainstructures = "all",
  ROIcortexL_fname = NULL,
  ROIcortexR_fname = NULL,
  ROIsubcortVol_fname = NULL,
  write_dir = NULL
)

Arguments

Details

Time unit, start, and step (dtseries files) will not be written to the GIFTI/NIFTIs. Column names (dscalar files) will not be written to the GIFTIs, as well as label names and colors (dlabel files). (Haven't checked the NIFTIs yet.)

ROI/medial wall behavior: If there are 32k vertices in the left cortex with 3k representing the medial wall, then both cortexL_fname and ROIcortexL_fname will have 32k entries, 3k of which having a value of 0 indicating the medial wall. The non-medial wall entries will have the data values in cortexL_fname and a value of 1 in ROIcortexL_fname. Thus, exporting ROIcortexL_fname is vital if the data values include 0, because 0-valued non-medial wall vertices and medial wall vertices cannot be distinguished from one another within cortexL_fname alone.

Value

A named character vector with the file paths to the written NIFTI and GIFTI files

Connectome Workbench

This function interfaces with the "-cifti-separate" Workbench command.

See Also

Other writing: write_cifti(), write_metric_gifti(), write_subcort_nifti(), write_surf_gifti(), write_xifti2()

Separate CIFTI: file names

Description

File paths for writing GIFTI and NIFTI files from a CIFTI or "xifti"

Usage

separate_cifti_files(
  bs_present,
  intent = 3006,
  brainstructures = "existing",
  cortexL_fname = NULL,
  cortexR_fname = NULL,
  subcortVol_fname = NULL,
  subcortLabs_fname = NULL,
  ROI_brainstructures = "all",
  ROIcortexL_fname = NULL,
  ROIcortexR_fname = NULL,
  ROIsubcortVol_fname = NULL,
  write_dir = NULL
)

Arguments

Details

If write_dir is NULL, only components with provided file names will be written. If write_dir is not NULL, files for all existing brain components will be written to that directory.

Value

List of three: do, ROI_do, and sep_fnames

separate_cifti wrapper

Description

Calls separate_cifti using the file names listed in the argument sep_fnames.

Usage

separate_cifti_wrapper(
  cifti_fname,
  brainstructures = "existing",
  ROI_brainstructures = "all",
  sep_fnames = NULL,
  write_dir = NULL
)

Arguments

Details

Currently used by read_cifti and resample_cifti.

Value

The return value of the separate_cifti call

Set "xifti" column names

Description

Change the column names of a "dscalar" or "dlabel" "xifti" object.

Usage

set_names_xifti(xifti, names)

Arguments

Value

xifti with the new column names.

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), smooth_cifti(), transform_xifti()

Smooth CIFTI data

Description

Spatially smooth the metric data of a CIFTI file or "xifti" object.

Usage

smooth_cifti(
  x,
  cifti_target_fname = NULL,
  surf_FWHM = 5,
  vol_FWHM = 3,
  surfL_fname = NULL,
  surfR_fname = NULL,
  cerebellum_fname = NULL,
  subcortical_zeroes_as_NA = FALSE,
  cortical_zeroes_as_NA = FALSE,
  subcortical_merged = FALSE
)

smoothCIfTI(
  x,
  cifti_target_fname = NULL,
  surf_FWHM = 5,
  vol_FWHM = 5,
  surfL_fname = NULL,
  surfR_fname = NULL,
  cerebellum_fname = NULL,
  subcortical_zeroes_as_NA = FALSE,
  cortical_zeroes_as_NA = FALSE,
  subcortical_merged = FALSE
)

smoothcii(
  x,
  cifti_target_fname = NULL,
  surf_FWHM = 5,
  vol_FWHM = 5,
  surfL_fname = NULL,
  surfR_fname = NULL,
  cerebellum_fname = NULL,
  subcortical_zeroes_as_NA = FALSE,
  cortical_zeroes_as_NA = FALSE,
  subcortical_merged = FALSE
)

smooth_xifti(
  x,
  cifti_target_fname = NULL,
  surf_FWHM = 5,
  vol_FWHM = 5,
  surfL_fname = NULL,
  surfR_fname = NULL,
  cerebellum_fname = NULL,
  subcortical_zeroes_as_NA = FALSE,
  cortical_zeroes_as_NA = FALSE,
  subcortical_merged = FALSE
)

Arguments

Details

If the CIFTI is a ".dlabel" file (intent 3007), then it will be converted to a ".dscalar" file because the values will no longer be integer indices. Unless the label values were ordinal, this is probably not desired so a warning will be printed.

Can accept a "xifti" object as well as a path to a CIFTI-file.

Surfaces are required for each hemisphere in the CIFTI. If they are not provided, the default inflated surfaces will be used.

Conversion for sigma: \sigma \times 2 \times \sqrt(2 \times \log(2)) = FWHM

Value

The cifti_target_fname, invisibly, if x was a CIFTI file name. A "xifti" object if x was a "xifti" object.

Connectome Workbench

This function interfaces with the "-cifti-smoothing" Workbench command.

See Also

Other manipulating xifti: add_surf(), apply_parc(), apply_xifti(), combine_xifti(), convert_xifti(), impute_xifti(), merge_xifti(), move_to_mwall(), move_to_submask(), newdata_xifti(), remap_cifti(), remove_xifti(), resample_cifti(), resample_cifti_from_template(), scale_xifti(), select_xifti(), set_names_xifti(), transform_xifti()

Other common: is.cifti(), read_cifti(), resample_cifti(), view_xifti(), write_cifti()

Smooth a metric GIFTI file

Description

Smooths metric GIFTI data along the cortical surface. The results are written to a new GIFTI file.

Usage

smooth_gifti(
  original_fname,
  target_fname,
  surf_fname = NULL,
  surf_FWHM = 5,
  hemisphere = c("left", "right"),
  ROI_fname = NULL,
  zeroes_as_NA = FALSE
)

smoothGIfTI(
  original_fname,
  target_fname,
  surf_fname,
  surf_FWHM = 5,
  zeroes_as_NA = FALSE
)

smoothgii(
  original_fname,
  target_fname,
  surf_fname,
  surf_FWHM = 5,
  zeroes_as_NA = FALSE
)

Arguments

Value

The smoothed GIFTI file name, invisibly

Connectome Workbench

This function interfaces with the "-metric-smoothing" Workbench command.

See Also

Other gifting: remap_gifti(), resample_gifti()

Substructure table

Description

Table of labels for cortex hemispheres (left and right) and subcortical substructures. The same labels used by the HCP data are here, plus "Other". Names from the CIFTI format ("CIFTI_STRUCTURE_*") and the names used by ciftiTools are given.

Usage

substructure_table()

Details

The names used by ciftiTools are based on those in FT_READ_CIFTI from the FieldTrip MATLAB toolbox.

Value

A data.frame with each substructure along the rows. The first column gives the CIFTI format name and the second column gives the ciftiTools name.

Summarize a "surf" object

Description

Summary method for class "surf"

Usage

## S3 method for class 'surf'
summary(object, ...)

## S3 method for class 'summary.surf'
print(x, ...)

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

Arguments

Summarize a "xifti" object

Description

Summary method for class "xifti"

Usage

## S3 method for class 'xifti'
summary(object, ...)

## S3 method for class 'summary.xifti'
print(x, ...)

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

Arguments

The NIFTI intents supported by ciftiTools

Description

Table of CIFTI file types (NIFTI intents) supported by ciftiTools.

Usage

supported_intents()

Details

See https://www.nitrc.org/forum/attachment.php?attachid=334&group_id=454&forum_id=1955 for information about the different NIFTI intents.

Value

A data.frame with each supported file type along the rows, and column names "extension", "intent_code", "value", and "intent_name"

surfL

Description

surfL

Arguments

surfL_fname

Description

surfL_fname

Arguments

surfL_original_fname

Description

surfL_original_fname

Arguments

surfL_target_fname

Description

surfL_target_fname

Arguments

surfR

Description

surfR

Arguments

surfR_fname

Description

surfR_fname

Arguments

surfR_original_fname

Description

surfR_original_fname

Arguments

surfR_target_fname

Description

surfR_target_fname

Arguments

Surface area calculation

Description

Calculate surface area of a "surf" object by vertex or face. Surface area calculation by vertex matches the Workbench command "-surface-vertex-areas".

Usage

surf_area(surf, by = c("vertex", "face"))

Arguments

Value

Vector of surface areas by vertex or face, in the same order as how the vertices or faces are listed in surf. The units are the square of the units of surf$vertices.

See Also

Other surface-related: add_surf(), boundary_mask_surf(), edit_mask_surf(), even_vert_samp(), is.surf(), load_surf(), mask_surf(), read_surf(), resample_surf(), rotate_surf(), view_surf(), write_surf_gifti()

Surface plot

Description

Surface plot

Arguments

Format a path for system

Description

Right now, it uses shQuote

Usage

sys_path(R_path)

Arguments

Value