view_xifti_volume: View subcortical data in a '"xifti"'

In neuroconductor/ciftiTools: Tools for Reading, Writing, Viewing and Manipulating CIFTI Files

Description

Visualize the subcortical data in a "xifti" using a series of 2D slices (based on overlay) or an interactive widget (based on papaya).

Usage

view_xifti_volume(
  xifti,
  structural_img = "MNI",
  color_mode = "auto",
  zlim = NULL,
  colors = NULL,
  structural_img_colors = gray(0:255/280),
  title = NULL,
  idx = 1,
  plane = c("axial", "sagittal", "coronal"),
  n_slices = 9,
  slices = NULL,
  widget = FALSE,
  fname = FALSE,
  fname_suffix = c("names", "idx"),
  fname_sub = FALSE,
  legend_fname = "[fname]_legend",
  legend_ncol = NULL,
  legend_alllevels = FALSE,
  legend_embed = NULL,
  digits = NULL,
  cex.title = NULL,
  ypos.title = 0,
  xpos.title = 0,
  text_color = "white",
  bg = NULL,
  width = NULL,
  height = NULL,
  ...
)

view_cifti_volume(
  xifti,
  structural_img = "MNI",
  color_mode = "auto",
  zlim = NULL,
  colors = NULL,
  structural_img_colors = gray(0:255/280),
  title = NULL,
  idx = 1,
  plane = c("axial", "sagittal", "coronal"),
  n_slices = 9,
  slices = NULL,
  widget = FALSE,
  fname = FALSE,
  fname_suffix = c("names", "idx"),
  legend_fname = "[fname]_legend",
  legend_ncol = NULL,
  legend_alllevels = FALSE,
  legend_embed = NULL,
  digits = NULL,
  cex.title = NULL,
  text_color = "white",
  bg = NULL,
  width = NULL,
  height = NULL,
  ...
)

viewCIfTI_volume(
  xifti,
  structural_img = "MNI",
  color_mode = "auto",
  zlim = NULL,
  colors = NULL,
  structural_img_colors = gray(0:255/280),
  title = NULL,
  idx = 1,
  plane = c("axial", "sagittal", "coronal"),
  n_slices = 9,
  slices = NULL,
  widget = FALSE,
  fname = FALSE,
  fname_suffix = c("names", "idx"),
  legend_fname = "[fname]_legend",
  legend_ncol = NULL,
  legend_alllevels = FALSE,
  legend_embed = NULL,
  digits = NULL,
  cex.title = NULL,
  text_color = "white",
  bg = NULL,
  width = NULL,
  height = NULL,
  ...
)

viewcii_volume(
  xifti,
  structural_img = "MNI",
  color_mode = "auto",
  zlim = NULL,
  colors = NULL,
  structural_img_colors = gray(0:255/280),
  title = NULL,
  idx = 1,
  plane = c("axial", "sagittal", "coronal"),
  n_slices = 9,
  slices = NULL,
  widget = FALSE,
  fname = FALSE,
  fname_suffix = c("names", "idx"),
  legend_fname = "[fname]_legend",
  legend_ncol = NULL,
  legend_alllevels = FALSE,
  legend_embed = NULL,
  digits = NULL,
  cex.title = NULL,
  text_color = "white",
  bg = NULL,
  width = NULL,
  height = NULL,
  ...
)

Arguments

