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

view_xifti_surface {ciftiTools}

R Documentation

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.

View cortical surface data in a "xifti"