bids

脳画像データ構造（BIDS）

概要

脳画像データ構造（BIDS）は、神経科学および生物医学研究のデータセットを整理・記述するためのコミュニティ標準です。一貫したファイル命名規則、ディレクトリ階層、メタデータスキーマを定めているため、データセットを人間にもソフトウェアツールにもすぐに理解できるようにします。BIDSはBIDS Specification（現在は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の採用が必須、または強く推奨されています。

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エンティティ（subject、session、task、acquisition、runなど）を扱う
• 検証対象からファイルを除外するために.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)

コアワークフロー

12 のワークフロー領域について、コード例とともに references/core_workflows.md に記載しています。

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=第 1 軸、j=第 2 軸、k=第 3 軸です。- は負の方向を意味します。標準的な軸位断の撮像では、通常 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 の時刻が誤った基準（例：トリガー時刻と最初のボリューム）を参照しています。 対処法：オンセットは、各ランの撮像における最初のボリュームを基準とした秒単位で記録する必要があります。ダミースキャンが破棄されている場合は、その分を考慮してください。

8. TSV ファイルの検証に失敗する

原因：エンコーディングまたは区切り文字の問題（タブではなくスペース、BOM 文字、Windows の改行コードなど）。 対処法：UTF-8 エンコーディングと Unix の改行コード（\n）を使用したタブ区切りの値であることを確認してください。欠損値には n/a（NA、NaN、空欄ではありません）を使用してください。

ベストプラクティス

1. 早い段階から頻繁に検証する - 変換や変更のたびに BIDS validator を実行してください。エラーが積み重なる前に修正してください。

2. メタデータの継承を使用する - 共通のメタデータ（例：TaskName、スキャナーのパラメーター）は、各被験者のディレクトリに重複して配置するのではなく、トップレベルのサイドカーファイルに配置してください。

3. sourcedata を保持する - 変換を再現できるよう、元の DICOM（またはその他の生データ）を sourcedata/ の下に保存してください。.bidsignore に sourcedata/ を追加してください。

4. 最初から一貫した命名規則を使用する - データ収集の前に BIDS の命名規則を定義してください。自動変換を可能にするため、スキャンプロトコルには ReproIn の命名規則を使用してください。

5. データセットを文書化する - 研究デザイン、撮像パラメーター、既知の問題、BIDS からの逸脱について詳しく説明する README を作成してください。

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 リポジトリは、さまざまなモダリティや用途（MRI、fMRI、DWI、EEG、MEG、iEEG、PET、ASL、遺伝学、派生データなど）を網羅した、典型的な BIDS データセットの標準的なコレクションです。独自のデータセットを構成する際の参考資料として、BIDS ツールのテストデータとして、また特定のモダリティの整理方法を理解するために活用してください。各サンプルは BIDS validator に合格しています。

BIDS 拡張提案（BEP）

BEP は、BIDS を新しいモダリティ、派生データ、メタデータに拡張するための、コミュニティ主導の提案です。ステータス、リード担当者、リンクを含む一覧は references/beps.yml にあります（bids-website から取得）。BEP 固有のスキーマプレビューは https://github.com/bids-standard/bids-schema/tree/main/BEPs に表示されます。

現在の BEP（スキーマ更新時点）：

BEP	タイトル	内容	ステータス
004	磁化率強調画像	raw	新しいリーダーを募集中
011	構造画像の前処理派生データ	derivative	PR あり（#518）
012	機能画像の前処理派生データ	derivative	PR あり（#519）、スキーマ実装済み
014	アフィン変換と非線形フィールドワープ	derivative	X5 形式を開発中
016	拡散強調画像の派生データ	derivative	PR あり（#2211）
017	汎用 BIDS 接続データスキーマ	derivative	開発中
021	共通電気生理派生データ	derivative	開発中
023	PET 前処理派生データ	derivative	開発中
024	コンピューター断層撮影スキャン	raw	貢献者を募集中
026	微小電極記録	raw	新しいリーダーを募集中
028	来歴	metadata	PR あり（#2099）
032	微小電極電気生理学	raw	PR あり（#2307）、プレビュー利用可能 — Neuropixels などの細胞外プローブを対象とし、neuropixels-analysis スキルに関連
033	高度な拡散強調画像	raw	貢献者を募集中
034	計算モデリング	derivative	PR あり（#967）
035	非準拠の派生データによるメガ解析	derivative	開発中
036	表現型データガイドライン	raw	コミュニティレビュー中
037	非侵襲的脳刺激	raw	開発中
039	次元削減に基づくネットワーク	raw	開発中
040	機能的超音波	raw	開発中
041	統計モデル派生データ	derivative	フィードバックを募集中
043	BIDS 用語マッピング	metadata	フィードバックを募集中
044	刺激	raw	PR あり（#2022）、コミュニティレビュー中
045	末梢生理記録	raw	PR あり（#2267）
046	拡散トラクトグラフィー	derivative	開発中
047	行動実験の音声／動画記録	raw	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 et al.（2016）Scientific Data、doi:10.1038/sdata.2016.44