bttoxin-pipeline/bttoxin_digger_v5_repro/README_CN.md

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 兼容标签

创建环境：

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 环境：

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）：

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 文件示例（使用干净的工作目录）：

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 ../../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 节）。

更新步骤

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

验证数据库绑定

# 检查数据库文件是否完整
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。