Brain Imaging Data Structure (BIDS)

Was macht Brain Imaging Data Structure (BIDS)?

Überblick

Die Brain Imaging Data Structure (BIDS) ist ein Community-Standard zur Organisation und Beschreibung neurowissenschaftlicher und biomedizinischer Forschungsdatensätze. Sie definiert eine konsistente Dateibenennungskonvention, eine Verzeichnishierarchie und ein Metadatenschema, sodass Datensätze sowohl für Menschen als auch für Softwarewerkzeuge sofort verständlich sind. BIDS wird durch die BIDS-Spezifikation (aktuell v1.11.x) geregelt und von der Community über die BIDS-Standard GitHub-Organisation gepflegt.

Während BIDS ursprünglich für die MRT entwickelt wurde, ist es inzwischen weit über die Neurobildgebung hinausgewachsen. Die Spezifikation umfasst mittlerweile 11 Modalitäten, die Bildgebung, Elektrophysiologie und Verhaltensdaten abdecken:

• Bildgebung: MRT (strukturell, funktionell, Diffusion, Feldkarten, Perfusion/ASL), PET, Mikroskopie
• Elektrophysiologie: EEG, MEG, iEEG (intrakranielles EEG), EMG
• Andere: NIRS (Nahinfrarotspektroskopie), Motion Capture, Verhaltensdaten (ohne Bildgebung), MR-Spektroskopie

Aktive BEPs erweitern BIDS weiter – insbesondere BEP032 (Mikroelektroden-Elektrophysiologie) wird die Unterstützung für extrazelluläre Ableitungen einschließlich Neuropixels-Sonden hinzufügen und BIDS zu einer verbreiteten Methode in der neurowissenschaftlichen Tierforschung bringen (siehe auch die neuropixels-analysis-Skill).

Die Adoption ist erforderlich oder wird dringend empfohlen von wichtigen Datenrepositorien (OpenNeuro, DANDI), führenden Zeitschriften (NeuroImage, Human Brain Mapping, Scientific Data) und Förderorganisationen (NIH, ERC).

Das Python-Ökosystem für BIDS konzentriert sich auf PyBIDS (pybids) zum Abfragen und Indizieren von BIDS-Datensätzen und den bids-validator (Deno-basiert, erhältlich als PyPI-Paket bids-validator-deno oder direkt über Deno) zur Compliance-Überprüfung. Die Konvertierung von DICOM erfolgt typischerweise mit HeuDiConv, dcm2bids oder BIDScoin.

Wann diese Skill verwendet werden sollte

Wenden Sie diese Skill an, wenn:

• Rohdaten der Neurowissenschaften (Bildgebung, Elektrophysiologie, Verhaltensdaten) in BIDS-konforme Verzeichnisstrukturen organisiert werden
• Ein vorhandener BIDS-Datensatz abgefragt wird, um bestimmte Dateien nach Proband, Sitzung, Aufgabe, Durchlauf oder Modalität zu finden
• Ein Datensatz vor dem Teilen oder Einreichen gegen die BIDS-Spezifikation validiert wird
• DICOM-Daten von Scannern in das BIDS-Format konvertiert werden
• JSON-Seitencar-Metadatendateien geschrieben oder bearbeitet werden
• BIDS-konforme Derivate (vorverarbeitete Daten, Analyseergebnisse) erstellt werden
• Eine dataset_description.json für einen neuen Datensatz eingerichtet wird
• Mit BIDS-Entitäten (Proband, Sitzung, Aufgabe, Akquisition, Durchlauf usw.) gearbeitet wird
• .bidsignore konfiguriert wird, um Dateien von der Validierung auszuschließen
• Daten für den Upload zu OpenNeuro, DANDI oder anderen BIDS-fähigen Repositorien vorbereitet werden

Installation

# Kern-BIDS-Abfragebibliothek
uv pip install pybids

# BIDS-Validator (Deno-basiert, installiert über PyPI-Wrapper)
uv pip install bids-validator-deno
# Alternative: direkt über Deno installieren
# deno install -g -A npm:bids-validator

# DICOM-zu-BIDS-Konverter (nach Bedarf installieren)
uv pip install heudiconv       # HeuDiConv – heuristikbasierte DICOM-Konvertierung
uv pip install dcm2bids        # dcm2bids – konfigurationsdateibasierte Konvertierung
# BIDScoin: uv pip install bidscoin

# Nützliche Begleiter
uv pip install nibabel          # NIfTI/andere neuroimaging Datei-I/O
uv pip install pydicom          # DICOM-Dateilesen (von Konvertern verwendet)

Kern-Workflows

Zwölf Arbeitsbereiche mit ausgearbeitetem Code sind dokumentiert in references/core_workflows.md:

