kundajelab/chrombpnet

chromBPNet Docker镜像文档

1. 镜像概述和主要用途

chromBPNet Docker镜像是一个预配置的生物信息学工具容器，封装了用于染色质可及性分析的深度学习模型——chromBPNet。该模型基于偏置分解（bias factorized）架构，以碱基分辨率（base-resolution）预测和解释染色质可及性信号，核心解决传统分析中技术偏置与生物信号混淆的问题，适用于ATAC-seq、DNase-seq等染色质可及性数据的深度解析。

2. 核心功能与特性

2.1 偏置分解架构

通过分离序列内在偏置（如DNA剪切偏好）和生物信号（如转录因子结合），提高染色质可及性预测的准确性和可解释性。

2.2 碱基分辨率预测

以单碱基精度输出染色质可及性得分，支持高分辨率的基因组区域分析（如转录因子结合位点、增强子核心区域）。

2.3 深度学习模型

基于卷积神经网络（CNN）和注意力机制设计，支持从原始DNA序列和实验数据中学习特征，兼容多种染色质可及性测序数据格式。

2.4 多场景适配

内置预训练模型，支持模型微调（fine-tuning），可针对特定细胞类型、组织或实验条件优化预测性能。

3. 使用场景与适用范围

3.1 研究领域

• 表观遗传学：分析染色质开放区域的调控机制
• 基因组学：预测和解释转录因子结合位点、增强子/启动子活性
• 计算生物学：建模染色质可及性数据中的技术偏置（如Tn5转座酶偏好）

3.2 目标用户

• 生物信息学研究者
• 计算生物学家
• 表观遗传实验团队（需基础Linux命令操作能力）

3.3 典型应用场景

• 从ATAC-seq数据中区分生物信号与技术偏置
• 预测未测序细胞类型的染色质可及性图谱
• 解释非编码区变异（如eQTL、GWAS位点）的表观遗传机制
• 验证转录因子结合 motif 的功能显著性

4. 使用方法和配置说明

4.1 获取镜像

从容器 registry 拉取镜像（假设镜像托管于 ghcr.io）：

bash
docker pull ghcr.io/kundajelab/chrombpnet:latest

4.2 基本运行命令

4.2.1 核心分析流程（预测染色质可及性）

bash
docker run -it --rm \
  -v /path/to/local/data:/data \  # 挂载本地数据目录（含输入文件和输出路径）
  -v /path/to/genome/fasta:/genome \  # 挂载参考基因组FASTA文件（如hg38、mm10）
  ghcr.io/kundajelab/chrombpnet:latest \
  chrombpnet predict \
    --input /data/input_regions.bed \  # 输入BED文件（待分析的基因组区域）
    --genome /genome/hg38.fa \  # 参考基因组FASTA路径
    --model /opt/chrombpnet/models/pretrained_hg38 \  # 预训练模型路径（容器内默认路径）
    --output /data/prediction_results/ \  # 输出目录（挂载的本地路径）
    --batch-size 32 \  # 批处理大小（根据硬件调整）
    --cuda  # 若宿主机有GPU且支持CUDA，添加此参数启用GPU加速

4.2.2 模型微调（针对自定义数据）

bash
docker run -it --rm \
  -v /path/to/training_data:/train \  # 挂载训练数据（含BED、FASTA、峰值文件）
  -v /path/to/output_models:/models \  # 挂载模型输出目录
  ghcr.io/kundajelab/chrombpnet:latest \
  chrombpnet train \
    --train-data /train/train_data.h5 \  # 训练数据（HDF5格式，含输入序列和可及性标签）
    --val-data /train/val_data.h5 \  # 验证数据
    --genome /genome/hg38.fa \
    --initial-model /opt/chrombpnet/models/pretrained_hg38 \  # 初始预训练模型
    --output-dir /models/custom_model \  # 微调后模型保存路径
    --epochs 50 \  # 训练轮数
    --learning-rate 1e-4  # 学习率

4.3 配置说明

4.3.1 输入数据格式

• 区域文件：BED格式（chr, start, end），定义待分析的基因组区域
• 参考基因组：FASTA格式（需含索引文件 .fai，与FASTA同目录）
• 训练数据：HDF5格式，需包含 sequence（one-hot编码DNA序列）、target（可及性信号）字段

4.3.2 核心参数说明

4.4 Docker Compose配置示例

适用于需要持久化数据和模型的场景，创建 docker-compose.yml：

yaml
version: '3'
services:
  chrombpnet:
    image: ghcr.io/kundajelab/chrombpnet:latest
    volumes:
      - ./local_data:/data  # 本地数据目录（输入/输出）
      - ./genome:/genome    # 参考基因组目录
      - ./models:/opt/chrombpnet/models  # 自定义模型目录（覆盖默认预训练模型）
    command: >
      chrombpnet predict
        --input /data/regions.bed
        --genome /genome/hg38.fa
        --model /opt/chrombpnet/models/custom_pretrained
        --output /data/results
        --cuda
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1  # 使用1块GPU
              capabilities: [gpu]

运行命令：docker-compose up

5. 环境变量说明

容器支持通过环境变量配置默认参数，优先级低于命令行参数：

6. 注意事项

1. 数据预处理：输入BED区域建议控制长度在100-1000bp（模型最优输入范围），过长区域需拆分
2. 硬件要求：CPU模式适合小批量数据（<10k区域），大规模分析需GPU支持（建议显存≥12GB）
3. 输出文件：预测结果包含 .bigWig（信号轨道）和 .bed（峰值调用结果），位于 --output 指定目录
4. 模型更新：通过挂载自定义模型目录（如 ./models:/opt/chrombpnet/models）可替换默认预训练模型

6. 总结

chromBPNet Docker镜像为染色质可及性的深度解析提供了便捷工具，通过偏置分解和碱基分辨率预测，助力研究者从表观遗传数据中高效提取生物信号。容器化设计简化了环境配置，适用于各类基因组学研究场景。