"xifti"Visualize the subcortical data in a "xifti" using a series of 2D
slices (based on overlay) or an interactive widget
(based on papaya).
view_xifti_volume(
xifti,
structural_img = "MNI",
color_mode = "auto",
zlim = NULL,
colors = NULL,
structural_img_colors = gray(0:255/280),
title = NULL,
idx = 1,
plane = c("axial", "sagittal", "coronal"),
n_slices = 9,
slices = 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,
cex.title = NULL,
ypos.title = 0,
xpos.title = 0,
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 = 1,
plane = c("axial", "sagittal", "coronal"),
n_slices = 9,
slices = NULL,
widget = FALSE,
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 = "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 = 1,
plane = c("axial", "sagittal", "coronal"),
n_slices = 9,
slices = NULL,
widget = FALSE,
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 = "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 = 1,
plane = c("axial", "sagittal", "coronal"),
n_slices = 9,
slices = NULL,
widget = FALSE,
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 = "white",
bg = NULL,
width = NULL,
height = NULL,
...
)
A "xifti" object.
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.
(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), or the name of a viridisLite palette. 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.
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).
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.
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).
The plane to display for the slices:
"axial" (default), "sagittal" or "coronal".
Ignored if widget.
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.
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.
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.
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.
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.
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 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.
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 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.
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).
Color for text in title and colorbar legend. Default:
"white".
Background color. NULL will use "black". Does not affect
the color legend or color bar if printed separately: those will always have
white backgrounds.
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.
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.
Other commonly-used functions:
is.cifti(),
read_cifti(),
resample_cifti(),
smooth_cifti(),
view_xifti_surface(),
write_cifti()