SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场bids

bids

数据与分析

查看项目

更新于 10-21 16:24

技能介绍

用途

BIDS（Brain Imaging Data Structure，脑影像数据结构）是一套社区标准，用于组织和描述神经科学与生物医学研究数据集。它定义了统一的文件命名约定、目录层级和元数据模式，使数据集能够被人和软件工具直接理解。BIDS 由 BIDS 规范（当前 v1.11.x）治理，并通过 BIDS-Standard GitHub 组织由社区维护。

本技能用于在以下场景中应用 BIDS：将原始神经科学数据（影像、电生理、行为）整理为符合 BIDS 的目录结构；查询已有 BIDS 数据集，按受试者、会话、任务、run 或模态定位文件；在共享或提交前依据 BIDS 规范验证数据集；将扫描仪 DICOM 数据转换为 BIDS 格式；编写或编辑 JSON sidecar 元数据文件；创建符合 BIDS 的衍生产物（预处理数据、分析输出）；为新数据集设置 dataset_description.json；处理 BIDS 实体（subject、session、task、acquisition、run 等）；配置 .bidsignore 以在验证时排除文件；为上传至 OpenNeuro、DANDI 或其他支持 BIDS 的仓库准备数据。

主要能力

BIDS 最初面向 MRI，现已远超神经影像范畴，规范覆盖 11 种模态，横跨影像、电生理和行为数据：

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

活跃的 BEP（BIDS 扩展提案）正在进一步扩展 BIDS，尤其是 BEP032（微电极电生理）将增加对细胞外记录（包括 Neuropixels 探针）的支持。

主要数据仓库（OpenNeuro、DANDI）、主要期刊（NeuroImage、Human Brain Mapping、Scientific Data）和资助机构（NIH、ERC）要求或强烈推荐采用 BIDS。

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

使用方式

安装命令：

# 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 中：

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

建议尽早且频繁验证：PyBIDS 在索引数据集时会验证结构，因此索引失败通常意味着命名或元数据问题，而非代码缺陷。

参考材料包括：bids_schema.json（机器可读的 BIDS schema，实体定义、排序规则、文件名模板、各数据类型允许的后缀及元数据字段要求的权威来源）、beps.yml（所有 BIDS 扩展提案的标题、负责人、状态和链接）、bids_specification.md（实体表、数据类型参考、目录结构规则、模板空间和规范变更日志）、metadata_fields.md（每种 BIDS 模态的必需和推荐 JSON sidecar 字段）、conversion_tools.md（HeuDiConv、dcm2bids 和 BIDScoin 的详细工作流，含启发式/配置示例与故障排查）。可用 python scripts/update_schema.py 更新 schema 和 BEP。

适用场景

  • 将原始神经科学数据整理为 BIDS 兼容目录结构
  • 查询已有 BIDS 数据集以定位特定文件
  • 共享或提交前验证数据集
  • 将 DICOM 数据转换为 BIDS 格式
  • 编写或编辑 JSON sidecar 元数据
  • 创建 BIDS 兼容的衍生产物
  • 为新数据集设置 dataset_description.json
  • 处理 BIDS 实体
  • 配置 .bidsignore
  • 为上传 OpenNeuro、DANDI 等仓库准备数据

限制与常见问题

常见问题及解决方案：

  1. 验证器报告 "Not a BIDS dataset"：原因是根目录缺少 dataset_description.json。修复：创建该文件，至少包含 {"Name": "...", "BIDSVersion": "1.10.0"}。
  2. 受试者不一致警告：原因并非所有受试者拥有相同文件集。这是警告而非错误，如属有意可使用 --ignoreSubjectConsistency，并在 participants.tsv 或 scans.tsv 中记录缺失数据。
  3. 缺少 SliceTiming：原因是 dcm2niix 无法从 DICOM 头提取切片时序。修复：从扫描协议确定切片顺序并手动添加到 JSON sidecar。
  4. 相位编码方向混淆：BIDS 中使用 NIfTI 图像轴：i=第一轴，j=第二轴，k=第三轴，- 表示负方向。
  5. PyBIDS 在大数据集上缓慢：使用 database_path 将索引缓存到 SQLite 文件：layout = BIDSLayout("/data", database_path="/data/.pybids_cache.db")。
  6. PyBIDS 找不到衍生产物：每个 derivatives 目录必须有自己的 dataset_description.json，且 "DatasetType": "derivative"。
  7. 事件文件时序偏差：onset 必须相对于该 run 采集的第一个 volume，以秒为单位。
  8. TSV 文件验证失败：确保制表符分隔、UTF-8 编码、Unix 换行（\n），缺失值使用 n/a。

最佳实践：尽早且频繁验证；使用元数据继承；保留 sourcedata 并加入 .bidsignore；从一开始就使用一致命名；撰写详尽 README；使用 scans.tsv 记录 run 级元数据；对数据集进行版本管理；共享前对解剖图像去脸；在衍生产物中使用 BIDS URI 记录来源；优先使用社区工具（fMRIPrep、MRIQC、QSIPrep）；研究 bids-examples 仓库。

相关工具生态包括 fMRIPrep、MRIQC、QSIPrep、TemplateFlow、Fitlins、DataLad、OpenNeuro、DANDI、HeuDiConv、dcm2bids、BIDScoin、nwb2bids、CuBIDS、bids2table、bids-examples。

文档：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）、HeuDiConv Docs（https://heudiconv.readthedocs.io/）。原始 BIDS 论文：Gorgolewski et al. (2016) Scientific Data, doi:10.1038/sdata.2016.44。