dcanlabs/abcd-hcp-pipeline

ABCD-HCP BIDS fMRI 处理流程

![DOI]([***]

（2021年12月7日）注意：此仓库已废弃。abcd-hcp-pipeline v0.1.0及以上版本可从新的https://hub.docker.com/repository/docker/dcanumn/abcd-hcp-pipeline/%E8%8E%B7%E5%8F%96%E3%80%82

该软件以BIDS文件夹为输入，确定DCAN实验室修改版HCP管道的参数，并调用适当代码运行被试数据。

镜像概述和主要用途

ABCD-HCP BIDS fMRI处理流程是一个基于BIDS（脑影像数据结构）标准的功能磁共振成像（fMRI）预处理应用，改编自人类连接组计划（HCP）的最小预处理管道。它能够接收符合BIDS格式的输入数据，自动配置并运行完整的fMRI预处理流程，生成标准化的输出结果，适用于神经影像研究中的数据预处理需求。

核心功能和特性

• 支持BIDS标准输入数据，减少用户配置工作
• 集成DCAN实验室修改版HCP预处理管道，包含结构像和功能像处理
• 提供多模态处理支持，可处理fMRI数据及相关场图数据
• 支持并行处理，可通过指定CPU核心数加速处理
• 提供阶段式运行功能，支持从指定阶段重启处理流程
• 包含质量控制输出（执行摘要），便于结果检查
• 支持自定义模板，适应特殊人群（如老年人群）数据处理

安装

若要通过容器运行此软件，您需要自行获取FreeSurfer许可证。

获取FreeSurfer许可证

使用Docker

运行前，需通过以下命令将镜像加载到Docker服务：

bash
docker pull dcanlabs/abcd-hcp-pipeline

如果拉取过程中出现"no space left on device"错误，可能需要清理Docker registry中的旧镜像和容器，并可能增加Docker分配的空间。

使用Singularity

您可以从Docker仓库拉取镜像，或从仓库构建镜像并保存到工作目录：

bash
singularity pull docker://dcanlabs/abcd-hcp-pipeline

singularity build abcd-hcp-pipeline.img docker://dcanlabs/abcd-hcp-pipeline

这两个命令本质相同，但后者允许您控制文件名。

使用方法和配置说明

使用该镜像需要BIDS格式的输入数据。有关BIDS格式的更多信息及数据转换工具，请参考[***]

以下是基本命令调用方式，选项详情见下文。

Docker使用

bash
docker run --rm \
    -v /path/to/bids_dataset:/bids_input:ro \
    -v /path/to/outputs:/output \
    -v /path/to/freesurfer/license:/license \
    dcanlabs/abcd-hcp-pipeline /bids_input /output --freesurfer-license=/license [选项]

Singularity使用

bash
env -i singularity run \
    -B /path/to/bids_dataset:/bids_input \
    -B /path/to/outputs:/output \
    -B /path/to/freesurfer/license.txt:/opt/freesurfer/license.txt \
    ./abcd-hcp-pipeline.img /bids_input /output --freesurfer-license=/opt/freesurfer/license.txt [选项]

注意：许可证需直接挂载到freesurfer文件夹，且Singularity调用前需添加"env -i"。

参数选项

bash
发展认知与神经影像（DCAN）实验室fMRI处理管道[1]。
此BIDS应用启动基于人类连接组计划最小预处理管道构建的功能MRI处理流程[2]。
该应用仅需符合BIDS规范的数据集，用户几乎无需额外配置。BIDS格式和应用详情见http://bids.neuroimaging.io/

位置参数：
  bids_dir              输入BIDS数据集根目录路径。详见描述中的BIDS标准链接。推荐使用Dcm2Bids将被试DICOM数据转换为BIDS格式。
  output_dir            管道所有中间文件和输出文件的输出目录路径，日志也存储于此。

可选参数：
  -h, --help            显示帮助信息并退出
  --version, -v         显示程序版本号并退出
  --participant-label ID [ID ...]
                        可选的被试ID列表。默认为BIDS输入目录中所有发现的ID。被试标签不包含"sub-"前缀
  --freesurfer-license LICENSE_FILE
                        若使用docker或singularity，需获取并提供自己的FreeSurfer许可证。可通过填写此表单获取许可证：https://surfer.nmr.mgh.harvard.edu/registration.html
  --all-sessions        运行被试时将所有会话合并为一个。
  --ncpus NCPUS         用于并发处理和算法加速的核心数。警告：会导致ANTs和FreeSurfer产生非确定性结果。
  --stage STAGE         从指定阶段开始继续运行。选项：PreFreeSurfer, FreeSurfer, PostFreeSurfer, FMRIVolume, FMRISurface, DCANBOLDProcessing, ExecutiveSummary, CustomClean
  --bandstop LOWER UPPER
                        运动回归器带阻滤波器参数。建议边界匹配被试组呼吸频率的四分位范围（次/分钟），或直接匹配BIDS生理数据[3]。对于采集频率大于1Hz（TR小于1秒）的数据，强烈推荐使用这些参数。默认无滤波器。

特殊管道选项：
  适用于替代管道或无法从BIDS数据推断的额外阶段的选项。

  --custom-clean JSON   管道成功完成后运行DCAN清理脚本，根据custom-clean JSON中指定的文件结构删除管道输出。自定义清理阶段必需。
  --abcd-task           运行ABCD任务数据通过任务fMRI分析，将此阶段添加到末尾。警告：非通用用途设计，未来版本将包含通用任务分析模块。
  --study-template HEAD BRAIN
                        用于中间非线性配准和掩膜的模板头和脑图像，在人群与平均成人差异较大时有效，例如脑室较大的老年人群。
  --ignore {func,dwi}   忽略处理中的模态。可重复使用该选项。

运行时选项：
  运行时行为的特殊更改。调试功能。

  --check-outputs-only  检查每个阶段的输出是否存在然后退出。用于调试。
  --print-commands-only
                        打印每个阶段的运行命令到shell然后退出。
  --ignore-expected-outputs
                        即使某些预期输出缺失，仍继续运行管道。

参考文献
----------
[1] Sturgeon, D., Perrone, A., Earl, E., & Snider, K. 
DCAN_Labs/abcd-hcp-pipeline. DOI: 10.5281/zenodo.2587209. (查看zenodo.org获取特定版本的DOI/引用)
[2] Glasser, MF. et al. The minimal preprocessing pipelines for the Human
Connectome Project. Neuroimage. 2013 Oct 15;80:105-24.
10.1016/j.neuroimage.2013.04.127
[3] Fair, D. et al. Correction of respiratory artifacts in MRI head motion
estimates. Biorxiv. 2018 June 7. doi: https://doi.org/10.1101/337360
[4] Dale, A.M., Fischl, B., Sereno, M.I., 1999. Cortical surface-based
analysis. I. Segmentation and surface reconstruction. Neuroimage 9, 179-194.
[5] M. Jenkinson, C.F. Beckmann, T.E. Behrens, M.W. Woolrich, S.M. Smith. FSL.
NeuroImage, 62:782-90, 2012
[6] Avants, BB et al. The Insight ToolKit image registration framework. Front
Neuroinform. 2014 Apr 28;8:44. doi: 10.3389/fninf.2014.00044. eCollection 2014.

使用示例

使用FreeSurfer、带阻滤波器和研究模板运行被试

首先确保已构建符合BIDS规范的bids_input文件夹。可使用https://github.com/cbedetti/Dcm2Bids%E8%BF%9B%E8%A1%8C%E6%9E%84%E5%BB%BA%E3%80%82

以下代码块展示使用一些高级参数的示例：

我们定义了运动数据的带阻滤波器--bandstop 18.582 25.726，其中被试人群的呼吸频率在18-25次/分钟之间（四分位范围，即25th和75th百分位，非绝对范围）。

对于研究模板，我们将额外路径挂载到Docker容器-v /path/to/template/folder:/atlases，其中包含这些文件：study_head.nii.gz和study_brain.nii.gz。然后，使用--study-template /atlases/study_head.nii.gz /atlases/study_brain.nii.gz添加这些模板作为研究模板头和脑图像（使用挂载到Docker容器中的路径/atlases）。

我们还请求4个核心以加快处理速度--ncpus 4

bash
docker run --rm \
    -v  /path/to/bids_dataset:/bids_input:ro \
    -v /path/to/outputs:/output \
    -v /path/to/freesurfer/LICENSE:/license:ro \
    -v /path/to/template/folder:/atlases \
    dcanlabs/abcd-hcp-pipeline /bids_input /output \
        --freesurfer-license /license \
        --bandstop 18.582 25.726 \
        --study-template /atlases/study_head.nii.gz /atlases/study_brain.nii.gz \
        --ncpus 4

注意：挂载标志-v跟随docker run，属于Docker选项；而--freesurfer-license、--bandstop和--study-template标志跟随dcanlabs/abcd-hcp-pipeline，属于本管道的选项，详见上述用法说明。

其他信息

输出

输出按以下结构组织：

output_dir/
|__ sub-id
    |__ ses-session
        |__ files
        |   |__ executive_summary
        |   |__ MNINonLinear
        |   |   |__ fsaverage_LR32k
        |   |   |__ Results
        |   |__ T1w
        |   |   |__ id
        |   |__ task-taskname
        |__ logs

files

• executive_summary：其中的.html文件可打开以质量检查管道结果
• MNINonLinear：包含164k分辨率的最终解剖空间结果
• MNINonLinear/fsaverage_LR32k：32k分辨率的最终解剖空间，功能数据最终投影到此空间
• MNINonLinear/Results：最终空间功能数据
• T1w：包含原生空间解剖数据及中间预处理文件
• T1w/id：T1w内的被试ID文件夹是FreeSurfer被试文件夹
• task-taskname：这些文件夹包含中间功能预处理文件

logs

logs包含每个阶段的日志文件。出现错误时，除应用本身的标准错误和标准输出（默认打印到命令行）外，还需查阅这些文件。

status.json代码：

• unchecked: 999
• succeeded: 1
• incomplete: 2
• failed: 3
• not_started: 4

重新运行

--stage选项允许在管道提前终止时从特定阶段重新启动。

特殊管道

特殊管道选项设计用于特定数据集。

若使用老年或神经退行性人群数据，添加"研究模板"通常能改善结果。研究模板通常使用ANTs构建被试平均模板，作为中间配准阶段，帮助脑室较大被试的非线性配准。

注意：abcd-task与BIDS文件夹结构不兼容，未来版本将添加兼容的任务模块，支持自动处理BIDS格式任务数据。

其他

单核心运行时管道可能需要超过24小时。建议至少使用4个核心，并确保至少12GB总内存（每核心至少3GB）。大多数fMRI处理可并行进行，因此使用的核心数最好能整除fMRI运行次数。

临时/ scratch空间：默认所有处理在输出文件夹中进行。未来将改进磁盘空间使用效率，并支持使用临时文件系统挂载进行高速读写。

软件将优先使用自旋回波场图（若存在），其次是梯度场图，最后不使用场图，这与观察到的最佳性能一致。注意：存在多种模态时不会产生错误或警告。

如需指定使用自旋回波场图（即将每对场图映射到单个功能运行），需在BIDS输入侧car JSON中插入IntendedFor字段，指定场图用于哪些功能运行。该字段在BIDS规范中有详细说明。

对于多波段（快速TR）数据，建议使用带阻滤波器以减轻伪高运动数值。运动回归器上用于帧位移计算的带阻滤波器参数应基于被试呼吸频率选择。

当前限制

扩散场图仍在开发中，因为不同扫描仪型号/品牌的数据差异显著。如遇场图问题，请提交issue，我们将添加新格式支持。

DWI处理将在未来版本中包含。对此功能的需求将加速其发布。

理想的运动滤波参数尚未在不同重复时间或青少年以外的人群中进行严格测试。此外，尚未实现从BIDS格式自动读取生理数据，因此应仔细确定适当范围。详见用法中的参考文献[3]。

软件目前不支持单模态的动态采集参数（例如，两个fMRI序列的不同相位编码方向，如左右和右左）。需为具有不同fMRI参数的会话创建单独的BIDS数据集进行处理。