nhp-abcd-bids-pipeline

该仓库包含用于非人灵长类（即猕猴）的BIDS App，用于运行dcan-macaque-pipeline。

该软件以BIDS文件夹为输入，确定DCAN Labs修改的HCP管道参数，并调用适当的代码来运行受试者数据。

使用Docker

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

bash
docker pull dcanumn/nhp-abcd-bids-pipeline

如果在拉取过程中收到“设备上没有空间”错误，可能需要清理Docker registry中的旧/悬空镜像和容器，并可能增加分配给Docker的空间。

使用Singularity

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

bash
singularity pull docker://dcanumn/nhp-abcd-bids-pipeline

singularity build nhp-abcd-bids-pipeline.img docker://dcanumn/nhp-abcd-bids-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 \
    dcanumn/nhp-abcd-bids-pipeline /bids_input /output \
    --freesurfer-license=/license [选项]

注意：FreeSurfer许可证需直接挂载到FreeSurfer文件夹中。

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 \
    ./nhp-abcd-bids-pipeline.img /bids_input /output \
    --freesurfer-license=/opt/freesurfer/license.txt [选项]

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

选项

python
usage: nhp-abcd-bids-pipeline [-h] [--version] [--aseg ASEG]
                              [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                              [--session-id SESSION_ID [SESSION_ID ...]]
                              [--all-sessions] [--ncpus NCPUS] [--stage STAGE]
                              [--bandstop LOWER UPPER]
                              [--max-cortical-thickness MAX_CORTICAL_THICKNESS]
                              [--registration-assist MOVING REFERENCE]
                              [--custom-clean JSON]
                              [--t1-brain-mask T1_BRAIN_MASK]
                              [--t2-brain-mask T2_BRAIN_MASK]
                              [--study-template HEAD BRAIN]
                              [--t1-reg-method {FLIRT_FNIRT,ANTS,ANTS_NO_INTERMEDIATE}]
                              [--check-outputs-only] [--print-commands-only]
                              [--ignore-expected-outputs]
                              [--multi-template-dir MULTI_TEMPLATE_DIR]
                              [--hyper-normalization-method {ADULT_GM_IP,ROI_IPS,NONE}]  
                              [--norm-gm-std-dev-scale SCALE_FACTOR]
                              [--norm-wm-std-dev-scale SCALE_FACTOR]
                              [--norm-csf-std-dev-scale SCALE_FACTOR]
                              [--make-white-from-norm-t1] [--single-pass-pial]
                              bids_dir output_dir

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

位置参数:
  bids_dir              输入BIDS数据集根目录路径。有关BIDS格式的更多信息，请参见描述中的链接。建议使用dcan bids gui或dcm2bids将参与者DICOM转换为BIDS格式。
  output_dir            管道所有中间文件和输出文件的输出目录路径，日志也存储在此路径中。

可选参数:
  -h, --help            显示此帮助消息并退出
  --version, -v         显示程序版本号并退出
  --aseg ASEG           指定FreeSurfer使用的aseg文件路径；替换受试者T1w目录中的默认aseg_acpc.nii.gz。指定的aseg文件名必须为"aseg_acpc.nii.gz"。默认值：使用PreFreeSurfer阶段通过ANTs联合标签融合在受试者T1w目录中生成的aseg_acpc.nii.gz。
  --participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
                        可选的参与者ID列表。默认值：BIDS输入目录下找到的所有ID。参与者标签不包含"sub-"前缀。
  --session-id SESSION_ID [SESSION_ID ...]
                        按会话ID筛选输入数据集。默认值：在受试者输入目录下找到的所有ID。会话ID不包含"ses-"前缀。
  --all-sessions        运行受试者时将所有会话合并为一个。
  --ncpus NCPUS         用于并发处理和算法加速的核心数。警告：会导致ANTs和FreeSurfer产生非确定性结果。
  --stage STAGE         从指定阶段开始继续运行。选项：PreFreeSurfer、FreeSurfer、PostFreeSurfer、FMRIVolume、FMRISurface、DCANBOLDProcessing、ExecutiveSummary
  --bandstop LOWER UPPER
                        运动回归器带阻滤波器参数。建议边界匹配参与者组呼吸频率（bpm）的四分位距，或直接匹配BIDS生理数据[3]。对于采集频率约为1 Hz或更高（TR≤1.0）的数据，强烈推荐这些参数。默认值：无滤波器。
  --max-cortical-thickness MAX_CORTICAL_THICKNESS
                        FreeSurfer允许的最大皮质厚度。默认值=5 mm。
  --registration-assist MOVING REFERENCE
                        提供两个任务/运行名称（移动图像和参考图像）以辅助解剖配准。用例：超顺磁性氧化铁增强fMRI在典型FSL flirt指标下无法一致配准到T1w图像。使用bold图像作为参考有助于解决此问题。例如：task-CErest01 task-rest01
  --t1-brain-mask T1_BRAIN_MASK
                        指定掩码文件路径。指定的文件将替代PreliminaryMasking和PreFreeSurfer阶段的默认掩码处理。--t2-brain-mask可与此选项结合使用，但不是必需的。
  --t2-brain-mask T2_BRAIN_MASK
                        指定掩码文件路径。指定的文件将替代PreliminaryMasking和PreFreeSurfer阶段的默认掩码处理。此选项可与--t1-brain-mask结合使用，但不是必需的。
  --study-template HEAD BRAIN
                        用于掩码非线性和T1w到标准图谱（Yerkes19）的可选中间配准的模板头部和脑图像。有效解决男性/女性群体头部形状差异、年龄组差异或解剖视野差异。默认值：使用Yerkes19模板。
  --t1-reg-method {FLIRT_FNIRT,ANTS,ANTS_NO_INTERMEDIATE}        
                        指定PreFreeSurfer阶段中受试者T1w配准到参考图像的方法。FLIRT_FNIRT使用FLIRT进行初始仿射变换，然后使用FNIRT配准到参考图像。ANTS先中间配准到研究模板，然后配准到参考图像，两者均使用antsRegistrationSyN。ANTS_NO_INTERMEDIATE直接使用antsRegistrationSyN配准到参考图像。默认值：FLIRT_FNIRT。
  --multi-template-dir MULTI_TEMPLATE_DIR
                        联合标签融合模板目录。该目录应仅包含每个子目录，每个子目录包含"T1w_brain.nii.gz"和"Segmentation.nii.gz"。每个子目录可具有任意名称和任意数量的附加文件。
  --hyper-normalization-method {ADULT_GM_IP,ROI_IPS,NONE}
                        指定FreeSurfer中超归一化步骤使用的强度分布：ADULT_GM_IP调整整个基础图像，使目标GM的IP大致匹配参考（即成人freesurfer图谱）的GM的IP。然后将目标图像中的WM偏移以匹配参考中WM的直方图。ROI_IPS分别调整每个ROI（GM、WM、CSF）的强度分布并重新组合。NONE跳过超归一化步骤。允许用户运行PreFreeSurfer，应用新的实验性超归一化方法，然后从FreeSurfer阶段重新开始。默认值：ADULT_GM_IP。
  --norm-gm-std-dev-scale SCALE_FACTOR
                        指定超归一化FreeSurfer T1w图像中GM体素标准差相对于成人参考图像标准差的缩放因子（浮点数）。降低GM体素的标准差可解决当T1w皮质GM对比度不均匀或在软脑膜表面附近较弱时FreeSurfer表面生成不良的问题。默认值=1。
  --norm-wm-std-dev-scale SCALE_FACTOR
                        指定超归一化FreeSurfer T1w图像中WM体素标准差相对于成人参考图像标准差的缩放因子（浮点数）。默认值=1。
  --norm-csf-std-dev-scale SCALE_FACTOR
                        指定超归一化FreeSurfer T1w图像中CSF体素标准差相对于成人参考图像标准差的缩放因子（浮点数）。当与ADULT_GM_IP超归一化一起使用时，此选项无效。默认值=1。
  --make-white-from-norm-t1
                        使用归一化T1w体积（如果存在）作为FreeSurfer mris_make_surfaces生成白质表面的输入。默认值：False。
  --single-pass-pial
                        使用超归一化T1w脑图像（如果未省略超归一化）通过mris_make_surfaces单次生成软脑膜表面；省略mris_make_surfaces的第二次运行（其中第一次运行生成的表面将用作先验，并使用非超归一化T1w脑图像）。默认值：False。

特殊管道选项:
  属于替代管道或未从BIDS数据推断的额外阶段的选项。

  --custom-clean JSON   管道成功完成后运行dcan清理脚本，根据custom-clean json中指定的文件结构删除管道输出。

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

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

参考文献
----------
[1] dcan-pipelines（目前，请在使用本软件时引用[3]）
[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: [***]
[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.

构建Docker镜像

该仓库包含创建包含BIDS应用和管道脚本的Docker镜像所需的Dockerfile（和其他文件）。此版本不需要像先前版本那样预先构建DCAN-Labs internal-tools；internal-tools Dockerfile的内容现已集成到nhp-abcd-bids-pipeline Dockerfile中。

其他信息

管道阶段

有关每个阶段的关键输入和输出以及审查和故障排除输出的提示，请参见管道阶段摘要文档。

!flowchart-PreliminaryMasking !flowchart-PreFreeSurfer !flowchart-FreeSurfer !flowchart-PostFreeSurfer !flowchart-FMRIVolume !flowchart-FMRISurface !flowchart-DCANBOLDProcessing !flowchart-ExecutiveSummary

输出

输出按以下结构组织：

output_dir/sub-id/ses-session/

• files/
• logs/

files

• T1w: 包含原生空间解剖数据以及中间预处理文件。
• T1w/participantID: T1w中的参与者ID文件夹是FreeSurfer受试者文件夹。
• T2w: 包含原生空间解剖数据以及中间预处理文件。
• MNINonLinear: 包含164k分辨率的最终空间解剖结果。
• MNINonLinear/Results: 最终空间功能数据。
• MNINonLinear/fsaverage_32K: 32k分辨率的最终空间解剖结构，功能数据最终投影到此处。
• task-taskname: 这些文件夹包含中间功能预处理文件。
• summary_DCANBOLDProc_ver/executivesummary: 其中的.html文件可打开以进行管道结果的质量检查。

关于"MNINonLinear"的说明

"MNINonLinear"输出目录的名称继承自DCAN-HCP BIDS应用/abcd-bids-pipeline，其中标准输出空间为MNINonLinear。在此管道中，"MNINonLinear"目录中的图像实际上处于MacaqueYerkes19空间。

logs

logs包含每个阶段的日志文件。发生错误时，除了应用程序本身的标准错误/输出（默认打印到命令行）外，请查阅这些文件。

status.json代码:

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

重新运行

--stage选项允许在管道提前终止的情况下重新启动管道。

杂项

• 临时/暂存空间：默认情况下，所有处理都在输出文件夹中进行。未来可能会改进磁盘空间的使用效率，并支持使用临时文件系统挂载进行热读写。
• 软件将优先使用自旋回波场图（如果存在），然后是梯度场图，最后是无场图，这与观察到的最佳性能一致。注意，如果存在多种模态，不会产生错误或警告。
• 要指定使用自旋回波场图（即每个功能运行为一对场图），必须在BIDS输入侧car json中插入"IntendedFor"字段，该字段为每个场图指定一个功能运行。该字段在BIDS规范中有更详细的说明。
• 对于多波段（快速TR）数据，建议使用带阻滤波器以减少 artifactually high 运动数值。在帧位移计算前对运动回归器使用的带阻滤波器参数必须根据受试者呼吸频率选择。

当前限制

• 尚未在不同重复时间或人群中对理想的运动滤波参数进行稳健测试。此外，尚未实现从BIDS格式自动读取生理数据，因此应仔细确定适当的范围。
• 软件目前不支持单一模态的动态采集参数，例如BIDS目录中2个fMRI的不同相位编码方向（但BIDS fmap目录中用于FSL topup的相反PE方向扫描是允许的）。具有不同fMRI参数的会话必须通过为其创建单独的BIDS数据集来处理。当存在多个具有相同BIDS ses-、task-（可选run-）标签的运行时（例如必须通过acq-标签区分的运行），FMRIVolume阶段将发生错误。