ciftiTools Mini Demo

ciftiTools is an R package for working with CIFTI-2 format brain imaging data. Used in conjunction with GIFTI surface geometry files, CIFTI files enable surface-based analysis of gray matter data, which has several advantages over traditional volumetric/voxel-based analysis. Because of this, the CIFTI-2 format is used by recent neuroimaging studies including the Human Connectome Project (HCP). ciftiTools supports reading, writing, visualizing, resampling, and other operations for CIFTI files with the ".dscalar.nii", ".dtseries.nii", and ".dlabel.nii" intents. Several of these operations are made possible by the Connectome Workbench.

Several key operations in ciftiTools, including reading and writing CIFTI files, are made possible by the Connectome Workbench. Since the Workbench must be locally installed, this vignette made for CRAN can only demonstrate a few functions. Please refer to the full vignette on GitHub.

To get started, the first time you use ciftiTools, install it from either CRAN with install.packages() or Github with devtools::install_github(). Here, we will use the CRAN version.

# Check if package installed. If not, install it.
if(!require('ciftiTools', quietly=TRUE)){
  install.packages('ciftiTools')
  # devtools::install_github('mandymejia/ciftiTools') # development version
}

Now we load the ciftiTools package.

library(ciftiTools)

Next, we indicate where to find the Connectome Workbench. This can be the full path to the Connectome Workbench executable file, or the path to its containing folder, in which case ciftiTools will locate the full path. Here, we will use the latter.

Note that this step is skipped with eval=FALSE for the purpose of including the vignette on CRAN.

# Replace '~/Applications' with the actual path to the 
#   Connectome Workbench folder on your computer. If
#   successful, the Workbench executable path will be printed.
ciftiTools.setOption('wb_path', '~/Applications')

Since reading in CIFTI files requires the Connectome Workbench, let’s instead use load_parc to load one of the cortex parcellations included in ciftiTools.

xii <- load_parc() # Loads the Schaefer 100 parcellation.
xii # Summary of the `"xifti"` object.
## ====CIFTI METADATA===================
## Intent:           3007 (dlabel)
## - names           "parcels"
## Measurements:     1 column
## 
## ====BRAIN STRUCTURES=================
## - left cortex     32492 data vertices
## 
## - right cortex    32492 data vertices

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)
rgl::setupKnitr()

# Sometimes the first OpenGL window does not render properly.
rgl::open3d(); rgl::close3d()
## null 
##    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.