ciftiTools | 用于读取、写入、可视化和操作CIFTI文件的R包

文章来源于微信公众号（茗创科技），欢迎有兴趣的朋友搜索关注。

导读

人类连接体项目引入的CIFTI 灰度文件格式进一步推进了基于灰度的分析，将来自左右半球皮层的灰质数据与来自皮层下和小脑的灰质数据合并成一个文件。在灰度空间中进行的分析非常适合通过传统的分析技术和更先进的统计方法(包括贝叶斯方法)来利用大脑和被试之间共享的信息。R语言促进了高级统计技术的使用，但以前几乎没有进行灰度分析的R包。事实上，在任何语言中都很少有用于处理CIFTI文件的综合编程工具。这里，研究者介绍了ciftiTools R包，该包提供了一个用于读取、写入、可视化和操作CIFTI文件和相关数据格式的统一环境。并举例说明了ciftiTools操作，用于在R中处理灰质和表层几何数据，并描述了如何使用ciftiTools来推进基于灰度的功能性MRI数据的统计分析。

前言

基于表层的磁共振(MR)数据分析由Freesurfer首创，并由人类连接体项目(HCP)进一步推广。采用基于表层的分析有很多原因，包括改善整个皮层的可视化，缓解与体素平滑相关的问题，如降低灵敏度和特异性，改进被试间皮层折叠模式和功能区的对齐，以及降维。

最近，基于表层的MR数据只存储在不包含相关的大脑皮层下和小脑灰质区域的数据格式中。例如，GIFTI文件是一种表层格式，可以包含度量数据(如fMRI时间序列)、标签数据(如分割)或特定半球的表层几何数据。在分析中整合皮层下和/或小脑灰质，需要将表层数据与传统NIFTI文件中存储的体素数据配对。为了解决这一局限性，并推进和促进灰度MR数据的采用，这一术语是皮层、皮层下和小脑灰质的统称，HCP引入了CIFTI文件格式。CIFTI是连接性信息技术倡议的首字母缩写。(NIFTI中的N代表神经科学，GIFTI中的G代表几何) CIFTI文件是一种NIFTI文件，它具有一个用于所有灰度数据的数字矩阵，并带有一个XML可扩展标记语言，其中包含关于数据大小和类型、列名和脑结构标签信息。这种组合格式为用户提供了一种简便的文件结构，可以对大脑的所有灰质区域进行分析。

研究者介绍的ciftiTools R包提供了一个用户友好的高级界面，可用于访问CIFTI和分析GIFTI数据。ciftiTools是一套用于读取、写入、可视化、处理和操作CIFTI数据，以及兼容表层几何图形的工具(图1)。支持三种CIFTI文件类型：dtseries(用于时间序列数据)、dscalar(用于结构、连续值数据)和dlabel(用于分组、标签或分类数据)。还支持GIFTI度量数据，以便更广泛地应用于基于表层的分析。研究者引入了对象类型“xifti”，指的是度量或标签数据与GIFTI表层几何文件中编码的表层几何的组合。这有助于表层数据的可视化、处理和分析。

图1.ciftiTools功能概括。

xifti对象类型

图2说明了“xifti”的结构。第一层有三个部分：data，表示每个大脑结构的数据矩阵；Surf，表示左右皮层表面几何图形；meta，表示各种元数据包括内侧壁掩膜(mask)、皮层下标签和掩膜，以及CIFTI特定信息。因为“xifti”是一个列表，其内容可以用$解析。例如，xii$meta$cifti$intent表示返回“xifti”对象xii的CIFTI intent。

图2.“xifti”的结构。

左右皮层表面几何图形本身就是“surf”类的对象。“surf”对象是一个包含三个条目的列表：vertices，faces和hemisphere。“surf”对象也可以与任何“xifti”对象分开存在，允许在没有度量或标签数据的情况下直接可视化、重采样和操作表层几何数据。

is.xifti这个函数可以用来验证R对象是否是一个正确格式的“xifti”对象。在ciftiTools中实现了几种S3方法。S3方法在应用于特定类的对象时控制某些基R函数的行为。目前，“xifti”对象有用于summary，print，plot和一些数学操作的S3方法。

