bids

脑成像数据结构 (BIDS)

概述

脑成像数据结构 (BIDS) 是一项社区标准，用于组织和描述神经科学与生物医学研究数据集。它定义了统一的文件命名约定、目录层级和元数据模式，使数据集能够被人类和软件工具直接理解。BIDS 由 BIDS 规范（依据 2026-09-29 发布的 v1.11.2 审核）管理，并由社区通过 BIDS-Standard GitHub 组织维护。

虽然 BIDS 最初为 MRI 而创建，但其应用已远远超出神经影像领域。该规范目前涵盖 11 种模态，横跨成像、电生理和行为数据：

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

正在推进的 BEP 正在进一步扩展 BIDS —— 尤其是 BEP032（微电极电生理）提出支持包括 Neuropixels 探针在内的细胞外记录，将 BIDS 带入动物神经科学研究中的一种主流方法（另见 neuropixels-analysis 技能）。

各模态和归档库的仓库提交要求各不相同；准备上传前请先查阅目标归档库的要求。

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 -ERWN -g -n bids-validator jsr:@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 中：

1. BIDS 目录结构 — 必需的目录布局以及每种模态应放置的位置。
2. dataset_description.json — 必需字段以及如何生成它。
3. 使用 PyBIDS 查询 — BIDSLayout、实体过滤器、具有自动继承的 sidecar 元数据，以及从实体构建路径。
4. 验证 — 通过 PyPI 封装使用 bids-validator（推荐）、直接通过 Deno 使用、旧版 Node 验证器，以及使用 .bidsignore 排除文件。
5. 实体与文件命名 — 实体顺序和命名语法。
6. DICOM 到 BIDS 转换 — HeuDiConv（包括开箱即用的 ReproIn 路径以及 reconnaissance → heuristic → convert 序列）和 dcm2bids（基于配置文件）。
7. 元数据 sidecar — 每种模态必需和推荐的 JSON 字段。
8. 事件文件 — 任务 fMRI 事件时序和列约定。
9. 参与者文件 — participants.tsv 及其数据字典。
10. 衍生数据 — 衍生数据布局及其 dataset_description.json。
11. 高级 PyBIDS — 索引缓存，包括衍生数据、混杂回归量和 DataFrame 输出。
12. BIDS-Apps — 标准调用模式，以及 fMRIPrep、MRIQC 和 QSIPrep。

使用 BIDS 验证器进行验证，并使用 PyBIDS 进行索引。成功索引并不等于完整的合规性检查；请记录验证器和 BIDS schema 版本，并在分析前检查警告和元数据继承情况。

参考资料

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

• bids_schema.json：机器可读的 BIDS schema（来自 https://bids-specification.readthedocs.io/en/stable/schema.json）。这是实体定义、排序规则、文件名模板、每种数据类型允许的后缀以及元数据字段要求的权威来源。BEP 专用 schema 位于 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 sidecar 字段
• conversion_tools.md：HeuDiConv、dcm2bids 和 BIDScoin 的详细工作流，包括 heuristic/config 示例和故障排除

在技能目录中，使用 python scripts/update_schema.py 更新 schema 和 BEP。捆绑的快照为 BIDS 1.11.2 / schema 2.0.0；BEP 提案并非已采纳的要求。 如果 ReadTheDocs 阻止自动抓取，请使用更新器帮助中记录的带版本号的 GitHub 导出。

常见问题与解决方案

1. 验证器报告 "Not a BIDS dataset"

原因：根目录缺少 dataset_description.json。 修复：创建该文件，至少包含 {"Name": "...", "BIDSVersion": "1.11.2"}。

2. 受试者不一致警告

原因：并非所有受试者都拥有相同的文件集（部分缺少 session、run 等）。 修复：在验证器 JSON 报告中查看严重程度和确切的问题代码，并在 participants.tsv 或 scans.tsv 中记录缺失数据。当前 schema 验证器不提供旧版的 --ignoreSubjectConsistency 标志；仅对经过审查的例外情况使用范围狭窄的 --config。

3. 缺少 SliceTiming

原因：dcm2niix 无法从 DICOM 头信息中提取切片时间。 修复：从扫描仪元数据或经过验证的序列协议中恢复实际的切片采集偏移量。仅凭切片顺序无法确定时间，尤其是在多频带采集或存在死区时间的情况下。按切片索引顺序以秒为单位存储偏移量，并考虑 SliceEncodingDirection；记录缺失的时间信息，而不是凭空捏造。

