hotwa
4c9a7d0978
- 新增 README_CN.md 中文文档 - 新增 frontend/ Vue 3 前端项目 - 新增 web/ FastAPI 后端项目 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
394 lines
10 KiB
Markdown
394 lines
10 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（线虫纲）**：蛔虫
|
||
|
||
## 开发
|
||
|
||
### 前端开发
|
||
|
||
前端是位于 `frontend/` 的 Vue 3 + Vite + Element Plus 应用程序。
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pixi run fe-install
|
||
|
||
# 启动开发服务器（http://localhost:5173）
|
||
pixi run fe-dev
|
||
|
||
# 构建生产版本
|
||
pixi run fe-build
|
||
|
||
# 运行单元测试
|
||
pixi run fe-test
|
||
|
||
# 代码检查和修复
|
||
pixi run fe-lint
|
||
```
|
||
|
||
### Web 后端开发
|
||
|
||
Web 后端是位于 `web/backend/` 的 FastAPI 应用程序。
|
||
|
||
```bash
|
||
# 启动开发服务器，支持热重载（http://localhost:8000）
|
||
pixi run api-dev
|
||
|
||
# 运行测试
|
||
pixi run api-test
|
||
|
||
# API 文档位于 http://localhost:8000/api/docs（DEBUG=true 时）
|
||
```
|
||
|
||
### 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）
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 找不到 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 |