bids

脑成像数据结构（BIDS）

概述

脑成像数据结构（BIDS）是一项社区标准，用于组织和描述神经科学与生物医学研究数据集。它定义了一套一致的文件命名规范、目录层级和元数据架构，使人类和软件工具都能立即理解数据集。BIDS 由 BIDS 规范（当前为 v1.11.x）管理，并由社区通过 BIDS-Standard GitHub 组织维护。

虽然 BIDS 最初面向 MRI，但其适用范围早已超出神经成像。该规范现已涵盖 11 种模态，涉及成像、电生理和行为数据：

• 成像：MRI（结构、功能、扩散、场图、灌注/ASL）、PET、显微成像
• 电生理：EEG、MEG、iEEG（颅内 EEG）、EMG
• 其他：NIRS（近红外光谱）、动作捕捉、行为数据（不含成像）、MR 波谱

活跃的 BEP 正在进一步扩展 BIDS——值得关注的是 BEP032（微电极电生理）将添加对细胞外记录的支持，包括 Neuropixels 探针，使 BIDS 能够应用于动物神经科学研究中广泛使用的方法（另请参阅 neuropixels-analysis 技能）。

主要数据存储库（OpenNeuro、DANDI）、领先期刊（NeuroImage、Human Brain Mapping、Scientific Data）和资助机构（NIH、ERC）均要求或强烈鼓励采用该标准。

BIDS 的 Python 生态系统以 PyBIDS（pybids）为核心，用于查询和索引 BIDS 数据集；并提供 bids-validator（基于 Deno，可通过 PyPI 包 bids-validator-deno 获取，或直接通过 Deno 使用）进行合规性检查。DICOM 转换通常使用 HeuDiConv、dcm2bids 或 BIDScoin。

何时使用此技能

在以下情况下使用此技能：

• 将原始神经科学数据（成像、电生理、行为数据）整理为符合 BIDS 的目录结构
• 查询现有 BIDS 数据集，以按受试者、会话、任务、运行或模态查找特定文件
• 在共享或提交数据集前，根据 BIDS 规范对其进行验证
• 将扫描仪生成的 DICOM 数据转换为 BIDS 格式
• 编写或编辑 JSON 侧边元数据文件
• 创建符合 BIDS 的衍生数据（预处理数据、分析输出）
• 为新数据集设置 dataset_description.json
• 使用 BIDS 实体（受试者、会话、任务、采集、运行等）
• 配置 .bidsignore，以将文件排除在验证之外
• 准备数据，以便上传到 OpenNeuro、DANDI 或其他支持 BIDS 的数据存储库

安装

# Core BIDS querying library
uv pip install pybids

# BIDS validator (Deno-based, installed via PyPI wrapper)
uv pip install bids-validator-deno
# Alternative: install directly via Deno
# deno install -g -A npm:bids-validator

# DICOM-to-BIDS converters (install as needed)
uv pip install heudiconv       # HeuDiConv - heuristic-based DICOM conversion
uv pip install dcm2bids        # dcm2bids - config-file-based conversion
# BIDScoin: uv pip install bidscoin

# Useful companions
uv pip install nibabel          # NIfTI/other neuroimaging file I/O
uv pip install pydicom          # DICOM file reading (used by converters)

核心工作流

references/core_workflows.md 中记录了 12 个工作流领域，每个领域都附有完整代码示例：

1. BIDS 目录结构 — 必需的布局，以及每种模态对应的位置。
2. dataset_description.json — 必需字段及其生成方式。
3. 使用 PyBIDS 查询 — BIDSLayout、实体筛选器、支持自动继承的旁车元数据，以及根据实体构建路径。
4. 验证 — 通过 PyPI 包装器（推荐）、直接通过 Deno、使用旧版 Node 验证器运行 bids-validator，以及使用 .bidsignore 排除文件。
5. 实体和文件命名 — 实体顺序和命名语法。
6. 将 DICOM 转换为 BIDS — HeuDiConv（包括一键式 ReproIn 流程，以及侦察 → 启发式规则 → 转换的步骤）和 dcm2bids（基于配置文件）。
7. 元数据旁车文件 — 各模态必需和推荐的 JSON 字段。
8. 事件文件 — 任务 fMRI 事件的时间安排和列约定。
9. 参与者文件 — participants.tsv 及其数据字典。
10. 衍生数据 — 衍生数据布局及其 dataset_description.json。
11. 高级 PyBIDS — 索引缓存（包括衍生数据）、混杂因素回归量和 DataFrame 输出。
12. BIDS-Apps — 标准调用模式，以及 fMRIPrep、MRIQC 和 QSIPrep。

尽早并经常进行验证：PyBIDS 会在为数据集建立索引时验证其结构，因此索引失败通常意味着命名或元数据存在问题，而不是代码错误。

参考资料

此技能包含详细的参考文档：

