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

view_xifti_volume {ciftiTools}

R Documentation

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.