bids/example

Example BIDS App 镜像文档

镜像概述

Example BIDS App 是一个遵循 BIDS (Brain Imaging Data Structure) 标准的示例应用镜像，旨在演示 BIDS App 的构建规范、数据处理流程及开发最佳实践。该镜像提供了基础的 BIDS 应用框架，帮助开发者直观理解如何构建符合 BIDS 规范的神经影像数据处理工具。

核心功能与特性

• BIDS 标准兼容：严格遵循 BIDS App 1.0+ 规范，支持标准 BIDS 格式数据输入与验证
• 完整流程演示：包含从数据校验、预处理到结果生成的端到端示例流程
• 灵活配置机制：提供多维度参数配置示例，支持自定义处理逻辑
• 轻量级设计：基于 Alpine 基础镜像构建，体积精简，资源占用低
• 文档化示例：内置使用说明与开发注释，便于学习和二次开发

使用场景与适用范围

• BIDS App 开发入门：帮助新手开发者理解 BIDS App 的目录结构、参数规范和执行流程
• 教学与培训：用于学术或企业培训，演示 BIDS 标准在实际应用中的落地方式
• 开发模板：可作为基础框架快速扩展，构建自定义神经影像数据处理工具
• 兼容性测试：验证 BIDS 格式数据集的规范性和处理流程可行性

使用方法

前提条件

• Docker Engine 20.10+
• 符合 BIDS 标准的数据集（推荐使用 https://github.com/bids-standard/bids-examples%EF%BC%89

基础运行命令

bash
docker run --rm \
  -v /local/bids/dataset:/data:ro \
  -v /local/output:/output \
  docker.xuanyuan.run/example-bids-app /data /output participant

参数说明：

• /local/bids/dataset：本地 BIDS 数据集路径（需通过 BIDS Validator 验证）
• /local/output：本地输出目录（用于存储处理结果）
• participant：处理级别（BIDS App 标准参数，可选 participant 或 group）

高级配置

通过环境变量自定义处理参数：

bash
docker run --rm \
  -v /local/bids/dataset:/data:ro \
  -v /local/output:/output \
  -e SUBJECT_ID=001 \
  -e SESSION=01 \
  -e PROCESSING_MODE=quick \
  -e THREADS=4 \
  docker.xuanyuan.run/example-bids-app /data /output participant --participant_label 001

支持的环境变量：

Docker Compose 配置

创建 docker-compose.yml：

yaml
version: '3.8'
services:
  bids-processing:
    image: docker.xuanyuan.run/example-bids-app
    volumes:
      - ./bids-data:/data:ro
      - ./results:/output
    environment:
      - SUBJECT_ID=001
      - PROCESSING_MODE=quick
      - THREADS=4
    command: /data /output participant --participant_label 001

启动服务：

bash
docker-compose up

注意事项

1. 数据集挂载必须使用 :ro 权限（只读），避免意外修改原始数据
2. 输出目录需确保有写入权限，建议使用本地目录而非 Docker ***卷
3. 大规模数据处理时，通过 THREADS 变量调整并行数，避免资源耗尽
4. 处理前建议使用 https://bids-standard.github.io/bids-validator/ 验证数据集规范性

相关资源

• https://bids-specification.readthedocs.io/
• BIDS App 官方指南
• https://github.com/bids-standard/bids-validator