腦部影像資料結構 (BIDS) 是做什麼的？
概述
腦部影像資料結構 (Brain Imaging Data Structure, BIDS) 是一個社群標準，用於組織和描述神經科學與生物醫學研究資料集。它定義了一致的檔案命名慣例、目錄層級結構與中繼資料綱要，使得資料集無論對人類還是軟體工具而言都能立即理解。BIDS 由 BIDS 規範（目前為 v1.11.x）管轄，並由社群透過 BIDS-Standard GitHub 組織進行維護。
雖然 BIDS 起源於 MRI，但它已遠遠超出神經影像學範疇。該規範目前涵蓋 11 種模態，橫跨影像學、電生理學和行為資料：
- 影像學：MRI（結構性、功能性、擴散、磁場圖、灌注/ASL）、PET、顯微鏡檢查
- 電生理學：EEG、MEG、iEEG（顱內腦電圖）、EMG
- 其他：NIRS（近紅外光譜學）、動作捕捉、行為資料（不含影像）、MR 頻譜學
正在進行中的 BEP 正在進一步擴展 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 驗證器使用
bids-validator，以及使用.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。
修正：每個衍生資料目錄都必須具有包含 "DatasetType": "derivative" 的 dataset_description.json。
7. 事件檔案時間不對
原因：onset 時間相對於錯誤的參考點（例如，觸發時間 vs. 第一個體積）。
修正：觸發時間必須是相對於該次運行的第一個採集體積的秒數。如果存在被丟棄的虛擬掃描，請將其考慮在內。
8. TSV 檔案驗證失敗
原因：編碼或分隔符號問題（空格代替了定位點、BOM 字元、Windows 換行符號）。
修正：確保使用 Tab 分隔的值、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 輸入/輸出，並產生符合 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 S
...
[為翻譯而截斷]