fe353fc0bc
- 移除 Motia Streams 实时通信，改用 3 秒轮询 - 简化前端代码，移除冗余组件 - 简化后端架构，准备 FastAPI 重构 - 更新 pixi.toml 环境配置 - 保留 bttoxin_digger_v5_repro 作为参考文档 Co-Authored-By: Claude <noreply@anthropic.com>
196 lines
7.2 KiB
Markdown
196 lines
7.2 KiB
Markdown
# 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。
|