ciftiTools Mini Demo
Author: Damon Pham & Amanda Mejia
Date: 2025-01-23

# `ciftiTools` Mini Demo

#### Damon Pham & Amanda Mejia

#### 2025-01-23

`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)

    ## 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.