• bids_schema.json：机器可读的 BIDS 架构（来自 https://bids-specification.readthedocs.io/en/stable/schema.json）。这是实体定义、排序规则、文件名模板、各数据类型允许的后缀以及元数据字段要求的权威来源。BEP 专用架构位于 https://github.com/bids-standard/bids-schema/tree/main/BEPs。
• beps.yml：所有 BIDS 扩展提案的当前列表，包含标题、负责人、状态和链接（来自 bids-website）
• bids_specification.md：以易读形式概述实体表、数据类型参考、目录结构规则、模板空间和规范变更日志
• metadata_fields.md：所有 BIDS 模态（anat、func、dwi、fmap、eeg、meg、pet 等）必需和推荐的 JSON 旁车字段
• conversion_tools.md：HeuDiConv、dcm2bids 和 BIDScoin 的详细工作流，包括启发式规则／配置示例和故障排除

使用以下命令更新架构和 BEP：python scripts/update_schema.py

常见问题与解决方案

1. 验证器报告“Not a BIDS dataset”

原因：根目录中缺少 dataset_description.json。 解决方法：创建该文件，至少包含 {"Name": "...", "BIDSVersion": "1.10.0"}。

2. 受试者不一致警告

原因：并非所有受试者都具有相同的一组文件（有些受试者缺少会话、运行等）。 解决方法：这是警告，不是错误。如果这是有意的，请使用 --ignoreSubjectConsistency。在 participants.tsv 或 scans.tsv 中记录缺失数据。

3. 缺少 SliceTiming

原因：dcm2niix 无法从 DICOM 头文件中提取切片时间信息。 解决方法：根据扫描协议确定切片顺序，并手动添加到 JSON 旁车文件中。常见模式：升序、降序、交错（奇数优先或偶数优先）。

4. 相位编码方向混淆

原因：轴标签（i/j/k 与 x/y/z、LR/AP/SI）容易混淆。 解决方法：在 BIDS 中使用 NIfTI 图像轴：i=第一轴，j=第二轴，k=第三轴。- 表示负方向。对于标准轴位采集：j 通常表示前后方向。请根据采集协议进行确认。

5. PyBIDS 在大型数据集上速度较慢

原因：每次调用 BIDSLayout() 时都会对整个文件系统建立索引。 解决方法：使用 database_path 将索引缓存到 SQLite 文件中：

layout = BIDSLayout("/data", database_path="/data/.pybids_cache.db")

6. PyBIDS 未找到衍生数据

原因：衍生数据目录缺少自己的 dataset_description.json。 解决方法：每个衍生数据目录都必须有 dataset_description.json，其中包含 "DatasetType": "derivative"。

7. 事件文件中的时间不正确

原因：onset 时间所参照的基准不正确（例如，触发时间而不是第一个体积）。 解决方法：Onset 必须以秒为单位，相对于该次采集的第一个体积计算。如果丢弃了虚拟扫描，请将其考虑在内。

8. TSV 文件未通过验证

原因：编码或分隔符问题（使用空格而不是制表符、含有 BOM 字符、使用 Windows 换行符）。 解决方法：确保使用 UTF-8 编码和 Unix 换行符（\n）分隔值。缺失值使用 n/a（不要使用 NA、NaN 或空值）。

最佳实践

1. 尽早并频繁验证 - 每次转换或修改后都运行 BIDS 验证器。在错误累积之前修复它们。

2. 使用元数据继承 - 将共享元数据（例如 TaskName、扫描仪参数）放在顶层附属文件中，而不是在每个受试者的目录中重复。

3. 保留 sourcedata - 将原始 DICOM（或其他原始）数据存储在 sourcedata/ 下，以便转换过程可复现。将 sourcedata/ 添加到 .bidsignore。

4. 从一开始就使用统一命名 - 在数据采集前定义 BIDS 命名方案。对扫描协议使用 ReproIn 命名约定，以便自动转换。

5. 记录数据集信息 - 编写详尽的 README，描述研究设计、采集参数、已知问题以及任何偏离 BIDS 的情况。

6. 使用 scans.tsv 记录运行级元数据 - 记录每次运行的采集时间和质量备注：

   filename	acq_time	quality
   func/sub-01_task-rest_bold.nii.gz	2025-01-15T10:30:00	good
   

7. 对数据集进行版本管理 - 使用 CHANGES 记录数据集修改。对于大型数据集，可考虑使用 DataLad 进行完整的版本控制。

8. 对解剖图像进行面部去标识 - 分享前从 T1w/T2w 图像中移除面部特征（例如使用 pydeface、mri_deface 或 afni_refacer）。将去标识后的版本存储为主要数据，或使用 _defacemask 文件。

9. 使用 BIDS URI 记录来源信息 - 在衍生数据中，使用 BIDS URI 引用源文件：bids::sub-01/anat/sub-01_T1w.nii.gz。

