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

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

View subcortical data in a "xifti"

Description

Visualize the subcortical data in a "xifti" using a series of 2D slices (based on overlay) or an interactive widget (based on papayar::papaya). Note: papayar has been removed from CRAN so the widget is not available. If papayar returns to CRAN the widget will be made available again.

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 = NULL,
  plane = c("axial", "sagittal", "coronal"),
  convention = c("neurological", "radiological"),
  n_slices = 9,
  slices = NULL,
  together = NULL,
  together_ncol = NULL,
  together_title = 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,
  scientific = NA,
  cex.title = NULL,
  ypos.title = 0,
  xpos.title = 0,
  orientation_labels = TRUE,
  crop = TRUE,
  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 = NULL,
  plane = c("axial", "sagittal", "coronal"),
  convention = c("neurological", "radiological"),
  n_slices = 9,
  slices = NULL,
  together = NULL,
  together_ncol = NULL,
  together_title = 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,
  scientific = NA,
  cex.title = NULL,
  ypos.title = 0,
  xpos.title = 0,
  orientation_labels = TRUE,
  crop = TRUE,
  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 = NULL,
  plane = c("axial", "sagittal", "coronal"),
  convention = c("neurological", "radiological"),
  n_slices = 9,
  slices = NULL,
  together = NULL,
  together_ncol = NULL,
  together_title = 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,
  scientific = NA,
  cex.title = NULL,
  ypos.title = 0,
  xpos.title = 0,
  orientation_labels = TRUE,
  crop = TRUE,
  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 = NULL,
  plane = c("axial", "sagittal", "coronal"),
  convention = c("neurological", "radiological"),
  n_slices = 9,
  slices = NULL,
  together = NULL,
  together_ncol = NULL,
  together_title = 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,
  scientific = NA,
  cex.title = NULL,
  ypos.title = 0,
  xpos.title = 0,
  orientation_labels = TRUE,
  crop = TRUE,
  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), the name of a viridisLite palette, or a data.frame with columns "color" and "value" (will override zlim). 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.
convention	"neurological" (default) or "radiological". Neurological convention will display the left side of the brain on the left side of axial and coronal images, and in the first few slices of a series of sagittal images. Radiological convention will display the right side of the brain on the left side of axial and coronal images, and in the first few slices of a series of sagittal images.
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.
together	Only applies if saving image files (!isFALSE(fname)). Use this argument to create and save a composite image which combines multiple plots. NULL (default) will not combine any plots. Otherwise, this argument should be a character vector with one or more of the following entries: "leg" to combine the color legend with each "xifti" data plot. Overrides/ignores legend_embed. "idx" to place all the plots for the different "idx" in a grid. If the data is not qualitative, a shared color bar will be added to the bottom of the composite. If the data is qualitative, a shared color legend will be added to the bottom only if "leg" is in together. For greater control see view_comp or grid::arrangeGrob.
together_ncol	If "idx" %in% together, this determines the number of columns to use in the array of subplots for different indices. By default, the number of columns and rows will be determined such that they are about equal.
together_title	If a composite image is made based on together, use this argument to add a grand title to the composite image. Should be a length-one character vector or NULL (default) to not add a grand title.
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. Note: papayar has been removed from CRAN so the widget is not available. If papayar returns to CRAN the widget will be made available again.
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.
scientific	Use scientific notation? If NA (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).
orientation_labels	Show orientation labels at the top left and top right of the plot? These will indicate the directions along the left-right axis for each slice image. Default: TRUE. Ignored if widget. The vertical positioning is controlled by ypos.title, and the font size is controlled by cex.title.
crop	Crop the slice subplots to the subcortical structures, instead of showing the full anatomical image? Default: TRUE. Ignored if widget.
text_color	Color for text in title and colorbar legend. Default: "white". If "white", will use black instead for the color
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.

Arguments concerning anatomical orientation assume that the subcortical data is stored in the following way: first dimension is normal to the sagittal plane, going left to right; second dimension is normal to the coronal plane, going from the front of the head (anterior) to the back (posterior); third dimension is normal to the axial plane, going from the top of the head (superior) to the neck (inferior).

For non-interactive plots, if n_slices > 1 and convention="neurological", axial slices are ordered from the neck (inferior) to the top of the head (superior), sagittal slices are ordered left to right, and coronal slices are ordered back (posterior) to front (anterior). If convention="radiological", sagittal slices are instead ordered right to left.

Value

If a png or pdf file(s) were written, the names of the files for each index (and color legend if applicable) will be returned. Otherwise, NULL is invisibly returned.

See Also

Other visualizing: view_comp(), view_surf(), view_xifti(), view_xifti_surface()

ciftiTools documentation built on Oct. 4, 2024, 1:12 a.m.