bids

Brain Imaging Data Structure (BIDS)

概要

Brain Imaging Data Structure (BIDS) は、神経科学および生物医学研究のデータセットを整理・記述するためのコミュニティ標準です。一貫したファイル命名規則、ディレクトリ階層、メタデータスキーマを定義しており、データセットが人間にとってもソフトウェアツールにとっても即座に理解できるようになります。BIDS は BIDS Specification（v1.11.2、2026-09-29 リリースに対してレビュー済み）によって管理されており、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 エコシステムは、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 対応リポジトリにアップロードするためのデータを準備する場合

インストール

# 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)

コアワークフロー

12 のワークフロー領域があり、それぞれに実践的なコード例が付いています。詳細は references/core_workflows.md に記載されています。

1. BIDS ディレクトリ構造 — 必須のレイアウトと、各モダリティがどこに属するか。
2. dataset_description.json — 必須フィールドとその生成方法。
3. PyBIDS によるクエリ — BIDSLayout、エンティティフィルター、自動継承を伴うサイドカー メタデータ、エンティティからのパス構築。
4. 検証 — PyPI ラッパー経由の bids-validator（推奨）、Deno を直接使う方法、 レガシーな Node バリデーター、そしてファイルを除外するための .bidsignore の使用。
5. エンティティとファイル命名 — エンティティの順序と命名文法。
6. DICOM から BIDS への変換 — HeuDiConv（ターンキーな ReproIn パスと、 reconnaissance → heuristic → convert の一連の流れを含む）および dcm2bids（設定ファイルベース）。
7. メタデータサイドカー — モダリティごとの必須および推奨の JSON フィールド。
8. イベントファイル — タスク fMRI のイベントタイミングと列の規約。
9. 参加者ファイル — participants.tsv とそのデータディクショナリ。
10. 派生データ — 派生データのレイアウトとその dataset_description.json。
11. 高度な PyBIDS — インデックスのキャッシュ、派生データの包含、交絡回帰変数、そして DataFrame 出力。
12. BIDS-Apps — 標準的な呼び出しパターン、および fMRIPrep、MRIQC、QSIPrep。

BIDS バリデーターによる検証と、PyBIDS によるインデックス作成の両方を行ってください。インデックス 作成の成功は完全な準拠チェックではありません。バリデーターと BIDS スキーマのバージョンを記録し、 解析前に警告とメタデータの継承を確認してください。

参考資料

このスキルには詳細な参考ドキュメントが含まれています。

• 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 Extension Proposal の現在の一覧（タイトル、リード、ステータス、リンク付き）（bids-website より）
• bids_specification.md: エンティティテーブル、データタイプリファレンス、ディレクトリ構造の規則、テンプレート空間、仕様の変更履歴を人間が読める形でまとめたもの
• metadata_fields.md: すべての BIDS モダリティ（anat、func、dwi、fmap、eeg、meg、pet など）における必須および推奨の JSON サイドカーフィールド
• conversion_tools.md: HeuDiConv、dcm2bids、BIDScoin の詳細なワークフロー（heuristic/config の例とトラブルシューティングを含む）

スキルディレクトリから、python scripts/update_schema.py でスキーマと 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. 被験者が一貫していないという警告

原因: すべての被験者が同じファイルセットを持っているわけではない（一部にセッション、ランなどが欠けている）。 修正: バリデーターの JSON レポートで重大度と正確な問題コードを確認し、欠落しているデータを participants.tsv または scans.tsv に記録します。現在のスキーマバリデーターはレガシーな --ignoreSubjectConsistency フラグを提供していません。レビュー済みの例外に限り、範囲を絞った --config を使用してください。

3. SliceTiming が欠落している

原因: dcm2niix が DICOM ヘッダーからスライスタイミングを抽出できませんでした。 修正: スキャナーのメタデータまたは検証済みのシーケンスプロトコルから、実際のスライス取得オフセットを復元します。スライス順序だけでは、特にマルチバンド取得やデッドタイムがある場合、タイミングを決定できません。オフセットは秒単位でスライスインデックス順に保存し、SliceEncodingDirection を考慮します。存在しないタイミングをでっち上げず、欠落していることを文書化します。

4. 位相エンコード方向の混同

原因: 軸ラベル (i/j/k と x/y/z と LR/AP/SI) が紛らわしいです。 修正: BIDS では NIfTI 画像の軸を使用します: i=第1軸、j=第2軸、k=第3軸。- は負の方向を意味します。解剖学的な方向は 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 が derivatives を見つけられない

原因: derivatives ディレクトリに独自の dataset_description.json がありません。 修正: すべての derivatives ディレクトリには、"DatasetType": "derivative" を含む dataset_description.json が必要です。

7. イベントファイルのタイミングがずれている

原因: onset 時間が誤った基準 (例: トリガー時刻と最初のボリューム) に対する相対値になっています。 修正: onset は、対応する記録に保存された最初のデータポイントを基準とした秒数です。保存前にダミーボリュームが破棄された場合は、時間ゼロを保持された最初のボリュームにリセットします。負の onset も許可されます。

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

原因: エンコーディングまたは区切り文字の問題 (タブの代わりにスペース、BOM 文字)。 修正: UTF-8 エンコーディングと Unix 改行 (\n) によるタブ区切り値を確保します。欠損値には n/a (NA、NaN、または空ではなく) を使用します。

ベストプラクティス

1. 早い段階で頻繁に検証する - 変換または変更のたびに BIDS バリデータを実行してください。エラーは積み重なる前に修正しましょう。

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

3. sourcedata を保持する - 元の DICOM と変換の来歴を管理されたストレージに保存してください。sourcedata/ は raw BIDS の検証から除外されますが、匿名化されるわけではありません。共有する前に識別子を確認してください。

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

5. データセットを文書化する - 研究デザイン、取得パラメータ、既知の問題、BIDS からの逸脱を記述した徹底的な README を作成してください。

6. run レベルのメタデータには scans.tsv を使用する - 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 を使用する - 派生データでは、raw ソースに bids:raw:sub-01/anat/sub-01_T1w.nii.gz を使用し、派生データのルートが raw/derivatives/pipeline/ の場合は "DatasetLinks": {"raw": "../.."} を定義してください。bids:: は現在のデータセット内で解決され、派生データセットではそれが派生データセットとなります。

10. コミュニティツールを優先する - 可能な場合は、独自のパイプラインではなく、確立された BIDS-Apps（fMRIPrep、MRIQC、QSIPrep）を使用してください。選択したリリースでサポートされる入力と出力の規約を確認してください。ソフトウェアの出力にも検証が必要です。

11. bids-examples を学ぶ - bids-examples リポジトリは、さまざまなモダリティとユースケース（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 リストは 2026-09-30 に更新されました。ドラフトエンティティを使用する前に、各エントリの提案/PR と ステータスを確認してください。BEP032 は提案のままであり、安定版 1.11.2 には含まれていません。 プレビュースキーマのパスを発見するにはリポジトリのディレクトリ一覧を使用してください。 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