xifti	A "xifti" object.
structural_img	The structural MRI image on which to overlay the subcortical plot. Can be a file name, "MNI" (default) to use the MNI T1-weighted template included in ciftiTools, or NULL to use a blank image.
color_mode	(Optional) "sequential", "qualitative", "diverging", or "auto" (default). Auto mode will use the qualitative color mode if the "xifti" object represents a .dlabel CIFTI (intent 3007). Otherwise, it will use the diverging mode if the data contains both positive and negative values, and the sequential mode if the data contains >90\ make_color_pal for more details.
zlim	(Optional) Controls the mapping of values to each color in colors. If the length is longer than one, using -Inf will set the value to the data minimum, and Inf will set the value to the data maximum. See make_color_pal description for more details.
colors	(Optional) "ROY_BIG_BL", vector of colors to use, the name of a ColorBrewer palette (see RColorBrewer::brewer.pal.info and colorbrewer2.org), or the name of a viridisLite palette. If NULL (default), will use the positive half of "ROY_BIG_BL" (sequential), "Set2" (qualitative), or the full "ROY_BIG_BL" (diverging). An exception to these defaults is if the "xifti" object represents a .dlabel CIFTI (intent 3007), in which case the colors in the label table will be used. See make_color_pal for more details.
structural_img_colors	Colors to use for the background image. These will be assigned in order from lowest to highest value with equal spacing between the colors. (color_mode, zlim and colors have no bearing on the background image colors.) This argument is used as the col.x argument to oro.nifti::overlay directly. Default: gray(0:255/280). To use the oro.nifti::overlay default instead set this argument to gray(0:64/64).
title	Optional title(s) for the plot(s). It will be printed at the top. Default: NULL will not use any title if length(idx)==1. Otherwise, it will use the time index (".dtseries") or name (.dscalar or .dlabel) of each data column. To use a custom title(s), use a length 1 character vector (same title for each plot) or length length(idx) character vector (different title for each plot). Set to NULL or an empty character to omit the title. If the title is non-empty but does not appear, try lowering cex.title.
idx	The time/column index of the data to display. NULL (default) will display the first column. If widget, only one index at a time may be displayed. If !widget and the length of idx is greater than one, a new plot will be created for each idx. These can be toggled between using the arrows at the top of the display window if working interactively in RStudio; or, these will be written to separate files if !isFALSE(fname).
plane	The plane to display for the slices: "axial" (default), "sagittal" or "coronal". Ignored if widget.
n_slices	The number of slices to display. Default: 9. The slices will be selected in a way that visualizes as much of the subcortex as possible. Ignored if widget.
slices	Which slices to display. If provided, this argument will override n_slices. Should be a numeric vector with integer values between one and the number of slices in plane. Ignored if widget.
widget	Create an interactive widget using papayar? Otherwise display static 2D slices. Default: FALSE. Note that the widget can only display one idx at a time.
fname, fname_suffix	Save the plot(s) (and color legend if applicable)? If isFALSE(fname) (default), no files will be written. If widget, these arguments are ignored. If neither of the cases above apply, a png image will be written for each idx. If isTRUE(fname) the files will be named by the data column names (underscores will replace spaces). Or, set fname to a length 1 character vector to name files by this suffix followed by the fname_suffix: either the data column names ("names") or the index value ("idx"). Or, set fname to a character vector with the same length as idx to name the files exactly.
fname_sub	Add "_sub" to the end of the names of the files being saved? Default: FALSE. This is useful if cortical plots of the same data are being saved too.
legend_fname	Save the color legend? Since the legend is the same for each idx only one legend is written even if length(idx)>1. This argument can be NULL to not save the legend, an exact file path, or a length-one character vector with "[fname]" in it, which will name the legend based on fname\[1\]. For example, if fname\[1\] is "plots/my_cifti.png" and legend_fname is "\[fname\]_legend" (default), then the legend plot will be saved to "plots/my_cifti_legend.png".
legend_ncol	Number of columns in color legend. If NULL (default), use 10 entries per row. Only applies if the color legend is used (qualitative data).
legend_alllevels	Show all label levels in the color legend? If FALSE (default), just show the levels present in the data being viewed. Only applies if the color legend is used (qualitative data).
legend_embed	Should the colorbar be embedded in the plot? It will be positioned at the bottom. Default: TRUE. If FALSE, print/save it separately instead. Only applies if the color bar is used (sequential or diverging data). The color legend (qualitative data) cannot be embedded at the moment.
digits	The number of digits for the colorbar legend ticks. If NULL (default), let format decide.
cex.title	Font size multiplier for the title. NULL (default) will use 1.2 for titles less than 20 characters long, and smaller sizes for increasingly longer titles. If saving a PNG and PDF file, the default will also scale with width relative to the default value of width.
ypos.title, xpos.title	The positioning of the title can be finicky, especially when using an R Markdown document interactively in which case it appears too high in the plot. Use these arguments to nudge the title up or down (ypos.title) or left or right (xpos.title).
text_color	Color for text in title and colorbar legend. Default: "white".
bg	Background color. NULL will use "black". Does not affect the color legend or color bar if printed separately: those will always have white backgrounds.
width, height	The dimensions of the plot, in pixels. Only affects saved images (if !isFALSE(fname)). If NULL, file dimensions will be 400 x 600 pixels for PNGs and 4 x 6 in. for PDFs. Currently, there is no way to control the dimensions of the plot if working interactively in RStudio or creating a knitted R Markdown document. The default appears to be a wide aspect ratio.
...	Additional arguments to pass to papayar::papaya or oro.nifti::overlay. Note that for oro.nifti::overlay the following additional arguments should not be provided since they are pre-determined inside this function or by the arguments listed above: x, y, plane, col.y, col.x, zlim.y, oma, plot.type, bg.

Details

Note that color_mode, zlim, and colors only affect the color scale of the data values whereas structural_img_colors only affects the color scale of the background image.

Currently, the color-related arguments only affect the 2D slice view. The color limits and palette must be edited using the widget controls once it's rendered.

See Also

Other commonly-used functions: is.cifti(), read_cifti(), resample_cifti(), smooth_cifti(), view_xifti_surface(), write_cifti()

neuroconductor/ciftiTools documentation built on Dec. 22, 2021, 1:09 a.m.