e44692600c
- Docker: - Explicitly install pixi environments (digger, pipeline, webbackend) during build to prevent runtime network/DNS failures. - Optimize pnpm config (copy method) to fix EAGAIN errors. - Backend: - Refactor ZIP bundling: use flat semantic directories (1_Toxin_Mining, etc.). - Fix "nested zip" issue by cleaning existing archives before bundling. - Exclude raw 'context' directory from final download. - Frontend: - Update TutorialView documentation to match new result structure. - Improve TaskMonitor progress bar precision (1 decimal place). - Update i18n (en/zh) for new file descriptions. Co-Authored-By: Claude <noreply@anthropic.com>
460 lines
12 KiB
Markdown
460 lines
12 KiB
Markdown
# BtToxin Pipeline
|
||
|
||
基于 pixi 管理环境的苏云金芽孢杆菌（Bacillus thuringiensis）毒素自动挖掘系统。
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- [pixi](https://pixi.sh) - 现代 conda 环境包管理器
|
||
- Linux x86_64 (linux-64 平台)
|
||
|
||
### 安装
|
||
|
||
1. 安装 pixi（如果尚未安装）：
|
||
|
||
```bash
|
||
# Linux/macOS
|
||
curl -fsSL https://pixi.sh/install.sh | bash
|
||
|
||
# 或通过 Homebrew
|
||
brew install pixi
|
||
```
|
||
|
||
2. 克隆并设置项目：
|
||
|
||
```bash
|
||
git clone <your-repo>
|
||
cd bttoxin-pipeline
|
||
|
||
# 安装所有环境（digger + pipeline）
|
||
pixi install
|
||
```
|
||
|
||
这将创建两个独立的环境：
|
||
- `digger`：BtToxin_Digger 及 bioconda 依赖（perl、blast 等）
|
||
- `pipeline`：Python 分析工具（pandas、matplotlib、seaborn）
|
||
|
||
### 运行管道
|
||
|
||
#### 完整管道（推荐）
|
||
|
||
使用单个命令运行完整的分析管道：
|
||
|
||
```bash
|
||
pixi run pipeline --fna tests/test_data/HAN055.fna
|
||
```
|
||
|
||
这将执行三个阶段：
|
||
1. **Digger**：BtToxin_Digger 毒素挖掘
|
||
2. **Shotter**：毒素评分和靶标预测
|
||
3. **Plot**：热图生成和报告创建
|
||
|
||
#### CLI 选项
|
||
|
||
```bash
|
||
pixi run pipeline --fna <file> [options]
|
||
|
||
选项：
|
||
--fna PATH 输入 .fna 文件（必需）
|
||
--out_root PATH 输出目录（默认：runs/<stem>_run）
|
||
--toxicity_csv PATH 毒性数据 CSV（默认：Data/toxicity-data.csv）
|
||
--min_identity FLOAT 最小相似度阈值 0-1（默认：0.0）
|
||
--min_coverage FLOAT 最小覆盖率阈值 0-1（默认：0.0）
|
||
--disallow_unknown_families 排除未知毒素家族
|
||
--require_index_hit 只保留已知特异性的比对结果
|
||
--lang {zh,en} 报告语言（默认：zh）
|
||
--bttoxin_db_dir PATH 自定义 bt_toxin 数据库目录
|
||
--threads INT 线程数（默认：4）
|
||
```
|
||
|
||
#### 示例
|
||
|
||
```bash
|
||
# 使用默认设置的基础运行
|
||
pixi run pipeline --fna tests/test_data/C15.fna
|
||
|
||
# 严格筛选高置信度结果
|
||
pixi run pipeline --fna tests/test_data/HAN055.fna \
|
||
--min_identity 0.50 --min_coverage 0.60 \
|
||
--disallow_unknown_families --require_index_hit
|
||
|
||
# 英文报告，自定义输出目录
|
||
pixi run pipeline --fna tests/test_data/HAN055.fna \
|
||
--out_root runs/HAN055_strict --lang en
|
||
|
||
# 使用自定义数据库
|
||
pixi run pipeline --fna tests/test_data/HAN055.fna \
|
||
--bttoxin_db_dir /path/to/custom/bt_toxin
|
||
```
|
||
|
||
#### 单独阶段命令
|
||
|
||
根据需要分别运行各个阶段：
|
||
|
||
##### 仅运行 Digger
|
||
|
||
```bash
|
||
pixi run digger-only --fna <file> [options]
|
||
|
||
选项：
|
||
--fna PATH 输入 .fna 文件（必需）
|
||
--out_dir PATH 输出目录（默认：runs/<stem>_digger_only）
|
||
--bttoxin_db_dir PATH 自定义数据库目录
|
||
--threads INT 线程数（默认：4）
|
||
--sequence_type 序列类型：nucl/orfs/prot/reads（默认：nucl）
|
||
```
|
||
|
||
示例：
|
||
```bash
|
||
pixi run digger-only --fna tests/test_data/C15.fna --threads 8
|
||
```
|
||
|
||
##### Shotter（评分）
|
||
|
||
```bash
|
||
pixi run shotter [options]
|
||
|
||
选项：
|
||
--toxicity_csv PATH 毒性数据 CSV
|
||
--all_toxins PATH Digger 输出的 All_Toxins.txt
|
||
--output_dir PATH 输出目录
|
||
--min_identity FLOAT 最小相似度阈值
|
||
--min_coverage FLOAT 最小覆盖率阈值
|
||
--allow_unknown_families / --disallow_unknown_families
|
||
--require_index_hit 只保留索引命中的结果
|
||
```
|
||
|
||
示例：
|
||
```bash
|
||
pixi run shotter \
|
||
--all_toxins runs/C15_run/digger/Results/Toxins/All_Toxins.txt \
|
||
--output_dir runs/C15_run/shotter
|
||
```
|
||
|
||
##### Plot（可视化）
|
||
|
||
```bash
|
||
pixi run plot [options]
|
||
|
||
选项：
|
||
--strain_scores PATH Shotter 输出的 strain_target_scores.tsv
|
||
--toxin_support PATH toxin_support.tsv（可选）
|
||
--species_scores PATH strain_target_species_scores.tsv（可选）
|
||
--out_dir PATH 输出目录
|
||
--cmap STRING 颜色映射（默认：viridis）
|
||
--per_hit_strain NAME 为特定菌株生成逐个毒素热图
|
||
--merge_unresolved 将其他/未知合并到未解决类别
|
||
--report_mode {summary,paper} 报告样式（默认：paper）
|
||
--lang {zh,en} 报告语言（默认：zh）
|
||
```
|
||
|
||
示例：
|
||
```bash
|
||
pixi run plot \
|
||
--strain_scores runs/C15_run/shotter/strain_target_scores.tsv \
|
||
--toxin_support runs/C15_run/shotter/toxin_support.tsv \
|
||
--out_dir runs/C15_run/shotter \
|
||
--per_hit_strain C15 --lang en
|
||
```
|
||
|
||
## 输出结构
|
||
|
||
运行管道后：
|
||
|
||
```
|
||
runs/<strain>_run/
|
||
├── stage/ # 分阶段输入文件
|
||
│ └── <strain>.fna
|
||
├── digger/ # BtToxin_Digger 输出
|
||
│ ├── Results/
|
||
│ │ └── Toxins/
|
||
│ │ ├── All_Toxins.txt
|
||
│ │ ├── <strain>.list
|
||
│ │ ├── <strain>.gbk
|
||
│ │ └── Bt_all_genes.table
|
||
│ └── BtToxin_Digger.log
|
||
├── shotter/ # Shotter 输出
|
||
│ ├── strain_target_scores.tsv
|
||
│ ├── strain_scores.json
|
||
│ ├── toxin_support.tsv
|
||
│ ├── strain_target_species_scores.tsv
|
||
│ ├── strain_species_scores.json
|
||
│ ├── strain_target_scores.png
|
||
│ ├── strain_target_species_scores.png
|
||
│ ├── per_hit_<strain>.png
|
||
│ └── shotter_report_paper.md
|
||
├── logs/
|
||
│ └── digger_execution.log
|
||
└── pipeline_results.tar.gz # 打包结果
|
||
```
|
||
|
||
## 数据库更新
|
||
|
||
BtToxin_Digger 的内置数据库可能已过时。请使用 GitHub 上的最新版本：
|
||
|
||
### 更新步骤
|
||
|
||
```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
|
||
|
||
cd ..
|
||
cp -a tmp_bttoxin_repo/BTTCMP_db/bt_toxin external_dbs/bt_toxin
|
||
rm -rf tmp_bttoxin_repo
|
||
```
|
||
|
||
如果存在 `external_dbs/bt_toxin`，管道会自动检测它。
|
||
|
||
### 数据库结构
|
||
|
||
```
|
||
external_dbs/bt_toxin/
|
||
├── db/ # BLAST 索引文件（必需）
|
||
│ ├── bt_toxin.phr
|
||
│ ├── bt_toxin.pin
|
||
│ ├── bt_toxin.ps
|
||
│ └── ...
|
||
└── seq/ # 源序列（可选，用于参考）
|
||
└── bt_toxin*.fas
|
||
```
|
||
|
||
## 输入文件格式
|
||
|
||
`.fna` 文件是 FASTA 格式的核酸序列文件，包含细菌基因组序列：
|
||
|
||
```
|
||
>NZ_CP010088.1 Bacillus thuringiensis strain 97-27 chromosome, complete genome
|
||
TAATGTAACACCAGTAAATATTTCATTCATATATTCTTTTAACTGTATTTTATATTCTTTCTACTCTACAATTTCTTTTA
|
||
ACTGCCAATATGCATCTTCTAGCCAAGGGTGTAAAACTTTCAACGTGTCTTTTCTATCCCACAAATATGAAATATATGCA
|
||
...
|
||
```
|
||
|
||
## 结果解读
|
||
|
||
### 关键输出文件
|
||
|
||
**All_Toxins.txt** - 完整毒素预测结果，包含：
|
||
- 菌株、蛋白质 ID、坐标
|
||
- SVM/BLAST/HMM 预测结果
|
||
- 命中 ID、比对长度、相似度、E 值
|
||
|
||
**strain_target_scores.tsv** - 菌株级别靶标预测：
|
||
- TopOrder：最可能的靶标昆虫目
|
||
- TopScore：置信度分数（0-1）
|
||
- 所有目标目的逐目分数
|
||
|
||
**toxin_support.tsv** - 逐个毒素贡献详情：
|
||
- 单个毒素权重和贡献度
|
||
- 家族分类和配对状态
|
||
|
||
### 毒素排名
|
||
|
||
- **Rank1**：最高置信度（相似度 ≥78%，覆盖率 ≥80%）
|
||
- **Rank2-3**：中等置信度
|
||
- **Rank4**：最低置信度预测
|
||
|
||
### 目标目
|
||
|
||
预测中常见的昆虫目：
|
||
- **Lepidoptera（鳞翅目）**：蛾类和蝴蝶
|
||
- **Coleoptera（鞘翅目）**：甲虫
|
||
- **Diptera（双翅目）**：苍蝇和蚊子
|
||
- **Hemiptera（半翅目）**：真正的蝽类
|
||
- **Nematoda（线虫纲）**：蛔虫
|
||
|
||
## Web 界面（可选）
|
||
|
||
BtToxin Pipeline 提供可选的 Web 界面，方便任务提交和监控。
|
||
|
||
### 快速启动
|
||
|
||
```bash
|
||
# 同时启动前端和后端服务（推荐）
|
||
pixi run web-start
|
||
|
||
# 前端：http://localhost:5173
|
||
# 后端：http://localhost:8000
|
||
```
|
||
|
||
或者分别启动服务：
|
||
|
||
```bash
|
||
# 终端 1：启动后端
|
||
pixi run api-dev
|
||
|
||
# 终端 2：启动前端
|
||
pixi run fe-dev
|
||
```
|
||
|
||
### 使用 Web 界面
|
||
|
||
1. 在浏览器中打开 http://localhost:5173
|
||
2. 上传 .fna 基因组文件
|
||
3. 配置分析参数（可选）
|
||
4. 点击"提交任务"
|
||
5. 页面将跳转到 `/<task_id>` 页面
|
||
6. 页面每 3 秒轮询一次状态
|
||
7. 完成后下载结果文件（.tar.gz）
|
||
|
||
### 任务链接
|
||
|
||
提交后，您的任务链接为：
|
||
```
|
||
http://localhost:5173/<task_id>
|
||
```
|
||
|
||
请保存此链接以便后续查看结果。结果保留 **30 天**。
|
||
|
||
### 结果存储
|
||
|
||
任务结果存储在 `/data/jobs/{task_id}/` 目录下：
|
||
- `input.fna` - 您上传的文件
|
||
- `params.json` - 任务参数
|
||
- `output/` - 管道输出文件
|
||
- `pipeline_results.tar.gz` - 可下载的结果包
|
||
|
||
### 结果保留期限
|
||
|
||
结果将在 **30 天**后自动删除以释放存储空间。请在过期前下载重要结果。
|
||
|
||
### Python 开发环境
|
||
|
||
对于 pixi 之外的开发工作：
|
||
|
||
```bash
|
||
uv venv --managed-python -p 3.12 --seed .venv
|
||
source .venv/bin/activate
|
||
uv pip install -e .
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行管道的属性测试
|
||
pixi run -e pipeline python -m pytest tests/test_pixi_runner.py -v
|
||
|
||
# 运行前端测试
|
||
pixi run fe-test
|
||
|
||
# 运行后端测试
|
||
pixi run api-test
|
||
```
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
bttoxin-pipeline/
|
||
├── pixi.toml # Pixi 环境配置
|
||
├── pyproject.toml # Python 包配置
|
||
├── scripts/ # 核心管道脚本
|
||
│ ├── run_single_fna_pipeline.py # 主管道编排器
|
||
│ ├── run_digger_stage.py # 仅 Digger 阶段
|
||
│ ├── bttoxin_shoter.py # 毒素评分模块
|
||
│ ├── plot_shotter.py # 可视化和报告
|
||
│ └── pixi_runner.py # PixiRunner 类
|
||
├── bttoxin/ # Python 包（CLI 入口点）
|
||
│ ├── __init__.py
|
||
│ ├── api.py
|
||
│ └── cli.py
|
||
├── Data/ # 参考数据
|
||
│ └── toxicity-data.csv # BPPRC 特异性数据
|
||
├── external_dbs/ # 外部数据库（可选）
|
||
│ └── bt_toxin/ # 更新后的 BtToxin 数据库
|
||
├── tests/ # 测试套件
|
||
│ ├── test_pixi_runner.py # 属性测试
|
||
│ └── test_data/ # 测试输入文件
|
||
├── docs/ # 文档
|
||
├── runs/ # 管道输出（被 git 忽略）
|
||
├── backend/ # FastAPI 后端（可选的 Web 服务）
|
||
└── frontend/ # Vue.js 前端（可选的 Web UI）
|
||
```
|
||
|
||
## Docker 部署
|
||
|
||
适用于生产环境部署或无需安装 pixi/conda 的快速启动：
|
||
|
||
```bash
|
||
# 1. 构建并启动服务
|
||
docker compose -f docker/compose/docker-compose.simple.yml up -d
|
||
|
||
# 2. 访问服务
|
||
# 前端页面: http://localhost
|
||
# 后端 API: http://localhost/api/docs
|
||
```
|
||
|
||
Docker 部署采用单容器模式，使用 Nginx 同时托管前端静态资源和反向代理后端 API。
|
||
|
||
**可用的 Docker 配置文件：**
|
||
- `docker/compose/docker-compose.yml` - 完整配置，包含多种部署选项
|
||
- `docker/compose/docker-compose.simple.yml` - 简单单容器部署（推荐用于快速启动）
|
||
- `docker/compose/docker-compose.traefik.yml` - 基于 Traefik 的生产环境部署
|
||
- `docker/compose/docker-compose.test.yml` - 测试配置
|
||
|
||
**数据挂载：**
|
||
- `./jobs`: 持久化任务数据
|
||
- `./Data`: 参考数据库
|
||
|
||
详细的 Docker 部署信息请参阅 [DOCKER_DEPLOYMENT.md](DOCKER_DEPLOYMENT.md)
|
||
|
||
### 手动构建镜像
|
||
|
||
若要手动构建镜像，请确保设置正确的构建上下文（build context），以便 Docker 能找到 `pixi.toml`。
|
||
|
||
```bash
|
||
# 选项 1：从项目根目录（指定上下文）
|
||
docker build \
|
||
--network=host \
|
||
-f web/zly/docker/dockerfiles/Dockerfile.traefik \
|
||
-t hotwa/bttoxin-app:latest \
|
||
web/zly
|
||
|
||
# 选项 2：先进入目录
|
||
cd web/zly
|
||
docker build \
|
||
--network=host \
|
||
-f docker/dockerfiles/Dockerfile.traefik \
|
||
-t hotwa/bttoxin-app:latest \
|
||
.
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 找不到 pixi
|
||
|
||
```bash
|
||
# 确保 pixi 在 PATH 中
|
||
export PATH="$HOME/.pixi/bin:$PATH"
|
||
|
||
# 或重新安装
|
||
curl -fsSL https://pixi.sh/install.sh | bash
|
||
```
|
||
|
||
### 环境未找到
|
||
|
||
```bash
|
||
# 重新安装环境
|
||
pixi install
|
||
```
|
||
|
||
### BtToxin_Digger 不可用
|
||
|
||
```bash
|
||
# 验证 digger 环境
|
||
pixi run -e digger BtToxin_Digger --help
|
||
```
|
||
|
||
### 权限错误
|
||
|
||
确保输出目录有写权限。管道会自动创建目录。
|
||
|
||
## 许可证
|
||
|
||
MIT License |