# BtToxin_Digger (pixi) 复现环境

本仓库是 BtToxin_Digger 1.0.10 的**可复现运行环境 + 示例输出**，支持 **BLAST v5 数据库兼容性**。这**不是**官方分支或新版本发布。

## 许可证 / 引用 / 免责声明

- **BtToxin_Digger** 由原作者开发，如在研究中使用请引用上游论文
- **本仓库**仅提供环境封装（pixi）和示例运行用于复现，不修改 BtToxin_Digger 源代码
- **免责声明**：这是独立的社区维护配置，未经上游作者认可

本目录使用 pixi 复现 `quay.io/biocontainers/bttoxin_digger:1.0.10--hdfd78af_0` 的环境，使 `scripts/run_single_fna_pipeline.py` 的 digger 步骤可以在无 Docker 环境下运行。

## 1) 环境定义（对比 Docker 镜像）

- `pixi.toml` 保持 `bttoxin_digger=1.0.10` + `perl=5.26.2`（旧版栈），同时升级 `blast` 到支持 v5 的版本以兼容 BLASTDB v5
- 相对于 `quay.io/biocontainers/bttoxin_digger:1.0.10--hdfd78af_0` 的变更：
  - BLAST+ 从 2.12.0 升级到 2.16.0（读取 v5 数据库所需）
  - 显式固定 `perl-file-tee==0.07` 和 `perl-list-util==1.38`
  - `channel-priority = "disabled"` 以允许混合 bioconda/conda-forge 和旧版 perl 兼容标签

创建环境：

```bash
cd bttoxin_digger_v5_repro
pixi install
```

## 2) 数据库配置（BLAST v4 vs v5）

`external_dbs/bt_toxin` 下的外部 BTTCMP 数据库使用 BLAST v5 索引（由新版 BLAST+ 构建）。如果使用 BLAST 2.7，需要重建 v4 数据库；使用 BLAST >= 2.10 可以直接使用 v5 数据库。

### 推荐：使用共享的 `external_dbs`（无需复制）

保持单一数据源，链接到 pixi 环境：

```bash
ENV_BIN=bttoxin_digger_v5_repro/.pixi/envs/default/bin
ln -sfn $(pwd)/external_dbs/bt_toxin "$ENV_BIN/BTTCMP_db/bt_toxin"
```

这样可以避免在仓库内复制大型数据库。

### 可选：在本仓库内冻结快照

如果需要本仓库完全自包含，可以复制快照并指向它（注意：如果要推送到 Git，考虑使用 Git LFS）：

```bash
SNAPSHOT=bttoxin_digger_v5_repro/external_dbs_snapshot
mkdir -p "$SNAPSHOT"
cp -a external_dbs/bt_toxin "$SNAPSHOT/"
ln -sfn "$SNAPSHOT/bt_toxin" "$ENV_BIN/BTTCMP_db/bt_toxin"
```

## 3) 运行 BtToxin_Digger（组装基因组）

`run_digger_pixi.sh` 在本目录内设置 `RATTLER_CACHE_DIR`，使 pixi 可以在工作区写入缓存（默认的 `~/.cache` 路径可能被沙箱阻止）。

单个 `.fna` 文件示例（使用干净的工作目录）：

```bash
mkdir -p work/C15_pixi_run
cd work/C15_pixi_run

bash ../../run_digger_pixi.sh ../../examples/inputs .fna 4
```

如果要显式绑定 `external_dbs/bt_toxin`：

```bash
bash ../../run_digger_pixi.sh ../../examples/inputs .fna 4 /path/to/external_dbs/bt_toxin
```

输出会生成在工作目录的 `Results/` 下。

### 参数说明

| 参数 | 说明 |
|------|------|
| `input_dir` | 输入目录（存放 `.fna` 文件） |
| `scaf_suffix` | 输入文件后缀（如 `.fna`） |
| `threads` | 线程数（默认 4） |
| `bttoxin_db_dir` | 外部 bt_toxin 数据库路径（可选） |

### 与 scripts/run_single_fna_pipeline.py 的一致性

pixi 脚本调用的 BtToxin_Digger 参数与 `scripts/run_single_fna_pipeline.py` 里的 Docker 调用一致：

| 参数 | 说明 |
|------|------|
| `--SeqPath <dir>` | 输入目录 |
| `--SequenceType nucl` | 核酸输入 |
| `--Scaf_suffix .fna` | 文件后缀 |
| `--threads 4` | 线程数 |