4. 相位编码方向混淆

原因：轴标签（i/j/k 与 x/y/z 与 LR/AP/SI）容易混淆。 修复：在 BIDS 中，使用 NIfTI 图像轴：i=第一轴，j=第二轴，k=第三轴。- 表示负方向。解剖方向取决于 NIfTI 仿射矩阵和转换器方向；不要仅凭 AP/PA 序列标签推断 j 或其符号。请对照扫描仪元数据和图像方向进行验证。

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

原因：每次调用 BIDSLayout() 都会进行完整的文件系统索引。 修复：使用 database_path 将索引缓存到数据集之外的目录中：

layout = BIDSLayout("/data", database_path="/cache/pybids")
# After dataset changes, rebuild with reset_database=True.

6. PyBIDS 找不到衍生产物

原因：衍生产物目录缺少自己的 dataset_description.json。 修复：每个衍生产物目录都必须包含 dataset_description.json，其中带有 "DatasetType": "derivative"。

7. 事件文件时间偏移有误

原因：onset 时间相对于错误的参考点（例如，触发时间与第一个体积）。 修复：Onset 是相对于相应记录中第一个存储数据点的秒数。如果在存储前丢弃了虚拟体积，请将时间零点重置为第一个保留的体积；允许负的 onset 值。

8. TSV 文件未通过验证

原因：编码或分隔符问题（用空格代替制表符、BOM 字符）。 修复：确保使用制表符分隔的值、UTF-8 编码和 Unix 换行符（\n）。缺失值请使用 n/a（而不是 NA、NaN 或空值）。

最佳实践

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

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

3. 保留 sourcedata - 将源 DICOM 和转换溯源信息保存在受控存储中；sourcedata/ 不参与原始 BIDS 验证，但并未去标识化。在任何共享之前检查标识符。

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

5. 为数据集编写文档 - 编写一份详尽的 README，描述研究设计、采集参数、已知问题以及与 BIDS 的任何偏差。

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

   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:raw:sub-01/anat/sub-01_T1w.nii.gz，并在衍生数据根目录为 raw/derivatives/pipeline/ 时定义 "DatasetLinks": {"raw": "../.."}。bids:: 在当前数据集内解析，而在衍生数据集中就是该衍生数据集。

10. 优先使用社区工具 - 尽可能使用成熟的 BIDS-App（fMRIPrep、MRIQC、QSIPrep），而不是自定义流程。检查所选发布版本支持的输入和输出约定；软件输出仍需要验证。

11. 研究 bids-examples - bids-examples 仓库是原型 BIDS 数据集的权威集合，涵盖不同模态和用例（MRI、fMRI、DWI、EEG、MEG、iEEG、PET、ASL、遗传学、衍生数据等）。在构建自己的数据集时将其作为参考，作为 BIDS 工具的测试数据，或用于了解某个特定模态应如何组织。固定示例修订版本以及验证器/schema 版本；随着实现的演进，上游测试套件也会跟踪预期失败。

BIDS 扩展提案 (BEP)

BEP 是由社区驱动的提案，用于将 BIDS 扩展到新的模态、衍生数据或元数据。包含状态、负责人和链接的完整列表位于 references/beps.yml（从 bids-website 获取）。针对特定 BEP 的 schema 预览渲染于 https://github.com/bids-standard/bids-schema/tree/main/BEPs。

随附的 BEP 列表已于 2026-09-30 刷新。在使用草稿实体之前，请阅读每个条目的提案/PR 和状态；BEP032 仍是一项提案，不属于稳定版 1.11.2 的一部分。使用仓库目录列表来发现预览 schema 路径；不要假设存在 BEPs/BEP032/schema.json URL。

相关标准：

• 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 Specification: https://bids-specification.readthedocs.io/
• BIDS Website: https://bids.neuroimaging.io/
• PyBIDS Documentation: https://bids-standard.github.io/pybids/
• BIDS Validator: https://github.com/bids-standard/bids-validator
• BIDS Starter Kit: https://bids-standard.github.io/bids-starter-kit/
• BIDS Examples: https://github.com/bids-standard/bids-examples — 每种 BIDS 模态的标准参考数据集；可用作模板和测试数据
• HeuDiConv Docs: https://heudiconv.readthedocs.io/
• Original BIDS paper: Gorgolewski et al. (2016) Scientific Data, doi:10.1038/sdata.2016.44