convert_to_dlabel: Convert the intent of a CIFTI file or `"xifti"` object

Description

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

Usage

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")
)
convert_xifti(
  x,
  to = c("dscalar", "dtseries", "dlabel"),
  cifti_target_fname = NULL,
  ...
)

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.

Arguments

x

The CIFTI file name or "xifti" object to convert.

cifti_target_fname

File name for the converted CIFTI. Only used if x is a CIFTI file name. If NULL (default), will use the same name as x but with the extension updated.

levels_old, levels, labels

(Optional) levels_old is a vector of the original data values. They should all be unique. They may not all occur in the "xifti" data, but every datapoint in the "xifti" must occur in levels_old. If levels_old is not provided it will be set to the vector of all unique values in the data, in ascending order.

If levels is not provided, the original values will be re-mapped to integers from $0$ to $N-1$ (the "Keys" of a "dlabel" CIFTI), with $N$ being the length of levels_old. Otherwise, levels can be a vector the same length as levels_old specifying the corresponding new integers to use (rather than $0$ to $N-1$). If x is already "dlabel", then by setting levels_old to the current label table values and levels to the desired new values, the data can be re-leveled (see examples in function documentation). Note that duplicates in levels_old are allowed, to map multiple existing levels to the same new level.

New label names can be set with labels. If provided, it must be a character vector with the same length as levels. If there are duplicates in levels, the first label for a given level will be used. If labels is not provided, the new label names will be set to levels if it was provided, and levels_old if it was not.

Note: NA and NaN values are handled a bit differently. Data locations that are NA or NaN will remain unchanged. NA and NaN should not be included in levels_old or levels.

nsig

Take this many significant digits for the data values. If Inf (default), do not round.

colors

(Optional) "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 colors. Default: "Set2".

add_white

Append white to the beginning of the colors? Default: TRUE.

return_conversion_table

Return the conversion table along with the converted "xifti"? Default: FALSE. It will give the original values, the values_new (i.e. the "Keys"), and the new label names.

names

The column names. If NULL (default), will be set to "Column 1", "Column 2", ... .

time_start, time_step, time_unit

(Optional) metadata for the new dtseries

to

The desired intent: "dscalar" (default), "dtseries", or "dlabel"

...

Only used if x is a "xifti" object. Additional options specific to the target type and intent, e.g. for convert_to_dlabel.

Functions

convert_to_dlabel(): Give the ".dlabel" intent (code 3007/ConnDenseLabel) to an input "xifti". Will use the same label table for each data column. Can also be used to re-assign values in the label table, or to change label names.
convert_to_dscalar(): Give the ".dscalar" intent (code 3006/ConnDenseScalar) to an input CIFTI file or "xifti" object. Can also be used to set the names for each column with names.
convert_to_dtseries(): Give the ".dtseries" intent (code 3002/ConnDenseSeries) to an input "xifti" object. Can also be used to set the time metadata.

Examples

Run this code

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