**差异点：**
- Docker 版本会自动绑定 `external_dbs/bt_toxin`（若存在），并把输出整理到 `runs/<out_root>/digger`
- pixi 版本默认在当前工作目录生成 `Results/`
- `scripts/run_single_fna_pipeline.py` 还会继续运行 Shotter + report；pixi 脚本只执行 BtToxin_Digger 本体

## 4) 输出和对比（示例）

### 输入文件

- `examples/inputs/C15.fna`
- `examples/inputs/HAN055.fna`

### 示例运行结果

| 类型 | C15 | HAN055 |
|------|-----|--------|
| pixi 运行 | `examples/C15_pixi_v5` | `examples/HAN055_pixi_v5_clean` |
| Docker 运行 | `examples/C15_docker/digger` | `examples/HAN055_docker/digger` |

### 对比报告

- 汇总报告：`examples/COMPARE_REPORT.md`
- Diff 文件：
  - `examples/diffs/C15_docker_vs_pixi_v5.diff`
  - `examples/diffs/HAN055_docker_vs_pixi_v5_clean.diff`

## 5) 外部数据库更新（v5）

当从 BtToxin_Digger 仓库更新 `external_dbs/bt_toxin` 时，BLAST 数据库是 v5 格式，需要 BLAST >= 2.10.0。这就是为什么本 pixi 环境将 BLAST 升级到 2.16.0。

更新 `external_dbs/bt_toxin` 后，确保 pixi 环境仍指向该目录（见第 2 节）。使用 BLAST 2.16.0 时无需重新索引，因为上游仓库已包含预构建的 v5 索引。如果降级到 BLAST 2.7，需要重建 v4 数据库（见第 2 节）。

### 更新步骤

```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
```

### 验证数据库绑定

```bash
# 检查数据库文件是否完整
ls -lh external_dbs/bt_toxin/db/

# 验证容器能正确访问绑定的数据库
docker run --rm \
  -v "$(pwd)/external_dbs/bt_toxin:/usr/local/bin/BTTCMP_db/bt_toxin:ro" \
  quay.io/biocontainers/bttoxin_digger:1.0.10--hdfd78af_0 \
  bash -lc 'ls -lh /usr/local/bin/BTTCMP_db/bt_toxin/db | head'
```

输出应显示 `.pin/.psq/.phr` 等文件，且时间戳/大小与宿主机一致，说明绑定成功。

## 6) 目录结构

```
bttoxin_digger_v5_repro/
├─ .pixi/                       # pixi 环境缓存
├─ pixi.toml                    # 环境定义（bttoxin_digger + blast）
├─ pixi.lock                    # 锁定的环境依赖
├─ run_digger_pixi.sh           # 在此环境运行 BtToxin_Digger 的封装脚本
├─ README.md                    # 英文文档
├─ README_CN.md                 # 中文文档
└─ examples/
   ├─ inputs/                   # 测试输入文件（C15.fna, HAN055.fna）
   ├─ C15_pixi_v5/              # pixi 运行输出（示例）
   ├─ HAN055_pixi_v5_clean/     # pixi 运行输出（示例）
   ├─ C15_docker/               # Docker 输出副本（基准）
   ├─ HAN055_docker/            # Docker 输出副本（基准）
   ├─ diffs/                    # Docker vs pixi 差异文件
   └─ COMPARE_REPORT.md         # 对比报告
```

## 7) 常见问题

### Q: 为什么需要这个复现环境？

A: 主项目的 `scripts/run_single_fna_pipeline.py` 默认使用 Docker 运行 BtToxin_Digger。本环境提供了一个无 Docker 的替代方案，使用 pixi 管理依赖，适用于：
- 无法使用 Docker 的环境（如某些 HPC 集群）
- 需要调试或修改 BtToxin_Digger 运行参数的场景
- 验证 pixi 环境与 Docker 环境输出一致性

### Q: pixi 运行结果与 Docker 一致吗？

A: 是的，`examples/COMPARE_REPORT.md` 和 `examples/diffs/` 目录包含了详细的对比结果，证明两种方式的输出是一致的。

### Q: 如何切换回 Docker 运行？

A: 直接使用主项目的 `scripts/run_single_fna_pipeline.py`，它默认使用 Docker。