BtToxin Pipeline

Automated Bacillus thuringiensis toxin mining system with CI/CD integration.

Quick Start (单机部署)

uv .venv

uv venv --managed-python -p 3.12 --seed .venv
uv pip install backend/requirements.txt

Prerequisites

• Docker / Podman
• Python 3.10+
• Node.js 18+

Development Setup

# 1. Clone and setup
git clone <your-repo>
cd bttoxin-pipeline

# 2. 使用 Makefile 初始化与启动（单机）
make setup
make start

# 3. 初始化数据库（创建表）
make db-init

# 4. 访问服务
# API:     http://localhost:8000/docs
# Flower:  http://localhost:5555
# Frontend:http://localhost:3000

# (可选) 本地开发
# Backend: uvicorn app.main:app --reload
# Frontend: npm run dev

Architecture

Nginx (Reverse Proxy) ├── Frontend (Vue 3 Static) └── Backend (FastAPI + Swagger) ├── PostgreSQL (SQLModel via SQLAlchemy) ├── Redis (Broker/Result) ├── Celery (Worker/Beat + Flower) └── Docker Engine (BtToxin_Digger)

Documentation

• API 文档: 浏览器打开 http://localhost:8000/docs
• 单机编排: docker/docker-compose.yml（唯一来源）
• 环境变量示例: backend/.env.example
• 常用命令: make help

macOS + Podman 使用注意事项

• Podman 在 macOS 上通过虚拟机运行，宿主目录绑定到容器时，写权限可能受限。
• 我们已在运行逻辑中对 macOS 进行特殊处理：将输入复制到容器内 /tmp/input，在 /tmp 执行 BtToxin_Digger，结束后把 Results/ 与关键输出复制回挂载的 /workspace（宿主输出目录）。
• 如仍遇写入问题：
  • 在 Podman Desktop 的虚拟机共享目录中，添加项目路径并开启写权限。
  • 如需，启用 rootful 模式并重启：podman machine stop && podman machine set --rootful && podman machine start
  • 手动验证挂载：podman run --rm -v $(pwd)/tests/output:/workspace:rw alpine sh -lc 'echo ok > /workspace/test.txt && ls -l /workspace'

本地离线容器测试（可选）

使用 scripts/test_bttoxin_digger.py 最小测试：

uv run python scripts/test_bttoxin_digger.py

要求：tests/test_data 下存在 97-27.fna 与 C15.fna，测试成功后在 tests/output/Results/Toxins 看到 6 个关键文件。

输入文件格式说明

.fna 文件是 FASTA 格式的核酸序列文件，包含细菌的完整基因组序列：

• 97-27.fna: Bacillus thuringiensis strain 97-27 的完整基因组序列
• C15.fna: Bacillus thuringiensis strain C15 的完整基因组序列

文件格式示例：

TAATGTAACACCAGTAAATATTTCATTCATATATTCTTTTAACTGTATTTTATATTCTTTCTACTCTACAATTTCTTTTA
ACTGCCAATATGCATCTTCTAGCCAAGGGTGTAAAACTTTCAACGTGTCTTTTCTATCCCACAAATATGAAATATATGCA
...

挖掘结果解读

BtToxin_Digger 分析完成后会生成以下关键结果文件：

1. 菌株毒素列表文件 (.list)

• 包含每个菌株中预测到的各类毒素蛋白的详细分类信息
• 毒素类型包括：Cry、Cyt、Vip、Others、App、Gpp、Mcf、Mpf、Mpp、Mtx、Pra、Prb、Spp、Tpp、Vpa、Vpb、Xpp
• 每个毒素显示：蛋白ID、长度、等级(Rank1-4)、BLAST结果、最佳匹配、覆盖度、相似度、SVM和HMM预测结果

2. 基因银行格式文件 (.gbk)

• 包含预测毒素基因的详细注释信息
• 记录基因位置、蛋白描述、BLAST比对详情、预测结果等
• 可用于后续的功能分析和可视化

3. 汇总表格 (Bt_all_genes.table)

• 所有菌株的毒素基因汇总表格
• 显示每个菌株中不同类型毒素基因的数量和相似度信息

4. 全部毒素列表 (All_Toxins.txt)

