hotwa
1c0e8f90a5
- docker_client.py: run_bttoxin_digger() 新增 bttoxin_db_dir 参数，支持挂载外部数据库 - run_single_fna_pipeline.py: 新增 --bttoxin_db_dir 参数，自动检测 external_dbs/bt_toxin - README.md: 添加 bttoxin_db 更新说明和 Docker 绑定文档 - external_dbs/bt_toxin: 添加 2025-11-04 版本数据库文件 测试验证: HAN055 样本毒素命名版本号变化 (Cry2Aa9→22, Cry2Ab35→41, Cry1Ia40→42, Vip3Aa7→79)
226 lines
7.4 KiB
Markdown
226 lines
7.4 KiB
Markdown
# BtToxin Pipeline
|
||
|
||
Automated Bacillus thuringiensis toxin mining system with CI/CD integration.
|
||
|
||
## Quick Start (单机部署)
|
||
|
||
### uv .venv
|
||
|
||
```bash
|
||
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
|
||
```bash
|
||
# 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` 最小测试：
|
||
|
||
```bash
|
||
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 的完整基因组序列
|
||
|
||
文件格式示例：
|
||
```>NZ_CP010088.1 Bacillus thuringiensis strain 97-27 chromosome, complete genome
|
||
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
|
||
└── ...
|
||
```
|
||
|
||
### 更新步骤
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
### 验证数据库绑定
|
||
|
||
```bash
|
||
# 检查数据库文件是否完整
|
||
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` 目录，若存在则自动绑定：
|
||
|
||
```bash
|
||
# 自动使用 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
|