读取和写入

图1A显示了ciftiTools函数read_xifti如何将CIFTI数据作为“xifti”对象导入R中。read_xifti还可以导入GIFTI表层几何数据和CIFTI数据。当“xifti”用write_xifti写入时，数据流是反向的。

as.xifti和read_xifti2两个函数提供了构造“Xifti”对象的替代方法。as.xifti从R数据矩阵创建一个“xifti”，而不是CIFTI文件，允许用户存储可能不是来自真实神经影像的灰度数据。例如，用as.xifti的用户可以使用R中一些功能强大的仿真工具来模拟数据，然后将数据格式化为“xifti”灰度数据。然后，这个“xifti”可以用ciftiTools进行分析，或者可以用R之外的方法和软件将它编写到CIFTI文件进行分析或可视化。read_xifti2从GIFTI度量或标签文件创建一个“xifti”，而不是使用CIFTI文件，其灵活性更大。

与读写相关的其他函数包括separate_xifti，它将CIFTI文件分割为GIFTI度量或标签文件(用于皮质数据)和NIFTI文件(用于皮质下数据)，info_xifti只读取CIFTI文件的元数据。write_xifti2的操作与read_xifti2相反：它将带有表层数据的“xifti”写入GIFTI度量或标签文件。

还可以使用saveRDS将“xifti”对象写入RDS数据文件，并使用readRDS读取，这两个都是基本的R函数。但RDS文件通常不与MATLAB或Python等其他编程平台兼容。对跨平台兼容性感兴趣的用户应该使用write_xifti来生成CIFTI和GIFTI表层几何文件，以便后续在MATLAB、Python或其他工具中使用。

可视化

图1B说明了如何使用view_xifti将“xifti”对象中的灰度数据可视化。同样，通用的R函数plot也可以应用于“xifti”对象，因为view_xifti是“xifti”对象的plot S3方法。view_xifti将用view_xifti_surface绘制皮层数据，用view_xifti_volume绘制皮层下数据。如果“xifti”对象包含皮层和皮层下数据，这两个绘图将共享相同的色阶、调色板和色阶范围。view_xifti_surface和view_xifti_volume也可以直接调用。

view_xifti_surface函数使用rgl包生成皮层表面数据的3D渲染。如果使用view_xifti_surface创建了交互式图形，用户可以单击和拖动以旋转曲面，并滚动以调整其大小。交互式绘图通常会在OpenGL窗口中打开，但在某些特定情况下也可以在HTML中打开。

view_xifti_volume函数默认生成覆盖在2mm MNI结构模板上的皮层下和小脑数据的2D切片图。该函数具有与view_xifti_surface相同的参数，用于控制测量值的绘制和文件存储等。非交互式绘图基于来自oro.nifti包的overlay函数，还有与view_xifti_surface相同的色阶类型、调色板和色阶范围的参数。还包括控制显示的解剖平面和切片指数的参数。交互图是 papayar包的同名函数包装器，允许用户沿着每个解剖轴滚动切片，并读取每个体素的值。可以在GUI中调整色阶、调色板和色阶范围。可以将非交互式图形导出为PNG文件，然后嵌入到R Markdown文档中。

"surf"也可以使用函数view_surf独立于任何"xifti"数据进行可视化。“surf”对象的plot S3方法是view_surf的别名。与view_xifti_surface一样，view_surf基于rgl包，并包含参数来控制视图显示。

ciftiTools还包括view_comp函数，以帮助用户一次显示多个PNG文件。view_comp可用于显示网格中多个列或“xifti”对象的数据，或并排显示相应的皮层和皮层下图形。

Processing

Connectome Workbench是一套用于神经成像数据的开源软件工具，专为HCP数据设计。它包括许多命令行工具，可以对CIFTI文件和其他数据格式进行操作。ciftiTools包为一些Workbench命令提供了一个方便的接口，包括两种常见的处理操作，即重采样和平滑，如图1C所示。“xifti”对象和CIFTI文件都可以直接使用ciftiTools重采样和平滑。