1. BIDS-Verzeichnisstruktur – das erforderliche Layout und wo jede Modalität hingehört.
2. dataset_description.json – die erforderlichen Felder und wie sie generiert werden.
3. Abfragen mit PyBIDS – BIDSLayout, Entitätsfilter, Seitencar-Metadaten mit automatischer Vererbung und Pfaderstellung aus Entitäten.
4. Validierung – bids-validator über den PyPI-Wrapper (empfohlen), über Deno direkt, den Legacy-Node-Validator und Verwendung von .bidsignore zum Ausschluss von Dateien.
5. Entitäten und Dateibenennung – die Entitätsreihenfolge und Benennungsgrammatik.
6. DICOM-zu-BIDS-Konvertierung – HeuDiConv (einschließlich des schlüsselfertigen ReproIn-Pfads und der Sequenz Erkundung → Heuristik → Konvertierung) und dcm2bids (konfigurationsdateibasiert).
7. Metadaten-Seitencars – erforderliche und empfohlene JSON-Felder pro Modalität.
8. Events-Dateien – Task-fMRT-Ereigniszeitsteuerung und Spaltenkonventionen.
9. Teilnehmerdatei – participants.tsv und ihr Datenwörterbuch.
10. Derivate – das Derivate-Layout und seine dataset_description.json.
11. Fortgeschrittene PyBIDS – Index-Caching, Einbeziehung von Derivaten, Confound-Regressoren und DataFrame-Ausgabe.
12. BIDS-Apps – das standardmäßige Aufrufmuster sowie fMRIPrep, MRIQC und QSIPrep.

Validieren Sie früh und oft: PyBIDS validiert die Struktur, wenn es einen Datensatz indiziert, also ist ein Indizierungsfehler normalerweise ein Namens- oder Metadatenproblem und kein Code-Fehler.

Referenzmaterialien

Diese Skill enthält detaillierte Referenzdokumentation:

