概述
gtars 是一个用 Rust 编写的高性能工具包，用于操作、分析和处理基因组区间数据。它提供了重叠检测、覆盖度分析、面向机器学习的 tokenization 以及参考序列管理等专门工具。
以下场景可使用该技能：
- 基因组区间文件（BED 格式）
- 基因组区域之间的重叠检测
- 覆盖度轨道生成（WIG、BigWig）
- 基因组机器学习预处理与 tokenization
- 单细胞基因组学中的片段分析
- 参考序列检索与校验
安装
Python 安装
安装 gtars Python 绑定：
uv uv pip install gtars
CLI 安装
安装命令行工具（需要 Rust/Cargo）：
# Install with all features
cargo install gtars-cli --features "uniwig overlaprs igd bbcache scoring fragsplit"
# Or install specific features only
cargo install gtars-cli --features "uniwig overlaprs"
Rust 库
在 Rust 项目的 Cargo.toml 中添加：
[dependencies]
gtars = { version = "0.1", features = ["tokenizers", "overlaprs"] }
核心能力
gtars 按专门模块组织，每个模块聚焦特定的基因组分析任务。
1. 重叠检测与 IGD 索引
使用 Integrated Genome Database (IGD) 数据结构高效检测基因组区间之间的重叠。
适用场景：
- 查找重叠的调控元件
- 变异注释
- 比较 ChIP-seq peak
- 识别共享的基因组特征
示例：
import gtars
# Build IGD index and query overlaps
igd = gtars.igd.build_index("regions.bed")
overlaps = igd.query("chr1", 1000, 2000)
2. 覆盖度轨道生成
使用 uniwig 模块从测序数据生成覆盖度轨道。
适用场景：
- ATAC-seq 可及性图谱
- ChIP-seq 覆盖度可视化
- RNA-seq 读段覆盖度
- 差异覆盖度分析
示例：
# Generate BigWig coverage track
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）。
适用场景：
- 校验参考基因组完整性
- 提取特定基因组序列
- 计算序列摘要
- 交叉引用比较
示例：
# Load reference and extract sequences
store = gtars.RefgetStore.from_fasta("hg38.fa")
sequence = store.get_subsequence("chr1", 1000, 2000)
5. 片段处理
拆分和分析片段文件，尤其适用于单细胞基因组学数据。
适用场景：
- 处理单细胞 ATAC-seq 数据
- 按细胞条形码拆分片段
- 基于聚类的片段分析
- 片段质量控制
示例：
# Split fragments by clusters
gtars fragsplit cluster-split --input fragments.tsv --clusters clusters.txt --output-dir ./by_cluster/
6. 片段打分
将片段重叠与参考数据集进行打分。
适用场景：
- 评估片段富集
- 将实验数据与参考比较
- 质量指标计算
- 跨样本批量打分
示例：
# Score fragments against reference
gtars scoring score --fragments fragments.bed --reference reference.bed --output scores.txt
常见工作流
工作流 1：Peak 重叠分析
识别重叠的基因组特征：
import gtars
# Load two region sets
peaks = gtars.RegionSet.from_bed("chip_peaks.bed")
promoters = gtars.RegionSet.from_bed("promoters.bed")
# Find overlaps
overlapping_peaks = peaks.filter_overlapping(promoters)
# Export results
overlapping_peaks.to_bed("peaks_in_promoters.bed")
工作流 2：覆盖度轨道管线
生成覆盖度轨道用于可视化：
# Step 1: Generate coverage
gtars uniwig generate --input atac_fragments.bed --output coverage.wig --resolution 10
# Step 2: Convert to BigWig for genome browsers
gtars uniwig generate --input atac_fragments.bed --output coverage.bw --format bigwig
工作流 3：ML 预处理
为机器学习准备基因组数据：
from gtars.tokenizers import TreeTokenizer
import gtars
# Step 1: Load training regions
regions = gtars.RegionSet.from_bed("training_peaks.bed")
# Step 2: Create tokenizer
tokenizer = TreeTokenizer.from_bed_file("training_peaks.bed")
# Step 3: Tokenize regions
tokens = [tokenizer.tokenize(r.chromosome, r.start, r.end) for r in regions]
# Step 4: Use tokens in ML pipeline
# (integrate with geniml or custom models)
Python 与 CLI 用法
使用 Python API 的场景：
- 集成到分析管线
- 需要程序化控制
- 配合 NumPy/Pandas 工作
- 构建自定义工作流
使用 CLI 的场景：
- 快速单次分析
- Shell 脚本
- 批量处理文件
- 工作流原型设计
与 geniml 的集成
gtars 是 geniml Python 包的基础，为机器学习工作流提供核心基因组区间操作。在处理 geniml 相关任务时，可使用 gtars 进行数据预处理与 tokenization。
性能特征
- 原生 Rust 性能：执行快速，内存开销低
- 并行处理：面向大数据集的多线程操作
- 内存效率：支持流式与内存映射文件
- 零拷贝操作：NumPy 集成，数据复制最小化
数据格式
gtars 支持标准基因组格式：
- BED：基因组区间（3 列或扩展列）
- WIG/BigWig：覆盖度轨道
- FASTA：参考序列
- Fragment TSV：带条形码的单细胞片段文件
错误处理与调试
启用详细日志以便排查问题：
import gtars
# Enable debug logging
gtars.set_log_level("DEBUG")
# CLI verbose mode
gtars --verbose <command>