bttoxin-pipeline/README_CN.md

BtToxin Pipeline

基于 pixi 管理环境的苏云金芽孢杆菌（Bacillus thuringiensis）毒素自动挖掘系统。

快速开始

前置要求

• pixi - 现代 conda 环境包管理器
• Linux x86_64 (linux-64 平台)

安装

1. 安装 pixi（如果尚未安装）：

# Linux/macOS
curl -fsSL https://pixi.sh/install.sh | bash

# 或通过 Homebrew
brew install pixi

2. 克隆并设置项目：

git clone <your-repo>
cd bttoxin-pipeline

# 安装所有环境（digger + pipeline）
pixi install

这将创建两个独立的环境：

• digger：BtToxin_Digger 及 bioconda 依赖（perl、blast 等）
• pipeline：Python 分析工具（pandas、matplotlib、seaborn）

运行管道

完整管道（推荐）

使用单个命令运行完整的分析管道：

pixi run pipeline --fna tests/test_data/HAN055.fna

这将执行三个阶段：

1. Digger：BtToxin_Digger 毒素挖掘
2. Shotter：毒素评分和靶标预测
3. Plot：热图生成和报告创建

CLI 选项

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）

示例

# 使用默认设置的基础运行
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

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）

示例：

pixi run digger-only --fna tests/test_data/C15.fna --threads 8

Shotter（评分）

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     只保留索引命中的结果

示例：

pixi run shotter \
  --all_toxins runs/C15_run/digger/Results/Toxins/All_Toxins.txt \
  --output_dir runs/C15_run/shotter

Plot（可视化）

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）

示例：

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 上的最新版本：

更新步骤

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 界面，方便任务提交和监控。

快速启动

# 同时启动前端和后端服务（推荐）
pixi run web-start

# 前端：http://localhost:5173
# 后端：http://localhost:8000

或者分别启动服务：

# 终端 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 之外的开发工作：

uv venv --managed-python -p 3.12 --seed .venv
source .venv/bin/activate
uv pip install -e .

运行测试

# 运行管道的属性测试
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 的快速启动：

# 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

手动构建镜像

若要手动构建镜像，请确保设置正确的构建上下文（build context），以便 Docker 能找到 pixi.toml。

# 选项 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

# 确保 pixi 在 PATH 中
export PATH="$HOME/.pixi/bin:$PATH"

# 或重新安装
curl -fsSL https://pixi.sh/install.sh | bash

环境未找到

# 重新安装环境
pixi install

BtToxin_Digger 不可用

# 验证 digger 环境
pixi run -e digger BtToxin_Digger --help

权限错误

确保输出目录有写权限。管道会自动创建目录。

许可证

MIT License