脑成像数据结构（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 扩展提案）正在进一步扩展 BIDS——值得注意的 BEP032（微电极电生理学）将增加对包括 Neuropixels 探针在内的细胞外记录的支持，将 BIDS 引入动物神经科学研究中流行的方法学领域（也可参见 neuropixels-analysis 技能）。
主要数据存储库（OpenNeuro、DANDI）、领先期刊（NeuroImage、Human Brain Mapping、Scientific Data）以及资助机构（NIH、ERC）要求或强烈推荐采用 BIDS。
BIDS 的 Python 生态系统主要围绕用于查询和索引 BIDS 数据集的 PyBIDS (pybids)，以及用于合规性检查的 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 的存储库
安装
# 核心 BIDS 查询库
uv pip install pybids
# BIDS 验证器（基于 Deno，通过 PyPI 包装器安装）
uv pip install bids-validator-deno
# 替代方案：直接通过 Deno 安装
# deno install -g -A npm:bids-validator
# DICOM 转 BIDS 转换器（根据需要安装）
uv pip install heudiconv # HeuDiConv - 基于启发式规则的 DICOM 转换
uv pip install dcm2bids # dcm2bids - 基于配置文件的转换
# BIDScoin: uv pip install bidscoin
# 有用的辅助工具
uv pip install nibabel # NIfTI/其他神经影像文件 I/O
uv pip install pydicom # DICOM 文件读取（供转换器使用）
核心工作流程
references/core_workflows.md 文档中记录了两大工作流程，每个都附带现成的代码示例：
- BIDS 目录结构 — 所需的布局以及每种模态应放置的位置。
dataset_description.json— 必需的字段以及如何生成它。- 使用 PyBIDS 查询 —
BIDSLayout、实体过滤器、侧车元数据及其自动继承，以及根据实体构建路径。 - 验证 — 通过 PyPI 包装器（推荐）、直接通过 Deno、传统的 Node 验证器以及使用
.bidsignore排除文件。 - 实体和文件命名 — 实体顺序和命名语法。
- DICOM 到 BIDS 转换 — HeuDiConv（包括一键式 ReproIn 路径以及侦察→启发式→转换序列）和 dcm2bids（基于配置文件）。
- 元数据侧车 — 每种模态的必需和推荐的 JSON 字段。
- 事件文件 — 任务 fMRI 事件时序和列约定。
- 参与者文件 —
participants.tsv及其数据字典。 - 衍生数据 — 衍生数据的布局及其
dataset_description.json。 - 高级 PyBIDS — 索引缓存、包含衍生数据、混淆回归变量以及 DataFrame 输出。
- 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. 验证器报告“不是 BIDS 数据集”
原因：根目录缺少 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 时间相对于错误的参考点（例如，触发时间 vs 第一个卷）。
修复：起始时间必须相对于该运行采集的第一个卷，以秒为单位。如果丢弃了虚拟扫描，请考虑它们。
8. TSV 文件验证失败
原因：编码或分隔符问题（空格代替制表符、BOM 字符、Windows 换行符）。
修复：确保制表符分隔的值采用 UTF-8 编码和 Unix 换行符（\n）。对于缺失值，请使用 n/a（而不是 NA、NaN 或空值）。
最佳实践
-
及早并频繁验证 — 在每次转换或修改后运行 BIDS 验证器。在错误组合之前修复它们。
-
使用元数据继承 — 将共享元数据（例如
TaskName、扫描仪参数）放在顶级侧车文件中，而不是在每个受试者目录中重复。 -
保留源数据 — 将原始 DICOM（或其他原始）数据存储在
sourcedata/下，以便转换可重现。将sourcedata/添加到.bidsignore。 -
从一开始就使用一致的命名 — 在数据收集之前定义 BIDS 命名方案。使用 ReproIn 命名约定来扫描协议，以实现自动转换。
-
记录数据集 — 编写详尽的
README，描述研究设计、采集参数、已知问题以及任何与 BIDS 的偏差。 -
使用 scans.tsv 记录运行级元数据 — 记录每次运行的采集时间和质量说明：
filename acq_time quality
func/sub-01_task-rest_bold.nii.gz 2025-01-15T10:30:00 good
-
版本化数据集 — 使用
CHANGES记录数据集修改。考虑使用 DataLad 对大型数据集进行完整版本控制。 -
去面部解剖图像 — 在共享前从 T1w/T2w 图像中移除面部特征（例如，使用
pydeface、mri_deface或afni_refacer）。将去面部版本存储为主要数据，或使用_defacemask文件。 -
使用 BIDS URI 进行溯源 — 在衍生数据中，使用 BIDS URI 引用源文件：
bids::sub-01/anat/sub-01_T1w.nii.gz。 -
优先使用社区工具 — 尽可能使用成熟的 BIDS-Apps（fMRIPrep、MRIQC、QSIPrep）而不是自定义流程。它们能正确处理 BIDS I/O 并生成符合 BIDS 的衍生数据。
-
研究 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 的模式预览可在 https://github.com/bids-standard/bids-schema/tree/main/BEPs 查看。
当前 BEP（截至模式更新）：
| BEP | 标题 | 内容 | 状态 |
|---|---|---|---|
| 004 | 磁敏感加权成像 | 原始 | 正在寻找新负责人 |
| 011 | 结构预处理衍生数据 | 衍生 | 有 PR (#518) |
| 012 | 功能预处理衍生数据 | 衍生 | 有 PR (#519)，模式已实现 |
| 014 | 仿射变换和非线性场扭曲 | 衍生 | X5 格式开发中 |
| 016 | 弥散加权成像衍生数据 | 衍生 | 有 PR (#2211) |
| 017 | 通用 BIDS 连接数据模式 | 衍生 | 开发中 |
| 021 | 通用电生理学衍生数据 | 衍生 | 开发中 |
| 023 | PET 预处理衍生数据 | 衍生 | 开发中 |
| 024 | 计算机断层扫描 | 原始 | 正在寻找贡献者 |
| 026 | 微电极记录 | 原始 | 正在寻找新负责人 |
| 028 | 溯源 | 元数据 | 有 PR (#2099) |
| 032 | 微电极电生理学 | 原始 | 有 PR (#2307)，预览可用 — 涵盖 Neuropixels 和其他细胞外探针；与 neuropixels-analysis 技能相关 |
| 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（无边界神经数据）文件转换为 BIDS |
| CuBIDS | BIDS 数据集整理和协调 |
| bids2table | BIDS 数据集的高效表格索引 |
| bids-examples | 适用于所有模态的典型 BIDS 数据集的权威集合 |
文档
- BIDS 规范：https://bids-specification.readthedocs.io/en/stable/
- BIDS 网站：https://bids.neuroimaging.io/
- PyBIDS 文档：https://bids-standard.github.io/pybids/
- HeuDiConv 文档：https://heudiconv.readthedocs.io/
- dcm2bids 文档：https://unfmontreal.github.io/Dcm2Bids/
- BIDScoin 文档：https://bidscoin.readthedocs.io/
- bids-validator 文档：https://bids-standard.github.io/bids-validator/