# 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