뇌 영상 데이터 구조 (BIDS)
개요
뇌 영상 데이터 구조(BIDS)는 신경과학 및 생체의학 연구 데이터셋을 구성하고 설명하기 위한 커뮤니티 표준입니다. 일관된 파일 명명 규칙, 디렉토리 계층 구조 및 메타데이터 스키마를 정의하여 데이터셋이 인간과 소프트웨어 도구 모두에게 즉시 이해될 수 있도록 합니다. BIDS는 BIDS 사양(현재 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를 위한 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-to-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 파일 읽기(변환기에서 사용)
핵심 워크플로우
12가지 워크플로우 영역 각각에 대한 작업 코드는 references/core_workflows.md에 문서화되어 있습니다:
- BIDS 디렉토리 구조 — 필수 레이아웃과 각 양식이 속한 위치.
dataset_description.json— 필수 필드 및 생성 방법.- PyBIDS로 쿼리 —
BIDSLayout, 엔티티 필터, 자동 상속이 포함된 사이드카 메타데이터, 엔티티에서 경로 구축. - 검증 — PyPI 래퍼(권장), Deno 직접 사용, 레거시 Node 검증기,
.bidsignore를 사용한 파일 제외를 통한bids-validator. - 엔티티 및 파일 명명 — 엔티티 순서 및 명명 문법.
- 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 vs x/y/z vs 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 시간이 잘못된 기준(예: 트리거 시간 대 첫 번째 볼륨)을 기준으로 함.
해결 방법: 온셋은 해당 실행의 첫 번째 볼륨을 기준으로 초 단위여야 합니다. 더미 스캔이 폐기된 경우 이를 고려하십시오.
8. TSV 파일 검증 실패
원인: 인코딩 또는 구분 기호 문제(탭 대신 공백, BOM 문자, Windows 줄 끝).
해결 방법: UTF-8 인코딩 및 Unix 줄 끝(\n)으로 탭으로 구분된 값을 사용하십시오. 누락된 값에는 n/a(NA, NaN 또는 빈 값 아님)를 사용하십시오.
모범 사례
-
초기에 자주 검증하십시오 - 모든 변환 또는 수정 후 BIDS 검증기를 실행하십시오. 오류가 누적되기 전에 수정하십시오.
-
메타데이터 상속을 사용하십시오 - 각 피험자 디렉토리에 중복하는 대신 공유 메타데이터(예:
TaskName, 스캐너 매개변수)를 최상위 사이드카 파일에 배치하십시오. -
소스 데이터를 보관하십시오 - 변환을 재현할 수 있도록 원본 DICOM(또는 기타 원시) 데이터를
sourcedata/아래에 저장하십시오.sourcedata/를.bidsignore에 추가하십시오. -
처음부터 일관된 명명을 사용하십시오 - 데이터 수집 전에 BIDS 명명 체계를 정의하십시오. 자동 변환을 활성화하려면 스캔 프로토콜에 ReproIn 명명 규칙을 사용하십시오.
-
데이터셋을 문서화하십시오 - 연구 설계, 획득 매개변수, 알려진 문제 및 BIDS와의 모든 편차를 설명하는 철저한
README를 작성하십시오. -
실행 수준 메타데이터에 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 I/O를 올바르게 처리하고 BIDS 호환 파생물을 생성합니다.
-
bids-examples를 연구하십시오 - bids-examples 저장소는 다양한 양식 및 사용 사례(MRI, fMRI, DWI, EEG, MEG, iEEG, PET, ASL, 유전체학, 파생물 등)를 포괄하는 프로토타입 BIDS 데이터셋의 표준 컬렉션입니다. 자체 데이터셋을 구성할 때 참고 자료로 사용하거나, 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-to-BIDS |
| dcm2bids | JSON 구성을 사용한 DICOM-to-BIDS |
| BIDScoin | GUI 및 YAML 구성을 사용한 DICOM-to-BIDS |
| nwb2bids | NWB(Neurodata Without Borders) 파일을 BIDS로 변환 |
| CuBIDS | BIDS 데이터셋 큐레이션 및 조화 |
| bids2table | BIDS 데이터셋의 효율적인 테이블 형식 인덱싱 |
| bids-examples | 모든 양식에 대한 프로토타입 BIDS 데이터셋의 표준 컬렉션 |
문서
- BIDS 사양: https://bids-specification.readthedocs.io
- PyBIDS 문서: https://bids-standard.github.io/pybids
- bids-validator: https://github.com/bids-standard/bids-validator
- HeuDiConv: https://heudiconv.readthedocs.io
- dcm2bids: https://github.com/UNFmontreal/Dcm2Bids
- BIDScoin: https://github.com/Donders-Institute/bidscoin
- BIDS 확장 제안: https://bids.neuroimaging.io/bep
- BIDS-Apps: https://bids-apps.neuroimaging.io
- TemplateFlow: https://www.templateflow.org
- bids-examples: https://github.com/bids-standard/bids-examples
참여하기
이 스킬에 기여하려면:
- 리포지토리를 포크하고 변경 사항으로 PR을 제출하십시오.
- BIDS 사양 확장에 대한 논의는 BIDS-Standard를 참조하십시오.
- 버그 신고 또는 기능 요청은 BIDS-Discuss 포럼을 사용하십시오.
이 스킬의 인라인 참조 문서는 가장 일반적인 신경과학 데이터 구성 작업을 다루지만, 모든 BIDS 모드와 엣지 케이스에 대한 전체 사양을 대체하지는 않습니다. 전체 BIDS 설명서를 보려면 https://bids-specification.readthedocs.io를 참조하십시오.