"xifti"Visualize "xifti" cortical data using an interactive Open GL window
or htmlwidget made with rgl. The rmarkdown package is
required for the htmlwidget functionality.
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,
cex.title = NULL,
text_color = "black",
bg = NULL,
borders = FALSE,
alpha = 1,
edge_color = NULL,
vertex_color = NULL,
vertex_size = 0,
material = NULL,
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,
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,
together = NULL,
together_ncol = together_ncol,
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,
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,
together = NULL,
together_ncol = together_ncol,
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,
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
)
A "xifti" object.
(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.
(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.
(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.
(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.
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.
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.
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.
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.
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.
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.
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()).
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.
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.
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: 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.
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: 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.
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".
Number of columns in color legend. If
NULL (default), use 10 entries per row. Only applies if the color
legend is used (qualitative data).
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).
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.
The number of digits for the colorbar legend ticks.
If NULL (default), let format decide.
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.
Color for text in title and colorbar legend. Default:
"black".
Background color. NULL will use "white". Does not affect
the color legend or color bar if printed separately: those will always have
white backgrounds.
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.
Transparency value for mesh coloring, between 0 and 1. Default:
1.0 (no transparency).
Outline each edge in this color. Default: NULL (do
not outline the edges).
Draw each vertex in this color. Default:
"black". Vertices are only drawn if vertex_size > 0
Draw each vertex with this size. Default: 0
(do not draw the vertices).
A list of materials from rgl.material
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.
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.
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.
Adjust the sizes of the brain meshes. Default: NULL (will
be set to 0.6 or 160\
widget.)
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.
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.
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.
Other commonly-used functions:
is.cifti(),
read_cifti(),
resample_cifti(),
smooth_cifti(),
view_xifti_volume(),
write_cifti()