"xifti"Visualize the subcortical data in a "xifti" using a series of 2D
slices (based on overlay) or an interactive widget
(based on papayar::papaya). Note: papayar has been removed
from CRAN so the widget is not available. If papayar returns to CRAN
the widget will be made available again.
view_xifti_volume(
xifti,
structural_img = "MNI",
color_mode = "auto",
zlim = NULL,
colors = NULL,
structural_img_colors = gray(0:255/280),
title = NULL,
idx = NULL,
plane = c("axial", "sagittal", "coronal"),
convention = c("neurological", "radiological"),
n_slices = 9,
slices = NULL,
together = NULL,
together_ncol = NULL,
together_title = 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,
orientation_labels = FALSE,
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 = NULL,
plane = c("axial", "sagittal", "coronal"),
n_slices = 9,
slices = NULL,
together = NULL,
together_ncol = NULL,
together_title = 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,
...
)
viewCIfTI_volume(
xifti,
structural_img = "MNI",
color_mode = "auto",
zlim = NULL,
colors = NULL,
structural_img_colors = gray(0:255/280),
title = NULL,
idx = NULL,
plane = c("axial", "sagittal", "coronal"),
n_slices = 9,
slices = NULL,
together = NULL,
together_ncol = NULL,
together_title = 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,
...
)
viewcii_volume(
xifti,
structural_img = "MNI",
color_mode = "auto",
zlim = NULL,
colors = NULL,
structural_img_colors = gray(0:255/280),
title = NULL,
idx = NULL,
plane = c("axial", "sagittal", "coronal"),
n_slices = 9,
slices = NULL,
together = NULL,
together_ncol = NULL,
together_title = 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,
...
)
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), 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.
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.
"neurological" (default) or "radiological".
Neurological convention will display the left side of the brain on the left
side of axial and coronal images, and in the first few slices of a series of
sagittal images. Radiological convention will display the right side of the
brain on the left side of axial and coronal images, and in the first few
slices of a series of sagittal images.
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.
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.
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.
Note: papayar has been removed
from CRAN so the widget is not available. If papayar returns to CRAN
the widget will be made available again.
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).
Show orientation labels at the top left and top
right of the plot? These will indicate the directions along the left-right
axis for each slice image. Default: FALSE. Ignored if widget.
The vertical positioning is controlled by ypos.title, and the font
size is controlled by cex.title.
Color for text in title and colorbar legend. Default:
"white". If "white", will use black instead for the color
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.
If a png or pdf file(s) were written, the names of the files for
each index (and color legend if applicable) will be returned. Otherwise,
NULL is invisibly returned.
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.
Arguments concerning anatomical orientation assume that the subcortical data is stored in the following way: first dimension is normal to the sagittal plane, going left to right; second dimension is normal to the coronal plane, going from the front of the head (anterior) to the back (posterior); third dimension is normal to the axial plane, going from the top of the head (superior) to the neck (inferior).
For non-interactive plots, if n_slices > 1 and convention="neurological",
axial slices are ordered from the neck (inferior) to the top of the head
(superior), sagittal slices are ordered left to right, and coronal slices
are ordered back (posterior) to front (anterior). If
convention="radiological", sagittal slices are instead ordered right
to left.
Other commonly-used functions:
is.cifti(),
read_cifti(),
resample_cifti(),
smooth_cifti(),
view_xifti_surface(),
write_cifti()