• bids_schema.json: Maschinenlesbares BIDS-Schema (von https://bids-specification.readthedocs.io/en/stable/schema.json). Dies ist die maßgebliche Quelle für Entitätsdefinitionen, Reihenfolgeregeln, Dateinamensvorlagen, zulässige Suffixe pro Datentyp und Metadatenfeldanforderungen. BEP-spezifische Schemata finden Sie unter https://github.com/bids-standard/bids-schema/tree/main/BEPs.
• beps.yml: Aktuelle Liste aller BIDS Extension Proposals mit Titeln, Leitern, Status und Links (von bids-website)
• bids_specification.md: Für Menschen lesbare Zusammenfassung der Entitätstabelle, Datentypreferenz, Verzeichnisstrukturregeln, Vorlagenräume und Spezifikations-Änderungsprotokoll
• metadata_fields.md: Erforderliche und empfohlene JSON-Seitencar-Felder für jede BIDS-Modalität (anat, func, dwi, fmap, eeg, meg, pet, usw.)
• conversion_tools.md: Detaillierte Workflows für HeuDiConv, dcm2bids und BIDScoin einschließlich Heuristik-/Konfigurationsbeispiele und Fehlerbehebung

Aktualisieren Sie Schema und BEPs mit: python scripts/update_schema.py

Häufige Probleme und Lösungen

1. Validator meldet „Kein BIDS-Datensatz"

Ursache: Fehlende dataset_description.json im Stammverzeichnis. Lösung: Erstellen Sie die Datei mit mindestens {"Name": "...", "BIDSVersion": "1.10.0"}.

2. Warnung zu inkonsistenten Probanden

Ursache: Nicht alle Probanden haben die gleichen Dateien (einige fehlen Sitzungen, Durchläufe, usw.). Lösung: Dies ist eine Warnung, kein Fehler. Verwenden Sie --ignoreSubjectConsistency, wenn dies beabsichtigt ist. Dokumentieren Sie fehlende Daten in participants.tsv oder einer scans.tsv.

3. Fehlende SliceTiming

Ursache: dcm2niix konnte die Schichtzeitsteuerung nicht aus den DICOM-Headern extrahieren. Lösung: Bestimmen Sie die Schichtreihenfolge aus dem Scan-Protokoll und fügen Sie sie manuell zum JSON-Seitencar hinzu. Übliche Muster: aufsteigend, absteigend, verschachtelt (ungerade zuerst oder gerade zuerst).

4. Verwirrung bei der Phasenkodierungsrichtung

Ursache: Achsenbezeichnungen (i/j/k vs. x/y/z vs. LR/AP/SI) sind verwirrend. Lösung: Verwenden Sie in BIDS NIfTI-Bildachsen: i=erste Achse, j=zweite, k=dritte. - bedeutet negative Richtung. Für standardmäßige axiale Aufnahmen: j ist typischerweise anterior-posterior. Überprüfen Sie mit dem Akquisitionsprotokoll.

5. PyBIDS ist langsam bei großen Datensätzen

Ursache: Vollständige Dateisystemindizierung bei jedem BIDSLayout()-Aufruf. Lösung: Verwenden Sie database_path, um den Index in einer SQLite-Datei zu cachen:

layout = BIDSLayout("/data", database_path="/data/.pybids_cache.db")

6. Derivate werden von PyBIDS nicht gefunden

Ursache: Das Derivate-Verzeichnis hat keine eigene dataset_description.json. Lösung: Jedes Derivate-Verzeichnis muss dataset_description.json mit "DatasetType": "derivative" haben.

7. Zeitsteuerung der Events-Datei ist falsch

Ursache: onset-Zeiten beziehen sich auf die falsche Referenz (z. B. Triggerzeit vs. erstes Volumen). Lösung: Onsets müssen in Sekunden relativ zum ersten Volumen dieser Durchlauf-Akquisition sein. Berücksichtigen Sie Dummy-Scans, falls diese verworfen wurden.

8. TSV-Dateien bestehen die Validierung nicht

Ursache: Kodierungs- oder Trennzeichenprobleme (Leerzeichen statt Tabs, BOM-Zeichen, Windows-Zeilenumbrüche). Lösung: Stellen Sie tabulatorgetrennte Werte mit UTF-8-Kodierung und Unix-Zeilenumbrüchen (\n) sicher. Verwenden Sie n/a (nicht NA, NaN oder leer) für fehlende Werte.

Best Practices

1. Validieren Sie früh und oft - Führen Sie den BIDS-Validator nach jeder Konvertierung oder Änderung aus. Beheben Sie Fehler, bevor sie sich häufen.

2. Verwenden Sie Metadatenvererbung - Platzieren Sie gemeinsame Metadaten (z. B. TaskName, Scanner-Parameter) in übergeordneten Seitencar-Dateien, anstatt sie in jedem Probandenverzeichnis zu duplizieren.

3. Behalten Sie Quellendaten - Speichern Sie die ursprünglichen DICOM (oder andere Rohdaten) unter sourcedata/, damit Konvertierungen reproduzierbar sind. Fügen Sie sourcedata/ zu .bidsignore hinzu.

4. Verwenden Sie von Anfang an konsistente Benennung - Definieren Sie Ihr BIDS-Benennungsschema vor der Datenerfassung. Verwenden Sie die ReproIn-Benennungskonvention für Scan-Protokolle, um eine automatische Konvertierung zu ermöglichen.

5. Dokumentieren Sie Ihren Datensatz - Schreiben Sie eine gründliche README, die das Studiendesign, die Akquisitionsparameter, bekannte Probleme und etwaige Abweichungen von BIDS beschreibt.

6. Verwenden Sie scans.tsv für Metadaten auf Durchlaufebene - Zeichnen Sie Akquisitionszeiten und Qualitätsnotizen pro Durchlauf auf:

   filename	acq_time	quality
   func/sub-01_task-rest_bold.nii.gz	2025-01-15T10:30:00	good
   

7. Versionieren Sie Ihren Datensatz - Verwenden Sie CHANGES, um Datensatzänderungen zu dokumentieren. Erwägen Sie DataLad für die vollständige Versionskontrolle großer Datensätze.

8. Entstellen Sie anatomische Bilder - Entfernen Sie Gesichtsmerkmale aus T1w/T2w-Bildern, bevor Sie sie teilen (z. B. mit pydeface, mri_deface oder afni_refacer). Speichern Sie entstellte Versionen als Primärdaten oder verwenden Sie _defacemask-Dateien.

9. Verwenden Sie BIDS-URIs für die Herkunft - Referenzieren Sie in Derivaten Quelldateien mit BIDS-URIs: bids::sub-01/anat/sub-01_T1w.nii.gz.

10. Bevorzugen Sie Community-Tools - Verwenden Sie nach Möglichkeit etablierte BIDS-Apps (fMRIPrep, MRIQC, QSIPrep) anstelle benutzerdefinierter Pipelines. Sie verarbeiten BIDS-I/O korrekt und erzeugen BIDS-konforme Derivate.

11. Studieren Sie bids-examples - Das Repository bids-examples ist die kanonische Sammlung prototypischer BIDS-Datensätze, die verschiedene Modalitäten und Anwendungsfälle abdecken (MRT, fMRT, DWI, EEG, MEG, iEEG, PET, ASL, Genetik, Derivate und mehr). Verwenden Sie es als Referenz beim Strukturieren Ihres eigenen Datensatzes, als Testdaten für BIDS-Tools oder um zu verstehen, wie eine bestimmte Modalität organisiert werden sollte. Jedes Beispiel besteht den BIDS-Validator.

BIDS Extension Proposals (BEPs)

BEPs sind von der Community getriebene Vorschläge zur Erweiterung von BIDS auf neue Modalitäten, Derivate oder Metadaten. Die vollständige Liste mit Status, Leitern und Links befindet sich in references/beps.yml (abgerufen von der bids-website). BEP-spezifische Schema-Vorschauen werden unter https://github.com/bids-standard/bids-schema/tree/main/BEPs gerendert.

Aktuelle BEPs (Stand Schema-Aktualisierung):

BEP	Titel	Inhalt	Status
004	Susceptibility Weighted Imaging	raw	Sucht neuen Leiter
011	Structural preprocessing derivatives	derivative	Hat PR (#518)
012	Functional preprocessing derivatives	derivative	Hat PR (#519), Schema implementiert
014	Affine transforms and nonlinear field warps	derivative	X5-Format-Entwicklung
016	Diffusion weighted imaging derivatives	derivative	Hat PR (#2211)
017	Generic BIDS connectivity data schema	derivative	In Entwicklung
021	Common Electrophysiological Derivatives	derivative	In Entwicklung
023	PET Preprocessing derivatives	derivative	In Entwicklung
024	Computed Tomography scan	raw	Sucht Mitwirkende
026	Microelectrode Recordings	raw	Sucht neuen Leiter
028	Provenance	metadata	Hat PR (#2099)
032	Microelectrode electrophysiology	raw	Hat PR (#2307), Vorschau verfügbar – deckt Neuropixels und andere extrazelluläre Sonden ab; bezieht sich auf neuropixels-analysis-Skill
033	Advanced Diffusion Weighted Imaging	raw	Sucht Mitwirkende
034	Computational modeling	derivative	Hat PR (#967)
035	Mega-analyses with non-compliant derivatives	derivative	In Entwicklung
036	Phenotypic Data Guidelines	raw	Community-Review
037	Non-Invasive Brain Stimulation	raw	In Entwicklung
039	Dimensionality reduction-based networks	raw	In Entwicklung
040	Functional Ultrasound	raw	In Entwicklung
041	Statistical Model Derivatives	derivative	Sammelt Feedback
043	BIDS Term Mapping	metadata	Sammelt Feedback
044	Stimuli	raw	Hat PR (#2022), Community-Review
045	Peripheral Physiological Recordings	raw	Hat PR (#2267)
046	Diffusion Tractography	derivative	In Entwicklung
047	Audio/video recordings for behavioral experiments	raw	Hat PR (#2231)

Verwandte Standards:

• BIDS-Stats Models: JSON-Spezifikation zur Definition von GLM-basierten Neuroimaging-Analysen
• BIDS-Derivatives (BEP003): Standard für vorverarbeitete/Analyse-Ergebnisse (teilweise in die Spezifikation eingeflossen)

Verwandtes Tool-Ökosystem

Tool	Zweck
fMRIPrep	fMRT-Vorverarbeitung (erzeugt BIDS-Derivate)
MRIQC	MRT-Qualitätskontrolle (erzeugt BIDS-Derivate)
QSIPrep	Diffusions-MRT-Vorverarbeitung
TemplateFlow	Neuroimaging-Vorlagen und Atlanten mit BIDS-ähnlicher Benennung
Fitlins	BIDS-Stats-Models-Implementierung
DataLad	Versionskontrolle für große Datensätze, integriert mit BIDS
OpenNeuro	Kostenloses BIDS-Datensatz-Repository
DANDI	Neurophysiologie-Datenarchiv (verwendet BIDS für einige Modalitäten)
HeuDiConv	DICOM-zu-BIDS mit heuristischen Python-Dateien
dcm2bids	DICOM-zu-BIDS mit JSON-Konfiguration
BIDScoin	DICOM-zu-BIDS mit GUI und YAML-Konfiguration
nwb2bids	Konvertiert NWB-Dateien (Neurodata Without Borders) in BIDS
CuBIDS	BIDS-Datensatz-Kuratierung und -Harmonisierung
bids2table	Effiziente tabellarische Indizierung von BIDS-Datensätzen
bids-examples	Kanonische Sammlung prototypischer BIDS-Datensätze für alle Modalitäten

Dokumentation

• BIDS-Spezifikation: https://bids-specification.readthedocs.io
• BIDS-Standard-Website: https://bids-standard.github.io
• BIDS-Validator: https://bids-standard.github.io/bids-validator
• PyBIDS-Dokumentation: https://bids-standard.github.io/pybids
• HeuDiConv-Dokumentation: https://heudiconv.readthedocs.io
• dcm2bids-Dokumentation: https://dcm2bids.readthedocs.io
• BIDScoin-Dokumentation: https://bidscoin.readthedocs.io