10. 优先使用社区工具 - 尽可能使用成熟的 BIDS-Apps（fMRIPrep、MRIQC、QSIPrep），而不是自定义流水线。它们能正确处理 BIDS 输入/输出，并生成符合 BIDS 规范的衍生数据。

11. 参考 bids-examples - bids-examples 仓库是典型 BIDS 数据集的权威集合，涵盖不同模态和用例（MRI、fMRI、DWI、EEG、MEG、iEEG、PET、ASL、遗传学、衍生数据等）。可将其用作构建自己数据集的参考、BIDS 工具的测试数据，或了解特定模态应如何组织。每个示例均通过了 BIDS 验证器的验证。

BIDS 扩展提案（BEP）

BEP 是由社区推动的提案，旨在将 BIDS 扩展到新的模态、衍生数据或元数据。包含状态、负责人和链接的完整列表见 references/beps.yml（从 bids-website 获取）。BEP 专属的 schema 预览可在 https://github.com/bids-standard/bids-schema/tree/main/BEPs 查看。

当前 BEP（截至 schema 更新）：

BEP	标题	内容	状态
004	磁化率加权成像	原始数据	正在寻找新负责人
011	结构预处理衍生数据	衍生数据	已有 PR（#518）
012	功能预处理衍生数据	衍生数据	已有 PR（#519），schema 已实现
014	仿射变换和非线性场扭曲	衍生数据	X5 格式开发中
016	扩散加权成像衍生数据	衍生数据	已有 PR（#2211）
017	通用 BIDS 连通性数据 schema	衍生数据	开发中
021	通用电生理衍生数据	衍生数据	开发中
023	PET 预处理衍生数据	衍生数据	开发中
024	计算机断层扫描	原始数据	正在寻找贡献者
026	微电极记录	原始数据	正在寻找新负责人
028	溯源信息	元数据	已有 PR（#2099）
032	微电极电生理学	原始数据	已有 PR（#2307），提供预览 — 涵盖 Neuropixels 和其他细胞外探针；与 neuropixels-analysis skill 相关
033	高级扩散加权成像	原始数据	正在寻找贡献者
034	计算建模	衍生数据	已有 PR（#967）
035	使用不合规衍生数据进行大型分析	衍生数据	开发中
036	表型数据指南	原始数据	社区审查中
037	无创脑刺激	原始数据	开发中
039	基于降维的网络	原始数据	开发中
040	功能超声	原始数据	开发中
041	统计模型衍生数据	衍生数据	正在收集反馈
043	BIDS 术语映射	元数据	正在收集反馈
044	刺激材料	原始数据	已有 PR（#2022），社区审查中
045	外周生理记录	原始数据	已有 PR（#2267）
046	扩散纤维束成像	衍生数据	开发中
047	行为实验音频/视频录制	原始数据	已有 PR（#2231）

相关标准：

• BIDS-Stats Models：用于定义基于 GLM 的神经影像分析的 JSON 规范
• BIDS-Derivatives（BEP003）：预处理/分析输出的标准（部分内容已合并到规范中）

相关工具生态

工具	用途
fMRIPrep	fMRI 预处理（生成 BIDS 衍生数据）
MRIQC	MRI 质量控制（生成 BIDS 衍生数据）
QSIPrep	扩散 MRI 预处理
TemplateFlow	采用类似 BIDS 命名方式的神经影像模板和图谱
Fitlins	BIDS Stats Models 实现
DataLad	大型数据集的版本控制，与 BIDS 集成
OpenNeuro	免费的 BIDS 数据集存储库
DANDI	神经生理数据档案（部分模态使用 BIDS）
HeuDiConv	使用启发式 Python 文件将 DICOM 转换为 BIDS
dcm2bids	使用 JSON 配置将 DICOM 转换为 BIDS
BIDScoin	使用 GUI 和 YAML 配置将 DICOM 转换为 BIDS
nwb2bids	将 NWB（Neurodata Without Borders）文件转换为 BIDS
CuBIDS	BIDS 数据集整理与协调
bids2table	对 BIDS 数据集进行高效的表格化索引
bids-examples	涵盖所有模态的典型 BIDS 数据集权威集合

文档

• BIDS 规范：https://bids-specification.readthedocs.io/
• BIDS 网站：https://bids.neuroimaging.io/
• PyBIDS 文档：https://bids-standard.github.io/pybids/
• BIDS 验证器：https://github.com/bids-standard/bids-validator
• BIDS 入门套件：https://bids-standard.github.io/bids-starter-kit/
• BIDS 示例：https://github.com/bids-standard/bids-examples — 涵盖每种 BIDS 模态的规范参考数据集；可用作模板和测试数据
• HeuDiConv 文档：https://heudiconv.readthedocs.io/
• BIDS 原始论文：Gorgolewski 等人（2016），Scientific Data，doi:10.1038/sdata.2016.44