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（线虫纲）：蛔虫

开发

前端开发

前端是位于 frontend/ 的 Vue 3 + Vite + Element Plus 应用程序。

# 安装依赖
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 应用程序。

# 启动开发服务器，支持热重载（http://localhost:8000）
pixi run api-dev

# 运行测试
pixi run api-test

# API 文档位于 http://localhost:8000/api/docs（DEBUG=true 时）

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）

故障排除

找不到 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