• 包含所有预测到的毒素基因的完整信息
• 字段包括：菌株、蛋白ID、蛋白长度、链向、基因位置、SVM预测、BLAST结果、HMM结果、命中ID、比对长度、一致性、E值等

测试结果示例：

• 97-27菌株预测到12个毒素基因，包括InhA1/2、Bmp1、Spp1Aa1、Zwa5A/6等
• C15菌株预测到多个Cry毒素基因（Cry21Aa2、Cry21Aa3、Cry21Ca2、Cry5Ba1）和其他辅助毒素
• 毒素等级分为Rank1-4，Rank1为最高置信度，Rank4为最低置信度
• 相似度范围从27.62%到100%，表明与已知毒素的相似程度

单目录方案（跨平台稳定写入）

• 运行前，程序会将输入文件复制到宿主输出目录下的 input_files/ 子目录；容器仅挂载该输出目录（读写）为 /workspace。
• 工具运行时的 --SeqPath 指向 /workspace/input_files，工作目录也固定在 /workspace；所有结果与中间文件都会落在宿主的 tests/output/ 下。

目录示例：

tests/output/
├── input_files/          # 输入文件副本
│   ├── 97-27.fna
│   └── C15.fna
├── Results/              # BtToxin_Digger 输出
│   └── Toxins/
│       ├── 97-27.list
│       ├── 97-27.gbk
│       └── ...
├── StatsFiles/           # 统计文件（如有）
├── All_Toxins.txt
└── BtToxin_Digger.log

bttoxin_db更新

BtToxin_Digger 容器内置的数据库版本较旧（2021年8月），建议使用官方 GitHub 仓库的最新数据库。

数据库目录结构

external_dbs/bt_toxin/
├── db/                    # BLAST 索引文件（运行时必需）
│   ├── bt_toxin.phr
│   ├── bt_toxin.pin
│   ├── bt_toxin.psq
│   ├── bt_toxin.pdb
│   ├── bt_toxin.pjs
│   ├── bt_toxin.pot
│   ├── bt_toxin.ptf
│   ├── bt_toxin.pto
│   └── old/
└── seq/                   # 序列源文件（留档/更新用）
    ├── bt_toxin20251104.fas
    └── ...

更新步骤

mkdir -p external_dbs
rm -rf external_dbs/bt_toxin tmp_bttoxin_repo

git clone --filter=blob:none --no-checkout https://github.com/liaochenlanruo/BtToxin_Digger.git tmp_bttoxin_repo
cd tmp_bttoxin_repo

git sparse-checkout init --cone
git sparse-checkout set BTTCMP_db/bt_toxin
git checkout master

# 把目录拷贝到你的项目 external_dbs 下
cd ..
cp -a tmp_bttoxin_repo/BTTCMP_db/bt_toxin external_dbs/bt_toxin

# 清理临时 repo
rm -rf tmp_bttoxin_repo

验证数据库绑定

# 检查数据库文件是否完整
ls -lh external_dbs/bt_toxin/db/

# 验证容器能正确访问绑定的数据库
docker run --rm \
  -v "$(pwd)/external_dbs/bt_toxin:/usr/local/bin/BTTCMP_db/bt_toxin:ro" \
  quay.io/biocontainers/bttoxin_digger:1.0.10--hdfd78af_0 \
  bash -lc 'ls -lh /usr/local/bin/BTTCMP_db/bt_toxin/db | head'

输出应显示 .pin/.psq/.phr 等文件，且时间戳/大小与宿主机一致，说明绑定成功。

使用外部数据库运行 Pipeline

脚本会自动检测 external_dbs/bt_toxin 目录，若存在则自动绑定：

# 自动使用 external_dbs/bt_toxin（推荐）
uv run python scripts/run_single_fna_pipeline.py --fna tests/test_data/HAN055.fna

# 或手动指定数据库路径
uv run python scripts/run_single_fna_pipeline.py \
  --fna tests/test_data/HAN055.fna \
  --bttoxin_db_dir /path/to/custom/bt_toxin

注意事项

• db/ 目录是必需的：运行时 BLAST 只读取 db/ 下的索引文件
• seq/ 目录是可选的：仅用于留档或重新生成索引
• 绑定模式为只读 (ro)：防止容器意外修改宿主机数据库
• 不需要重新 index：GitHub 仓库已包含预构建的 BLAST 索引

License

MIT License