BIDS 规范速查实体体系、数据布局与文件命名完整参考【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills面向在 scientific-agent-skills 仓库中处理神经影像数据的开发者与 AI Agent本文系统梳理 BIDSBrain Imaging Data Structure规范的实体Entity体系、各模态数据类型datatype目录、文件扩展名与必需文件、目录结构规则、元数据继承机制、标准模板空间及规范演进历程并对照仓库内置的机器可读权威 schema为组织、校验与查询 BIDS 数据集提供可直接对照的规范速查与深度参考。BIDS 是社区通用的神经科学与生物医学数据组织标准它用一致的命名约定、目录层级与元数据 schema让数据集对人力和软件工具都一眼可懂。在 scientific-agent-skills 仓库中该主题沉淀于 BIDS skill一方面维护了从官方规范导出的机器可读 schema 与人类可读速查文档另一方面配套了 PyBIDS 查询、bids-validator 校验、DICOM 转换等完整实战流程。本文聚焦速查文档 bids_specification.md 所讲解的规范本体并深入对应 schema 源码与测试用例展开讲解让你在整理原始数据、编写 sidecar、构建 derivatives 时能精确命中规范。规范的权威来源与本文使用说明在深入表格之前先明确本仓库内 BIDS 规范相关材料的定位。参考文档开头即强调了一条重要原则canonical权威的、机器可读的规范真值来源是同目录下的bids_schema.json由官方 BIDS Schema 导出。速查文档中的各张表格仅是人类可读摘要当二者不一致时以 schema 为准。对应的权威 schema 位于 skills/bids/references/bids_schema.json从仓库内容看这份 JSON 导出声明了bids_version: 1.11.1与schema_version: 1.2.1顶层结构包含meta如事件文件、ASL 上下文的关联规则、objects实体、后缀、模态等定义、rules实体排序、目录、JSON、表格化数据等规则。也就是说当前速查文档对应的 BIDS 规范版本为1.11.x。schema 与 BEPs 列表并非手工维护而是由维护脚本 update_schema.py 从上游拉取它默认从 BIDS 规范 ReadTheDocs 的schema.jsonstable 发布版下载 schema、从 BIDS 标准组织的 website 仓库拉取beps.yml并以缩进格式重写落地。脚本还支持用--schema-url指定特定规范版本如v1.11.0或指定 BEP 预览 schema如 BEP032配合--skip-beps跳过 BEP 列表更新。其实现细节——下载前校验 JSON、从 payload 解析schema_version/bids_version并打印报告——在仓库测试 tests/bids/test_scripts.py 中有完整覆盖例如测试验证了下载的 schema 会被重新序列化为带缩进的稳定格式、版本号直接来自 payload且beps.yml的 BEP 计数与随附文件的实际行格式保持一致。理解这一层关系后下文所有表格都可以在需要时回溯到 bids_schema.json 求证。实体Entity体系文件名由固定顺序的键值对构成BIDS 文件名的核心机制是entity实体文件名由一组有序的键-值对拼接而成用于编码研究对象、会话、任务、采集参数等语义信息。参考文档给出了完整的实体总表行序即规范要求的文件名顺序——任何 BIDS 文件名中的实体都必须按此顺序排列该顺序由 schema 中的rules.entities定义见bids_schema.json。仓库随附的 bids_schema.json 中rules.entities与objects.entities可交叉印证该顺序与每个实体的name即文件名中的键与format值类型定义。下表完整列出全部 35 个实体及其适用位置#EntityKeyFormatApplies to1Subjectsub-label(alphanumeric)All files (required)2Templatetpl-labelderivatives (template-based)3Sessionses-labelAll datatypes4Cohortcohort-labelderivatives (template cohorts)5Samplesample-labelmicroscopy6Tasktask-labelfunc, eeg, meg, ieeg, beh, pet, nirs, motion7Tracking systemtracksys-labelmotion8Acquisitionacq-labelAll datatypes9Nucleusnuc-labelMR spectroscopy10Volumevoi-labelMR spectroscopy11Contrast enhancing agentce-labelanat12Tracertrc-labelpet13Stainstain-labelmicroscopy14Reconstructionrec-labelanat, func, pet15Directiondir-labelfmap, dwi, perf, func16Runrun-index(integer)All datatypes17Modalitymod-labelfieldmaps18Echoecho-indexfunc, fmap19Flipflip-indexanat (quantitative MRI)20Inversioninv-indexanat (quantitative MRI)21Magnetization transfermt-on/offanat (quantitative MRI)22Partpart-mag/phase/real/imaganat, func23Processingproc-labeleeg, meg, ieeg24Hemispherehemi-L/Rderivatives (surface data)25Spacespace-labelderivatives26Splitsplit-indexfunc, dwi, eeg, meg, ieeg27Recordingrecording-labelphysio, stim, eeg, meg28Chunkchunk-indexlarge files split across chunks29Atlasatlas-labelderivatives (atlas-based)30Segmentationseg-labelderivatives31Scalescale-labelderivatives32Resolutionres-labelderivatives33Densityden-labelderivatives (surface meshes)34Labellabel-labelderivatives (segmentation labels)35Descriptiondesc-labelderivatives only从 schema 印证实体的键与值格式对比 schema 实现可以发现rules.entities中给出的正是上表 1–35 的有序实体名列表subject → template → session → cohort → sample → task → tracksys → acquisition → nucleus → volume → ceagent → tracer → stain → reconstruction → direction → run → modality → echo → flip → inversion → mtransfer → part → processing → hemisphere → space → split → recording → chunk → atlas → segmentation → scale → resolution → density → label → description而objects.entities中每个实体都带有统一为string的type以及区分两种取值语义的formatformat: label——绝大多数实体如sub、ses、task、acq、space、desc取值必须是不含特殊字符的字母数字标签format: index——少数枚举运行序号的实体run、echo、flip、inv、split、chunk取值为数据集内统一补零到等宽的非负整数如run-01、run-02。这正好对应下文实体标签规则中 label 与 index 的区分。值得一提的是schema 中实体名如ceagent、mtransfer与文件名键ce-、mt-并不总是同构这提醒我们写文件名时以name键值为准编程与查询时才使用objects.entities的条目名。常见实体的文件名用法参考文档关联的实战工作流 core_workflows.md 给出了命名文法的一个常用子集与典型示例sub-label[_ses-label][_task-label][_acq-label][_ce-label][_rec-label][_dir-label][_run-index][_echo-index][_part-label][_space-label][_desc-label]_suffix.extension其中方括号表示可选实体。实际应用中sub-用于所有文件ses-用于多会话研究task-用于 func/EEG/MEG 等任务数据acq-用于区分不同采集参数ce-用于增强造影rec-用于重建变体dir-用于场图、DWI 与相位编码方向run-用于重复的相同采集echo-用于多回波序列part-用于幅值/相位拆分space-与desc-则主要出现在 derivatives见后文标准模板空间。实体标签规则Entity Label Rules命名实体时必须遵守以下标签规范Labelslabel仅限字母数字不含特殊字符不允许前导零run-除外Indicesindex非负整数在同一数据集内补零到相同位宽例如run-01、run-02Subject 标签通常为数字01、02但也可以是字母数字CON01、PAT01Session 标签既可以是描述性名称pre、post、baseline、followup也可以是数字Task 标签简短、具描述性、不含空格rest、nback、faces、gonogo。一个直观的反面案例是sub-001与sub-002是合法的等宽补零但若同一数据集同时出现sub-01与sub-001则会破坏补零一致性约定而带下划线、连字符或空格的 label如task-face recognition则直接违反 label 规则会导致校验失败。数据类型Datatypes与顶层目录BIDS 通过顶层目录名区分不同模态的数据类型每种数据类型有固定的文件后缀集合。参考文档给出完整对照表DatatypeDescriptionCommon SuffixesanatStructural MRIT1w,T2w,FLAIR,T2star,inplaneT1,inplaneT2,PDw,T1map,T2map,T1rho,UNIT1,MP2RAGE,MTR,MTSfuncFunctional MRIbold,cbv,sbrefdwiDiffusion-weighted imagingdwi,sbreffmapFieldmapsphasediff,phase1,phase2,magnitude1,magnitude2,fieldmap,epiperfPerfusion imaging (ASL)asl,m0scan,aslcontexteegElectroencephalographyeeg,channels,electrodes,events,coordsystemmegMagnetoencephalographymeg,channels,coordsystem,events,headshapeieegIntracranial EEGieeg,channels,electrodes,events,coordsystempetPositron Emission Tomographypet,bloodmicrMicroscopy2PE,BF,CARS,CONF,DIC,DF,FLUO,MPE,NLO,OCT,PC,PLI,SRS,TLbehBehavioral data (no imaging)events,beh,physio,stimmotionMotion capturemotion,channels,eventsnirsNear-infrared spectroscopynirs,channels,optodes,coordsystem,events从 BIDS skill 总览SKILL.md可知规范覆盖能力远不止 MRI当前已覆盖11 类模态——影像类MRI 的结构/功能/弥散/场图/灌注 ASL、PET、显微成像、电生理类EEG、MEG、iEEG、EMG以及其他类NIRS、动作捕捉、无影像行为数据、MR 波谱。这份速查表中还出现了 MR 波谱使用的nuc-/voi-实体与 motion 专用的tracksys-与实体表一一呼应。值得注意的配套要点同样源自 SKILL.md 与 core_workflows.md每种 datatype 内channels.tsv、events.tsv、electrodes.tsv、coordsystem.json等侧车/配套文件并非可有可无——EEG/MEG/iEEG 数据必需_channels.tsv与_events.tsv见下文必需文件每张 NIfTI 影像都应携带同名的.jsonsidecar存放采集参数等元数据datatype 目录位于 subject或 session目录内部且目录层级关系受到 schemarules.directories的约束。文件扩展名约定不同模态与数据类型使用固定的文件扩展名参考文档给出核心扩展名清单ExtensionDescription.nii.gzCompressed NIfTI (standard for MRI/fMRI/DWI).niiUncompressed NIfTI.jsonJSON sidecar metadata.tsvTab-separated values (events, participants, etc.).bvecb-vectors (DWI gradient directions).bvalb-values (DWI gradient strengths).edfEuropean Data Format (EEG).bdfBioSemi Data Format (EEG).vhdr/.vmrk/.eegBrainVision format (EEG).setEEGLAB format (EEG).fifElekta/MEGIN format (MEG).dsCTF dataset (MEG).sqd/.conKIT/Yokogawa (MEG)结合仓库配套的元数据参考 metadata_fields.md 可以延伸两点工程细节DWI 必须同时具备.bvec与.bval.bvec为 3 行 × N 列N 体素数每列是一个梯度方向.bval为 1 行 × N 列表示每个体素的 b 值。注意两者数值用空格分隔不是制表符列数必须与 NIfTI 体素数一致b0 体素在.bvec中对应零向量.tsv系列文件events、participants、channels、scans 等规范要求制表符分隔、UTF-8 编码、Unix 换行\n缺失值使用n/a而不是NA、NaN或留空——这也是 SKILL.md 中TSV files fail validation一节的修复要点。必需文件清单参考文档将 BIDS 数据集的必需文件按层级与模态组织如下。数据集层级data-level始终必需dataset_description.json这是唯一在所有 BIDS 数据集中严格必需的文件。SKILL.md 指出校验器报 Not a BIDS dataset 的常见原因就是根目录缺失该文件最简修复是创建包含{Name: ..., BIDSVersion: 1.10.0}的文件。在实战工作流中一个完整版通常还包含DatasetTyperaw或derivative、License、Authors、Funding、GeneratedBy等字段完整示例见 core_workflows.md 第 2 节。数据集层级推荐README或README.mdCHANGESparticipants.tsvparticipants.jsonLICENSE其中participants.tsv记录受试者层面的表型数据其每个列的含义由同名participants.json数据字典描述CHANGES用于对数据集进行版本化说明。单次运行层面推荐sub-label/[ses-label/]sub-label[_ses-label]_scans.tsv—— 逐 run 的采集元数据scans.tsv中每一行对应一个文件列出文件名、采集时间acq_time、质量quality等字段是记录漏采、坏数据等逐 run 信息的主要载体。模态相关的必需文件func/bold任务数据需要对应的_events.tsvJSON sidecar 中必须含TaskNamedwi.bvec和.bval文件eeg/meg/ieeg_channels.tsv、_events.tsvperf/asl_aslcontext.tsv。结合 schema 的meta.associations可以看出这类配套文件在规范中是显式建模的例如 schema 中定义了事件文件关联规则events 后缀文件需以.tsv形式存在于对应 BOLD 文件旁、ASL 文件与_aslcontext.tsv、_m0scan的关联规则。也就是说规范不仅能约束单个文件的名字还能表达某类影像必须有配套文件的关系。目录结构规则除命名外BIDS 还规定了严格的目录布局。参考文档列出 8 条核心规则Subject 目录命名为sub-label位于数据集根目录下Session 目录ses-label为可选项一旦使用必须对所有 subject 一致使用Datatype 目录anat/、func/等位于 subject或 session目录内部sourcedata/存放原始未处理数据如 DICOM——不参与校验derivatives/存放处理输出——每个处理流程使用各自独立的子目录code/存放分析脚本stimuli/存放采集期间使用的刺激文件phenotype/存放不依附于特定影像数据的问卷/行为数据。一个最小 BIDS 数据集的完整布局在 core_workflows.md 第 1 节有实例展示my_dataset/ dataset_description.json participants.tsv participants.json README CHANGES .bidsignore sub-01/ anat/ sub-01_T1w.nii.gz sub-01_T1w.json func/ sub-01_task-rest_bold.nii.gz sub-01_task-rest_bold.json sub-01_task-rest_events.tsv dwi/ sub-01_dwi.nii.gz sub-01_dwi.json sub-01_dwi.bvec sub-01_dwi.bval fmap/ sub-01_phasediff.nii.gz sub-01_phasediff.json sub-02/ ses-pre/... ses-post/...其中的工程要点包括NIfTI 文件都应配同名.jsonsidecarsourcedata/与derivatives/位于数据集根层规则 4、5而非 subject 目录内derivatives/内的每个流程目录如fmriprep-24.1.0/必须拥有自己带DatasetType: derivative的dataset_description.json否则 PyBIDS 将无法识别这些处理产物。元数据继承机制Metadata InheritanceBIDS 的 JSON 元数据sidecar遵循从高层目录向低层目录级联继承的原则若同一键出现在多个层级最贴近数据文件的最具体定义优先。参考文档给出的解析顺序优先级从高到低文件级 sidecarsub-01/func/sub-01_task-rest_bold.jsonSubject 级 sidecarsub-01/sub-01_task-rest_bold.json数据集级 sidecartask-rest_bold.json这套机制的价值在于避免重复对全体受试者恒定不变的元数据如RepetitionTime、TaskName只需写一份顶层 sidecar。仓库实战文档给出了对应的目录示例my_dataset/ task-rest_bold.json # 应用于所有 rest BOLD 文件 sub-01/ func/ sub-01_task-rest_bold.json # 仅覆盖/扩展 sub-01在 PyBIDS 中这种继承是自动兑现的调用layout.get_metadata(path)返回的字典已按层级合并完成这正是 BIDS skill 声称PyBIDS 查询 sidecar 元数据时自动执行继承的底层机制。各模态 JSON sidecar 具体字段的要求与推荐值含 R/REC/OPT 状态标注在 metadata_fields.md 中有逐字段明细BOLD 的必需字段是RepetitionTime与TaskNameSliceTiming、PhaseEncodingDirection、TotalReadoutTime等则分别服务于 slice-timing 校正与畸变校正。标准模板空间Standard Template SpacesDerivatives 数据往往需要从个体空间配准到标准模板空间space-label实体即用于声明数据所在空间。参考文档列出常用空间标签Space LabelDescriptionMNI152NLin2009cAsymMNI 2009c nonlinear asymmetric (fMRIPrep default)MNI152NLin6AsymMNI 6th-generation nonlinear asymmetric (FSL default)MNI152LinMNI linear registrationMNIPediatricAsymPediatric MNI templatesT1wIndividual subjects T1w native spacefsnativeFreeSurfer individual surface spacefsaverageFreeSurfer average surface (164k vertices)fsaverage5FreeSurfer average surface (10k vertices)fsaverage6FreeSurfer average surface (40k vertices)fsLRHCP fs_LR surface spaceOASIS30ANTsOASIS-30 ANTs templateUNCInfantUNC infant templates说明这些模板的完整清单由 TemplateFlow 组织统一管理本仓库内仅收录了最常用子集。典型文件名实例如下同时体现了 derivatives 中space-、desc-的组合使用sub-01_space-MNI152NLin2009cAsym_desc-preproc_T1w.nii.gz sub-01_task-rest_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz结合 PyBIDS 查询实践可以用空间标签作为过滤条件精确命中某空间下的预处理产物详见 core_workflows.md 第 10–11 节。规范版本演进Specification ChangelogBIDS 规范通过版本化持续扩展覆盖的模态。参考文档摘录了从 1.0.0 到 1.10.0 的关键演进VersionKey Changes1.10.0Motion capture modality; refined derivative entity rules1.9.0NIRS modality; Python-based validator reference implementation1.8.0Microscopy modality;chunk-entity for large files1.7.0PET modality fully specified1.6.0EEG/MEG/iEEG matured;_coordsystem.json1.5.0Genetic descriptors; ASL perfusion1.4.0dataset_description.jsonexpanded; derivatives framework1.0.0Initial release: MRI only (anat, func, dwi, fmap)从仓库证据看本仓库内 schema 的bids_version为1.11.1即上述 1.10.0 之后的新版本BEP032微电极细胞外电生理覆盖 Neuropixels 探针、BEP012功能像预处理 derivativesschema 已实现等仍在不断并入规范。值得注意的是1.9.0 起的官方参考校验器实现迁移为 Python 生态——对应仓库内推荐使用的bids-validator-denoDeno 参考实现通过 PyPI 封装正是此趋势的体现见 SKILL.md 安装与校验一节。与仓库配套参考的协同使用规范速查文档只是 BIDS skill 的字典。在实际组织与使用 BIDS 数据时建议按如下路径协同查阅本仓库材料先看数据要落在哪类模态——对照本文数据类型表选择顶层目录与后缀结合实体表命名文件名补全必需的 sidecar 与配套文件——对照本文必需文件清单各字段取值细则查 metadata_fields.md运行校验器——安装bids-validator-deno后执行bids-validator /path/to/bids_dataset用.bidsignore排除sourcedata/等非校验内容命令细节见 core_workflows.md 第 4 节用 PyBIDS 查询与索引——BIDSLayout在加载时会顺带做结构校验因此索引失败往往意味着命名或元数据问题而非代码 bug大数据集请加database_path缓存任何歧义以 schema 为准——速查表与 schema 冲突时回溯 bids_schema.json 的rules与objects定义若怀疑 schema 过期可运行python skills/bids/scripts/update_schema.py拉取最新版本该脚本仅依赖标准库。这套速查表格 机器可读 schema 实战代码的组合使 BIDS 规范在数据整理、合规校验与 AI Agent 自动化处理场景中都具备可追溯、可执行的落地路径。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考