view_xifti_surface: View cortical surface data in a '"xifti"'

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

View cortical surface data in a "xifti"

Description

Visualize "xifti" cortical data using an interactive Open GL window or htmlwidget made with rgl. The rmarkdown package is required for the htmlwidget functionality.

Usage

view_xifti_surface(
  xifti = NULL,
  surfL = NULL,
  surfR = NULL,
  color_mode = "auto",
  zlim = NULL,
  colors = NULL,
  idx = NULL,
  hemisphere = NULL,
  together = NULL,
  together_ncol = NULL,
  together_title = NULL,
  view = c("both", "lateral", "medial"),
  widget = NULL,
  title = NULL,
  slider_title = "Index",
  fname = FALSE,
  fname_suffix = c("names", "idx"),
  legend_fname = "[fname]_legend",
  legend_ncol = NULL,
  legend_alllevels = FALSE,
  legend_embed = NULL,
  digits = NULL,
  scientific = NA,
  cex.title = NULL,
  text_color = "black",
  bg = NULL,
  NA_color = "white",
  borders = FALSE,
  alpha = 1,
  edge_color = NULL,
  vertex_color = NULL,
  vertex_size = 0,
  material = NULL,
  shadows = 1,
  width = NULL,
  height = NULL,
  zoom = NULL
)

view_cifti_surface(
  xifti = NULL,
  surfL = NULL,
  surfR = NULL,
  color_mode = "auto",
  zlim = NULL,
  colors = NULL,
  idx = NULL,
  hemisphere = NULL,
  together = NULL,
  together_ncol = NULL,
  together_title = NULL,
  view = c("both", "lateral", "medial"),
  widget = NULL,
  title = NULL,
  slider_title = "Index",
  fname = FALSE,
  fname_suffix = c("names", "idx"),
  legend_fname = "[fname]_legend",
  legend_ncol = NULL,
  legend_alllevels = FALSE,
  legend_embed = NULL,
  digits = NULL,
  scientific = NA,
  cex.title = NULL,
  text_color = "black",
  bg = NULL,
  NA_color = "white",
  borders = FALSE,
  alpha = 1,
  edge_color = NULL,
  vertex_color = NULL,
  vertex_size = 0,
  material = NULL,
  shadows = 1,
  width = NULL,
  height = NULL,
  zoom = NULL
)

viewCIfTI_surface(
  xifti = NULL,
  surfL = NULL,
  surfR = NULL,
  color_mode = "auto",
  zlim = NULL,
  colors = NULL,
  idx = NULL,
  hemisphere = NULL,
  together = NULL,
  together_ncol = NULL,
  together_title = NULL,
  view = c("both", "lateral", "medial"),
  widget = NULL,
  title = NULL,
  slider_title = "Index",
  fname = FALSE,
  fname_suffix = c("names", "idx"),
  legend_fname = "[fname]_legend",
  legend_ncol = NULL,
  legend_alllevels = FALSE,
  legend_embed = NULL,
  digits = NULL,
  scientific = NA,
  cex.title = NULL,
  text_color = "black",
  bg = NULL,
  NA_color = "white",
  borders = FALSE,
  alpha = 1,
  edge_color = NULL,
  vertex_color = NULL,
  vertex_size = 0,
  material = NULL,
  shadows = 1,
  width = NULL,
  height = NULL,
  zoom = NULL
)

viewcii_surface(
  xifti = NULL,
  surfL = NULL,
  surfR = NULL,
  color_mode = "auto",
  zlim = NULL,
  colors = NULL,
  idx = NULL,
  hemisphere = NULL,
  together = NULL,
  together_ncol = NULL,
  together_title = NULL,
  view = c("both", "lateral", "medial"),
  widget = NULL,
  title = NULL,
  slider_title = "Index",
  fname = FALSE,
  fname_suffix = c("names", "idx"),
  legend_fname = "[fname]_legend",
  legend_ncol = NULL,
  legend_alllevels = FALSE,
  legend_embed = NULL,
  digits = NULL,
  scientific = NA,
  cex.title = NULL,
  text_color = "black",
  bg = NULL,
  NA_color = "white",
  borders = FALSE,
  alpha = 1,
  edge_color = NULL,
  vertex_color = NULL,
  vertex_size = 0,
  material = NULL,
  shadows = 1,
  width = NULL,
  height = NULL,
  zoom = NULL
)

Arguments

