概述
gtars（Genomic Tools and Algorithms in Rust）是一个用 Rust 编写的高性能工具包，用于操作、分析和处理基因组区间数据。它提供重叠检测、覆盖度分析、面向机器学习的 tokenization 以及参考序列管理等专用工具。
适用场景包括：基因组区间文件（BED 格式）、基因组区域之间的重叠检测、覆盖度轨迹生成（WIG、BigWig）、基因组机器学习预处理与 tokenization、单细胞基因组学中的片段分析、参考序列检索与验证。
安装方式
Python 安装：
uv pip install gtars
CLI 安装（需要 Rust/Cargo）：
# 安装全部特性
cargo install gtars-cli --features "uniwig overlaprs igd bbcache scoring fragsplit"
# 或仅安装特定特性
cargo install gtars-cli --features "uniwig overlaprs"
Rust 库：在 Cargo.toml 中添加：
[dependencies]
gtars = { version = "0.1", features = ["tokenizers", "overlaprs"] }
主要能力
gtars 按专用模块组织，每个模块聚焦特定的基因组分析任务。
1. 重叠检测与 IGD 索引
使用 Integrated Genome Database（IGD）数据结构高效检测基因组区间之间的重叠。
适用场景：查找重叠的调控元件、变异注释、比较 ChIP-seq peaks、识别共享基因组特征。
示例：
import gtars
# 构建 IGD 索引并查询重叠
igd = gtars.igd.build_index("regions.bed")
overlaps = igd.query("chr1", 1000, 2000)
2. 覆盖度轨迹生成
使用 uniwig 模块从测序数据生成覆盖度轨迹。
适用场景：ATAC-seq 可及性图谱、ChIP-seq 覆盖度可视化、RNA-seq 读段覆盖度、差异覆盖度分析。
示例：
# 生成 BigWig 覆盖度轨迹
gtars uniwig generate --input fragments.bed --output coverage.bw --format bigwig
3. 基因组 Tokenization
将基因组区域转换为离散 token，用于机器学习应用，尤其是基因组数据上的深度学习模型。
适用场景：基因组 ML 模型预处理、与 geniml 库集成、创建位置编码、在基因组序列上训练 transformer 模型。
示例：
from gtars.tokenizers import TreeTokenizer
tokenizer = TreeTokenizer.from_bed_file("training_regions.bed")
token = tokenizer.tokenize("chr1", 1000, 2000)
4. 参考序列管理
处理参考基因组序列，并按照 GA4GH refget 协议计算 digest。
适用场景：验证参考基因组完整性、提取特定基因组序列、计算序列 digest、交叉引用比较。
示例：
# 加载参考序列并提取子序列
store = gtars.RefgetStore.from_fasta("hg38.fa")
sequence = store.get_subsequence("chr1", 1000, 2000)
5. 片段处理
拆分和分析片段文件，尤其适用于单细胞基因组学数据。
适用场景：处理单细胞 ATAC-seq 数据、按细胞 barcode 拆分片段、基于聚类的片段分析、片段质量控制。
示例：
# 按聚类拆分片段
gtars fragsplit cluster-split --input fragments.tsv --clusters clusters.txt --output-dir ./by_cluster/
6. 片段评分
将片段重叠与参考数据集进行评分。
适用场景：评估片段富集、将实验数据与参考比较、计算质量指标、跨样本批量评分。
示例：
# 针对参考对片段评分
gtars scoring score --fragments fragments.bed --reference reference.bed --output scores.txt
常见工作流
工作流 1：Peak 重叠分析
识别重叠的基因组特征：
import gtars
# 加载两个区域集
peaks = gtars.RegionSet.from_bed("chip_peaks.bed")
promoters = gtars.RegionSet.from_bed("promoters.bed")
# 查找重叠
overlapping_peaks = peaks.filter_overlapping(promoters)
# 导出结果
overlapping_peaks.to_bed("peaks_in_promoters.bed")
工作流 2：覆盖度轨迹流水线
生成用于可视化的覆盖度轨迹：
# 步骤 1：生成覆盖度
gtars uniwig generate --input atac_fragments.bed --output coverage.wig --resolution 10
# 步骤 2：转换为 BigWig 以供基因组浏览器使用
gtars uniwig generate --input atac_fragments.bed --output coverage.bw --format bigwig
工作流 3：机器学习预处理
为机器学习准备基因组数据：
from gtars.tokenizers import TreeTokenizer
import gtars
# 步骤 1：加载训练区域
regions = gtars.RegionSet.from_bed("training_peaks.bed")
# 步骤 2：创建 tokenizer
tokenizer = TreeTokenizer.from_bed_file("training_peaks.bed")
# 步骤 3：对区域进行 tokenize
tokens = [tokenizer.tokenize(r.chromosome, r.start, r.end) for r in regions]
# 步骤 4：在 ML 流水线中使用 token
# （与 geniml 或自定义模型集成）
Python 与 CLI 的使用选择
使用 Python API 的场景：与分析流水线集成、需要程序化控制、配合 NumPy/Pandas 使用、构建自定义工作流。
使用 CLI 的场景：快速的一次性分析、Shell 脚本、批量处理文件、工作流原型验证。
参考文档
各模块的详细文档包括：python-api.md（Python API 参考，含 RegionSet 操作、NumPy 集成与数据导出）、overlap.md（IGD 索引、重叠检测与集合操作）、coverage.md（使用 uniwig 生成覆盖度轨迹）、tokenizers.md（面向 ML 应用的基因组 tokenization）、refget.md（参考序列管理与 digest）、cli.md（命令行接口完整参考）。
与 geniml 的集成
gtars 是 geniml Python 包的基础，为机器学习工作流提供核心基因组区间操作。在处理 geniml 相关任务时，可使用 gtars 进行数据预处理与 tokenization。
性能特征
- 原生 Rust 性能：执行速度快，内存开销低
- 并行处理：针对大型数据集的多线程操作
- 内存效率：支持流式与内存映射文件
- 零拷贝操作：NumPy 集成，数据复制最少
数据格式
gtars 支持标准基因组格式：BED（基因组区间，3 列或扩展格式）、WIG/BigWig（覆盖度轨迹）、FASTA（参考序列）、Fragment TSV（带 barcode 的单细胞片段文件）。
错误处理与调试
可启用详细日志进行故障排查：
import gtars
# 启用调试日志
gtars.set_log_level("DEBUG")
# CLI 详细模式
gtars --verbose <command>