要使用resample_xifti重采样皮层数据，用户只需提供“xifti”对象或CIFTI文件的路径，以及每个半球指定的顶点的目标分辨率。注意，重采样后的确切顶点数可能会与目标分辨率略有不同，这是由于进行重采样的球面映射过程。另外，请注意，皮层下和小脑从未被重采样。如果表层包含在“xifti”对象中或被用户指定为GIFTI文件，它们将与CIFTI数据矩阵一起被重采样到相同的目标分辨率。也可以用resample_gifti函数和resample_surf函数分别对GIFTI文件和“surf”对象进行重采样度量、标签和表层几何图形。

平滑可以沿着皮层表面进行几何平滑，也可以使用smooth_cifti函数对皮层下和小脑数据进行体素平滑。用户只需提供一个“xifti”对象或CIFTI文件的路径和平滑内核的半宽度(FWHM)。

resample_xifti和smooth_xifti需要考虑的一个问题是，它们处理CIFTI文件的速度要比等效的“xifti”对象快。这是因为Connectome Workbench命令对CIFTI文件进行操作，所以在两个对xifti对象进行操作的函数的后台，必须将该对象写入CIFTI文件，重采样或平滑，然后再读入。对于具有一个或几个测量值的CIFTI数据，编写“xifti”对象非常快，但是对于具有许多测量值的高分辨率CIFTI，例如fMRI时间序列数据，编写“xifti”对象可能会很慢。因此，在后一种情况下，如果可能的话，在读取CIFTI文件之前直接重采样或平滑会更有效。

数学和操作

如图1D所示，ciftiTools提供了几个方便的函数来修改“xifti”对象，同时保留有效的“xifti”对象结构。这分为两类：操纵和数学。Manipulation函数显式地更改一个或多个“xifti”对象。包括添加或删除大脑结构的函数，数据矩阵的子集或与其他数据结合等。Manipulation函数减少了用户手动编辑“xifti”对象中的单个大脑结构条目的需要，同时确保适当更新元数据以保留有效的“xifti”格式。Math函数仅对一个或多个“xifti”对象的数据矩阵执行数学运算，例如算术和单变量转换。这些基本R函数可以直接应用于“xifti”对象。为了对“xifti”对象执行更高级的数学操作或分析，建议用户使用as.matrix提取数据矩阵，然后使用newdata_xifti函数更新“xifti”对象的数据矩阵。不过，ciftiTools中包含的操作和数学函数允许用户方便地使用CIFTI数据，并使用简洁的代码，同时为用户提供构建块，以创建更复杂的、特定于用户需要的处理过程。

示例

研究者通过一个简单的示例分析来说明ciftiTools的一些功能，该示例分析了来自HCP的静息态fMRI (rfMRI)扫描的计算和可视化种子相关性，该HCP已经用ICA-FIX进行了预处理。种子点是后扣带皮层(PCC)，是默认模式网络(DMN)的高度连接节点。研究者使用Schaefer等人(2018)创建的功能分割来定义PCC和其他脑区。分析过程分为四个步骤：(1)读取和平滑fMRI数据；(2)读取分割部分数据；(3)计算种子相关性；(4)可视化和保存结果。

读取并平滑fMRI数据

首先加载ciftiTools并设置路径于Connectome Workbench文件夹下。

library(ciftiTools)

## ************************************************

## ciftiTools requires the path to the Connectome Workbench folder,

## or directly to `wb_command(.exe)`. Please execute the command

## `ciftiTools.setOption('wb_path', 'path/to/workbench')`

## If you do not have the Connectome Workbench, install it here:

## humanconnectome.org/software/get-connectome-workbench

## ************************************************

ciftiTools.setOption("wb_path", "workbench")

## Using this Workbench path: 'workbench/bin_windows64/wb_command.exe'.