xifti	A "xifti" object.
surfL, surfR	(Optional) The brain surface model to use. Each can be a "surf" object, any valid argument to read_surf , or one of "very inflated", "inflated", or "midthickness". If provided, it will override xifti$surf$cortex_left or xifti$surf$cortex_right if it exists. Leave as NULL (default) to use xifti$surf$cortex_left or xifti$surf$cortex_right if it exists, or the default inflated surfaces if it does not exist.
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.
idx	The time/column index of the data to display. NULL (default) will display the first column. If its length is greater than one, and isFALSE(fname), a widget must be used since a single OpenGL window cannot show multiple indexes. A slider will be added to the widget to control what time/column is being displayed.
hemisphere	Which brain cortex to display: "both" (default), "left", or "right". Each will be plotted in a separate panel column. If a brain cortex is requested but no surface is available, a default inflated surface will be used. This argument can also be NULL (default). In this case, the default inflated surface included with ciftiTools will be used for each cortex with data (i.e. if xifti$data$cortex_left and/or xifti$data$cortex_right exist). Surfaces without data will be colored white.
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.
view	Which view to display: "lateral", "medial", or "both". If NULL (default), both views will be shown. Each view will be plotted in a separate panel row.
widget	Display the plot in an htmlwidget? Should be logical or NULL (default), in which case a widget will be used only if needed (length(idx)>1 & isFALSE(fname), fname is a file path to an .html file, or if rgl.useNULL()).
title	Optional title(s) for the plot(s). It will be printed at the top in a separate subplot with 1/4 the height of the brain cortex subplots. 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.
slider_title	Text at bottom of plot that will be added if a slider is used, to provide a title for it. Default: "Index". If NULL or an empty character, no title will be added.
fname	Save the plot(s) (and color legend if applicable)? If isFALSE(fname) (default), no files will be written. If fname is a length-1 character vector ending in ".html", an html with an interactive widget will be written. 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. Or, set fname to a character vector with the same length as idx to name the files exactly.
fname_suffix	Either the data column names ("names") or the index value ("idx").
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 in the bottom-left corner, in a separate subplot with 1/4 the height of the brain cortex subplots. Default: TRUE. If FALSE, print/save it separately instead. Only applies if the color bar is used (sequential or diverging data) or if "leg" %in% together. Otherwise 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 2 for titles less than 20 characters long, and smaller sizes for increasingly longer titles.
text_color	Color for text in title and colorbar legend. Default: "black".
bg	Background color. NULL will use "white". Does not affect the color legend or color bar if printed separately: those will always have white backgrounds.
NA_color	The color for the medial wall and NA values. Default: "white". Also used to color the entire surface for view_surf.
borders	Only applicable if color_mode is "qualitative". Border vertices will be identified (those that share a face with at least one vertex of a different value) and colored over. If this argument is TRUE borders will be colored in black; provide the name of a different color to use that instead. If FALSE or NULL (default), do not draw borders.
alpha	Transparency value for mesh coloring, between 0 and 1. Default: 1.0 (no transparency).
edge_color	Outline each edge in this color. Default: NULL (do not outline the edges).
vertex_color	Draw each vertex in this color. Default: "black". Vertices are only drawn if vertex_size > 0
vertex_size	Draw each vertex with this size. Default: 0 (do not draw the vertices).
material	A list of materials from material3d to use. For example, list(lit=FALSE, smooth=FALSE) will use exact colors from the color scale, rather than adding geometric shading and interpolating vertex colors. If NULL, use defaults.
shadows	Number from 0 (maximum added lighting) to 1 (no added lighting) to control the darkness and extent of shadowing on the 3D surface. Default: 1. Shadows help render the shape of the surface, but can be distracting if interpretation of the data depends on small differences in brightness along the color scale.
width, height	The dimensions of the RGL window, in pixels. If both are NULL (default), these dimensions depend on type of output (Open GL window or widget) and subplots (hemisphere, view, title, and slider_title) and are chosen to be the largest plot within a 1500 x 700 area (Open GL window) or 600 x 700 area (widget) that maintains a brain hemisphere subplot dimensions ratio of 10 x 7. Specifying only one will set the other to maintain this aspect ratio. Both can be specified to set the dimensions exactly, but note that the dimensions cannot be larger than the screen resolution. (These arguments do not affect the size of the legend, which cannot be controlled.) The plot will be taller than height to accommodate a title or color bar. If multiple idx are being composited with together, these arguments refer to a single idx within the composited plot, and not the composited plot itself.
zoom	Adjust the sizes of the brain meshes. Default: NULL (will be set to 0.6 or 160\ widget.)

Value

If a png or html file(s) were written, the names of the files for each index (and color legend if applicable) will be returned. Otherwise, the widget itself is returned if a widget was used, and the rgl object IDs are returned if an Open GL window was used. The rgl object IDs are useful for further programmatic manipulation of the Open GL window.

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

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.

See Also

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

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