Visualization

Cortex plots in ciftiTools are made possible by the rgl package. To prepare the R Markdown document for knitting we need to do the following:

library(rgl)

## Warning: package 'rgl' was built under R version 4.4.1

rgl::setupKnitr()

# Sometimes the first OpenGL window does not render properly.
rgl::open3d(); rgl::close3d()

## glX 
##   1

# These are also required.
library(manipulateWidget)
library(ggpubr)

## Loading required package: ggplot2

Now we can use view_xifti_surface(xii) to display the cortical data on the surface mesh. This function has several primary arguments:

• color_mode specifies the nature of the data values: "sequential", "qualitative" and "diverging". If it is not provided, a default mode that makes sense for the data will be used.
• colors specifies the color palette to use. If it is not provided, a default palette that makes sense for the color_mode is used.
• idx controls which column(s) to display.
• widget and fname control the output type. If fname is not provided, an interactive plot is created: by default, an OpenGL window if the length of idx is one, and an embedded HTML widget if the length of idx is greater than one. widget can be used to override this default. On the other hand, if fname is provided, static image files (png) for each idx are created, unless fname ends in .html in which case an interactive html file will be saved. Lastly, both OpenGL windows and HTML widgets can be embedded in R Markdown documents for knitting; refer to the source code of this vignette to see how this works.
• surfL and surfR specify the surface geometry to plot the data on. If not provided, the surfaces in the "xifti" object is used. But if those are also unavailable, the “inflated” surfaces included in ciftiTools are used.

Let’s plot our "xifti" object. Note that interactively, a color legend which displays the label names will also be printed.

# Normally `cex.title` doesn't need to be set, as it defaults to a good choice.
#   But when knitting static images this way, the default becomes a bit too big
#   based on how knitting works.
view_xifti_surface(xii, idx=1, title='Schaefer 100', cex.title=1.2)

Schaefer 100 parcellation

Manipulation

add_surf adds surface geometry to the "xifti" object.

xii <- add_surf(xii, "midthickness", "midthickness")
xii

## ====CIFTI METADATA===================
## Intent:           3007 (dlabel)
## - names           "parcels"
## Measurements:     1 column
## 
## ====BRAIN STRUCTURES=================
## - left cortex     32492 data vertices
##                   left surface geometry is present
## 
## - right cortex    32492 data vertices
##                   right surface geometry is present

remove_xifti removes a brain structure.

xii <- remove_xifti(xii, c("cortex_right", "surf_right"))
xii

## ====CIFTI METADATA===================
## Intent:           3007 (dlabel)
## - names           "parcels"
## Measurements:     1 column
## 
## ====BRAIN STRUCTURES=================
## - left cortex     32492 data vertices
##                   left surface geometry is present

transform_xifti applies a function to the data values. Let’s isolate and view the frontal pole cortex. Note the midthickness surface that was added will be used now, instead of the default inflated surface.

label_to_viz <- "17networks_LH_DefaultB_FPole_1"
key_idx <- which(rownames(xii$meta$cifti$labels$parcels)==label_to_viz)
key <- xii$meta$cifti$labels$parcels$Key[key_idx]
xii <- transform_xifti(xii, function(v){ifelse(v==key, v, 0)})
view_xifti_surface(xii)

Plotting the FPole parcel

Citing ciftiTools

A citation for the package itself can be printed with:

citation("ciftiTools")

## To cite {ciftiTools} in publications use:
## 
##   Pham DD, Muschelli J, Mejia AF (2021). "ciftiTools: A package for
##   reading, writing, visualizing and manipulating CIFTI files in R."
##   _NeuroImage_, *250*. doi:10.1016/j.neuroimage.2022.118877
##   <https://doi.org/10.1016/j.neuroimage.2022.118877>.
## 
## A BibTeX entry for LaTeX users is
## 
##   @Article{,
##     title = {{ciftiTools}: A package for reading, writing, visualizing and manipulating {CIFTI} files in {R}},
##     author = {Damon D Pham and John Muschelli and Amanda F Mejia},
##     year = {2021},
##     journal = {NeuroImage},
##     volume = {250},
##     doi = {10.1016/j.neuroimage.2022.118877},
##   }

Refer to the README for citation information for the surfaces, parcellations, and other data included in ciftiTools, as well as the Connectome Workbench. Also check the DESCRIPTION file to get a list of R packages used, including rgl and papayar. Lastly, check out the full vignette on GitHub.