view_xifti_surface: 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,
  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,
  cex.title = NULL,
  text_color = "black",
  bg = NULL,
  borders = FALSE,
  alpha = 1,
  edge_color = NULL,
  vertex_color = NULL,
  vertex_size = 0,
  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,
  view = c("both", "lateral", "medial"),
  widget = NULL,
  title = NULL,
  slider_title = "Index",
  fname = FALSE,
  fname_suffix = c("names", "idx"),
  legend_ncol = NULL,
  legend_embed = NULL,
  digits = NULL,
  cex.title = NULL,
  text_color = "black",
  bg = NULL,
  borders = FALSE,
  alpha = 1,
  edge_color = NULL,
  vertex_color = NULL,
  vertex_size = 0,
  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,
  view = c("both", "lateral", "medial"),
  widget = NULL,
  title = NULL,
  slider_title = "Index",
  fname = FALSE,
  fname_suffix = c("names", "idx"),
  legend_ncol = NULL,
  legend_embed = NULL,
  digits = NULL,
  cex.title = NULL,
  text_color = "black",
  bg = NULL,
  borders = FALSE,
  alpha = 1,
  edge_color = NULL,
  vertex_color = NULL,
  vertex_size = 0,
  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,
  view = c("both", "lateral", "medial"),
  widget = NULL,
  title = NULL,
  slider_title = "Index",
  fname = FALSE,
  fname_suffix = c("names", "idx"),
  legend_ncol = NULL,
  legend_embed = NULL,
  digits = NULL,
  cex.title = NULL,
  text_color = "black",
  bg = NULL,
  borders = FALSE,
  alpha = 1,
  edge_color = NULL,
  vertex_color = NULL,
  vertex_size = 0,
  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), or the name of a viridisLite palette. Defaults are "ROY_BIG_BL" (sequential), "Set2" (qualitative), and "ROY_BIG_BL" (diverging). An exception to these defaults is if the "xifti" object represents a .dlabel CIFTI (intent 3007), then the qualitative 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.

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.

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). 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"). Set this to a character vector with the same length as idx to name the files exactly.

fname_suffix

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.

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). 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 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".

Background color. NULL will not color the background (white).

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).

width

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. (These arguments do not affect the size of the legend, which cannot be controlled.)

height

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 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, rgl.close to close the window, and rgl.viewpoint 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.