使用read_xifti读取包含静息态fMRI (rfMRI)数据的CIFTI文件。默认情况下，只有左和右皮层会被读取：设置brainstructures = "all"也可以读取皮层下数据。为简便起见，研究者在示例分析中不包括皮层下数据，感兴趣的小伙伴可以参见补充材料。

xii <- read_xifti("Data/rfMRI_FIX.dtseries.nii")

xii将CIFTI数据存储为“xifti”对象。summary或者调用print S3方法，可以概览内容：

xii

## ====CIFTI METADATA===================

## Intent: 3002 (dtseries)

## - time step 0.72 (seconds)

## - time start 0

## Measurements: 1200 columns

## ====BRAIN STRUCTURES=================

## - left cortex 29696 data vertices

## 2796 medial wall vertices (32492 total)

## - right cortex 29716 data vertices

## 2776 medial wall vertices (32492 total)

S3方法as.matrix 将以矩阵形式返回时间序列数据，行(位置：顶点或体素)和列(测量值：时间点)。像dim这样的函数，强制输入到数据矩阵中的代码如下：

dim(xii)

## [1] 59412 1200

用使用高斯平滑器的smooth_xifti函数对数据进行空间平滑处理。这里使用默认的5毫米FWHM宽度，但是使用smooth_xifti函数的surf_FWHM参数也可以实现其他平滑。平滑原始CIFTI文件，然后读取它，而不是平滑xii，后者会慢一些。

smooth_xifti("Data/rfMRI_FIX.dtseries.nii", "Data/rfMRI_FIX_sm.dtseries.nii")xii_sm <- read_xifti("Data/rfMRI_FIX_sm.dtseries.nii")

画出xii和xii_sm的第一列来了解数据规模、范围和平滑效果。plot将通过调用view_xifti_surface创建皮层数据的3D可视化。这里将分别绘制每个“xifti”，将两个图保存为PNG文件，然后将PNG文件与view_comp组合在一起。

plot(xii, title="Original", fname="Plots/rfMRI.png")

## `zlim` not provided: using color range 0 - 13500 (data limits: 1160 - 17000).

plot(xii_sm, title="Smoothed", fname="Plots/rfMRI_sm.png")

## `zlim` not provided: using color range 0 - 13300 (data limits: 2600 - 15100).

(ref：my-caption)使用smooth_xifti平滑前后的fMRI体素。

view_comp(c("Plots/rfMRI.png", "Plots/rfMRI_sm.png"), ncol=2)

图3.(ref：my-caption)

色阶范围是根据数据自动确定的，颜色接近，但是右边的数据显然更平滑。

分割部分的读取

首先进行加载。为了方便起见，ciftiTools包含了一些常用的分割，可以使用load_parc读取。在这里，研究者使用了Schaefer分割为400个部分。其他CIFTI或GIFTI格式的分割可分别使用read_xifti或read_xifti2读取。

parc <- load_parc("Schaefer_400")

同样，可以通过使用summary来获得“xifti”对象parc的概览。

parc

## ====CIFTI METADATA===================

## Intent: 3007 (dlabel)

## - names "parcels"

## Measurements: 1 column

## ====BRAIN STRUCTURES=================

## - left cortex 32492 data vertices

## - right cortex 32492 data vertices

分别可视化parcel 14，它与PCC非常接近。使用transform_xifti创建一个只包含该parcel的掩膜。结果如图4所示

plot(parc, borders="black", title="Schaefer 400", fname="Plots/parc.png")parc_PCC <- transform_xifti(parc, function(x){ ifelse(x == 14, 14, 0) })
plot(parc_PCC, borders="black", title="Parcel 14 (PCC)", fname="Plots/pPCC.png")

view_comp(c("Plots/parc.png", "Plots/pPCC.png"), ncol=2)

图4.Schaefer分割和PCC。

计算种子的相关性

现在有了平滑的rfMRI数据和分割，接下来可以计算种子相关性。从每个parcel的平均时间序列开始。直接使用parcel数据比使用parc“xifti”对象更容易。因此，从将分割转化为向量开始，然后将xii_sm中的内侧壁顶点替换为NA数值，这样分割向量的长度parc_vec将匹配xii_sm中皮层数据顶点的数量。

