AveryanAlex/zhunters

# ZHunters `zhunters` 是 Z-HUNT 3 Z-DNA 扫描器的 Rust 版本。它提供了 `zhunt` 命令行工具，用于扫描 DNA 序列并写入与旧版本兼容的 `.Z-SCORE` 输出文件。 该项目基于科罗拉多州立大学 Ho 实验室的原版 Z-HUNT 实现： https://github.com/Ho-Lab-Colostate/zhunt 它还结合了 Carlos Bederián 的 Fast Z-Hunt 实现的正确性和优化思想： https://github.com/zzzoom/fast-zhunt ## 基准测试 在 Ryzen 7 5800X 上对 `NC_043715.1[1..59306649].fa`（59.3 Mbases）进行本地基准测试，使用 `zhunt 12 8 12`： | 扫描器 | 实际时间 | 加速比 | 用户时间 | 系统时间 | CPU | | --- | ---: | ---: | ---: | ---: | ---: | | `zhunters` | `0:13.96` | `6.89×` | `156.82s` | `4.91s` | `1158%` | | `fast-zhunt` | `1:36.23` | `1.00×` | `710.58s` | `8.53s` | `747%` | | `zhunt` | `38:56.40` | `0.04×` | `2329.38s` | `6.72s` | `99%` | ## 原版 Z-HUNT 的变更 命令行界面、输入处理和 `.Z-SCORE` 输出格式与原版扫描器保持兼容。主要变更按是否添加到本 Rust 版本或从 Fast Z-Hunt 适配进行分组。 ### Rust 版本改进 - **Delta-linking 候选者剪枝：** 使用 delta-linking 方程的单调性跳过无法击败当前最佳 delta-linking 值的候选者长度。 - **Delta-linking 根搜索加速：** 根搜索使用受保护的新ton 预测器，捕捉到二分网格，并使用原始方程验证最终点。预测器还使用 delta-linking 方程的因式分解形式来减少运行时 `exp()` 调用。 - **Rayon 多线程：** 使用 Rayon 工作窃取并行化评分。结果以有序的评分块形式流式传输，以便写入器可以消费已完成的工作，而无需等待整个大型计算块。默认情况下，具有 8 个或更多逻辑 CPU 的系统保留一个 CPU 用于写入，并使用 `cores - 1` 评分工作者；较小的系统使用所有可用的 CPU。`--threads` 覆盖此默认值。 - **输入/输出流：** 输入文件通过缓冲读取器解析为标准化基，`.Z-SCORE` 行以有界、有序的块形式生成，然后刷新到磁盘。扫描器不保留原始 FASTA 文本或完整结果文件在 RAM 中，以保持大型基因组内存使用的可预测性。 - **进度报告：** 长时间扫描在评分和流式传输到磁盘时显示进度条。 - **工作器端输出格式化：** 评分块由 Rayon 工作器格式化为字节缓冲区，然后按顺序由写入器线程写入。 ### 从 Fast Z-Hunt 衍生的修复和优化 - **Anti/syn 评分修复：** anti/syn 路径选择使用精确的整数百卡能量总和，而不是累积递归 `float` 添加/减法。这避免了 Ho-Lab-Colostate/zhunt 问题 [#9](https://github.com/Ho-Lab-Colostate/zhunt/issues/9) 中描述的数值漂移。 - **斜率修复：** 报告的斜率是从实际最佳二核苷酸长度的对数系数计算的，而不是运行最后发生的任何长度。这修复了 Ho-Lab-Colostate/zhunt 问题 [#10](https://github.com/Ho-Lab-Colostate/zhunt/issues/10) 中描述的 `logcoef` 错误。 - **Anti/syn 动态规划优化：** 使用紧凑的两种状态动态规划评估精确的 anti/syn 评分，仅保留以 `AS` 结尾的最佳前缀和以 `SA` 结尾的最佳前缀。此优化基于 Carlos Bederián 的 Fast Z-Hunt 实现中使用的紧凑 anti/syn DP。 ## 安装 安装 Rust，然后构建发布二进制文件： ``` cargo build --release ``` 二进制文件将在以下位置可用： ``` target/release/zhunt ``` ### Jupyter/Colab 在 Jupyter 或 Google Colab 笔记本中，在单元格中运行以下命令以安装 Rust、构建 `zhunt` 并使其在 `PATH` 上可用： ``` !curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y !rm -rf /tmp/zhunters && GIT_LFS_SKIP_SMUDGE=1 git clone --depth 1 https://github.com/AveryanAlex/zhunters.git /tmp/zhunters !cd /tmp/zhunters && PATH="$PATH:/root/.cargo/bin" cargo build --release && cd - !cp /tmp/zhunters/target/release/zhunt /usr/local/bin/zhunt && rm -rf /tmp/zhunters !zhunt --help ``` ## 使用方法 ``` zhunt [--threads ] [-o

] ``` 示例： ``` target/release/zhunt 12 8 12 input.fa ``` 使用固定数量的工作线程： ``` target/release/zhunt --threads 8 12 8 12 input.fa ``` 将结果写入自定义路径： ``` target/release/zhunt -o results.Z-SCORE 12 8 12 input.fa ``` 默认情况下，输出文件将写入输入文件旁边： ``` input.fa.Z-SCORE ``` ## 参数 - `windowsize`：二核苷酸的最大窗口大小 - `minsize`：二核苷酸的最小区域大小 - `maxsize`：二核苷酸的最大区域大小 - `datafile`：输入 DNA 文件 - `--threads `：可选的 Rayon 评分工作者数量；默认为可用并行性，除非系统具有 8 个或更多逻辑 CPU，默认为 `cores - 1` 以留出空间进行写入/进度工作 - `-o, --output

`：可选的输出 `.Z-SCORE` 路径；默认为 `.Z-SCORE` 输入解析遵循旧版行为：扫描器读取文件中的所有 `A/T/G/C/N` 基，并忽略其他字节。 注意：当前物理常数实现使用 `dimensional_quantity`，这需要 nightly Rust。 ## 开发 运行格式化、linting 和测试： ``` cargo fmt --all -- --check cargo clippy --all-targets -- -D warnings cargo test --lib cargo test --test cli ``` ## 性能分析 如果已安装 `cargo-flamegraph`，请使用辅助脚本： ``` ./profile.sh 12 8 12 input.fa --threads 16 ``` 这将写入 `flamegraph.svg`。

标签：DNA序列分析, DNS解析, Rayon库, Rust编程, Z-DNA扫描, 二分搜索, 代码优化, 代码重构, 可视化界面, 学术研究, 工作窃取, 并行计算, 开源项目, 性能优化, 性能比较, 数据科学, 数据管道, 检测绕过, 牛顿法, 生物信息学, 科学计算, 算法改进, 计算机科学, 资源验证, 软件工程, 软件移植, 通知系统