parc_vec <- c(as.matrix(parc))length(parc_vec)

## [1] 64984

xii_sm <- move_from_mwall(xii_sm, NA)dim(xii_sm)

## [1] 64984 1200

现在，对于每个parcel，将获得其组成顶点的平均时间序列。具体来说，预先分配一个矩阵xii_pmean，然后对于每个parcel，将获得其所有顶点的fMRI时间序列，在忽略内侧壁值的情况下，取整个空间的平均值，然后将产生的时间序列保存为xii_pmean行。

xii_mat <- as.matrix(xii_sm)xii_pmean <- matrix(nrow=400, ncol=ncol(xii_mat))for (p in 1:400) {data_p <- xii_mat[parc_vec==p,]xii_pmean[p, ] <- colMeans(data_p, na.rm=TRUE)}

然后计算PCC parcel与其他parcel之间的种子相关性：

seed_cor <- cor(t(xii_pmean))[,14]

可视化和保存结果

使用newdata_xifti创建一个新的“xifti”来可视化结果。首先，将parc_vec转换为xii_seed。然后，使用select_xifti初始化一列的“xifti”，并使用newdata_xifti将其数据替换为xii_seed。

xii_seed <- c(NA, seed_cor)[parc_vec + 1]xii1 <- select_xifti(xii_sm, 1)xii_seed <- newdata_xifti(xii1, xii_seed)

现在，再次使用“xifti”S3方法绘图。两次使用它来演示view_xifti自动选择适当的zlim的能力(图5)。

plot(xii_seed, zlim=c(-1, 1), title="Set zlim", fname="Plots/seed.png")plot(xii_seed, title="Auto zlim", fname="Plots/seed2.png")

## `zlim` not provided: using color range -0.345 - 0.345 (data limits: -0.374 - 1).

view_comp(c("Plots/seed.png", "Plots/seed2.png"), ncol=2)

图5.PCC种子相关。

正如预期的那样，研究者发现大多数种子相关值为正或接近于零，种子相关最高的脑区是DMN的组成部分。

最后，使用write_xifti保存分析结果。将数据写入一个“dscalar” CIFTI，因为它既不表示时间序列(“dtseries”) ，也不表示类别/标签数据(“dlabel”)。

write_xifti(xii_seed, "Data/PCC_seedCor.dscalar.nii")

## Writing left cortex.

## Writing right cortex.

## Creating CIFTI file from separated components.

file.exists("Data/PCC_seedCor.dscalar.nii")

## [1] TRUE

其他R包

ciftiTools依赖于其他几个R包来处理GIFTI和NIFTI格式的数据。具体来说，gifti包支持读取、写入和解析GIFTI文件。RNifti包支持读写NIFTI文件，特别是从CIFTI文件中分离出来的皮层下数据。皮层可视化基于rgl包。皮层下可视化是基于绘制静态图的oro.nifti包和用于交互图绘制的papayar包。这些包的依赖关系列表可在DESCRIPTION文件中找到。

同时，研究者详细地描述了cifti R、gifti R、freesurferformat、fsbrain R、ggseg、ggseg3d、ggsegExtra R包，并将这些包的功能与ciftiTools的功能进行了比较，这里就不赘述了。

在其他编程环境中使用CIFTI文件

Python和MATLAB编程语言开发了一些工具，为CIFTI处理、分析和可视化提供不同级别的支持。如Python：ciftify、NiBabel。MATLAB：cifti-matlab。

总结

本文中介绍的ciftiTools是一个用于读取、写入、可视化和操作CIFTI和GIFTI文件的R包。ciftiTools的稳定版本可以在以下网址获得：

CRAN：

https://cran.r-project.org/web/packages/ciftiTools/index.html

GitHub：

https://github.com/mandymejia/ciftiTools/

原文：ciftiTools: A package for reading, writing, visualizing, and manipulating CIFTI files in R.

https://doi.org/10.1016/j.neuroimage.2022.118877