gtars

Gtars：Rust 基因组工具与算法

概述

Gtars 是一款高性能 Rust 工具包，用于操作、分析和处理基因组区间数据。它提供专用工具，可用于重叠检测、覆盖度分析、机器学习分词和参考序列管理。

在以下场景中使用此工具包：

• 基因组区间文件（BED 格式）
• 检测基因组区域之间的重叠
• 生成覆盖度轨道（WIG、BigWig）
• 基因组机器学习预处理与分词
• 单细胞基因组学中的片段分析
• 参考序列检索与验证

安装

Python 安装

安装 gtars Python 绑定：

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 索引

使用集成基因组数据库（IGD）数据结构，高效检测基因组区间之间的重叠。

适用场景：

• 查找重叠的调控元件
• 变异注释
• 比较 ChIP-seq 峰
• 识别共享的基因组特征

快速示例：

import gtars

# Build IGD index and query overlaps
igd = gtars.igd.build_index("regions.bed")
overlaps = igd.query("chr1", 1000, 2000)

请参阅 references/overlap.md，了解全面的重叠检测文档。

2. 覆盖度轨道生成

使用 uniwig 模块根据测序数据生成覆盖度轨道。

适用场景：

• ATAC-seq 可及性图谱
• ChIP-seq 覆盖度可视化
• RNA-seq 读段覆盖度
• 差异覆盖度分析

快速示例：

# Generate BigWig coverage track
gtars uniwig generate --input fragments.bed --output coverage.bw --format bigwig

请参阅 references/coverage.md，了解详细的覆盖度分析工作流。

3. 基因组分词

将基因组区域转换为离散词元，用于机器学习应用，尤其是基于基因组数据的深度学习模型。

适用场景：

• 基因组机器学习模型的预处理
• 与 geniml 库集成
• 创建位置编码
• 在基因组序列上训练 Transformer 模型

快速示例：

from gtars.tokenizers import TreeTokenizer

tokenizer = TreeTokenizer.from_bed_file("training_regions.bed")
token = tokenizer.tokenize("chr1", 1000, 2000)

请参阅 references/tokenizers.md，了解分词文档。

4. 参考序列管理

处理参考基因组序列，并遵循 GA4GH refget 协议计算摘要。

适用场景：

• 验证参考基因组完整性
• 提取特定基因组序列
• 计算序列摘要
• 交叉参考比较

快速示例：

# Load reference and extract sequences
store = gtars.RefgetStore.from_fasta("hg38.fa")
sequence = store.get_subsequence("chr1", 1000, 2000)

请参阅 references/refget.md，了解参考序列操作。

5. 片段处理

拆分并分析片段文件，尤其适用于单细胞基因组学数据。

适用场景：

• 处理单细胞 ATAC-seq 数据
• 按细胞条形码拆分片段
• 基于聚类的片段分析
• 片段质量控制

快速示例：

# Split fragments by clusters
gtars fragsplit cluster-split --input fragments.tsv --clusters clusters.txt --output-dir ./by_cluster/

请参阅 references/cli.md，了解片段处理命令。

6. 片段评分

根据参考数据集为片段重叠评分。

适用场景：

• 评估片段富集情况
• 将实验数据与参考数据进行比较
• 计算质量指标
• 跨样本批量评分

快速示例：

# Score fragments against reference
gtars scoring score --fragments fragments.bed --reference reference.bed --output scores.txt

常见工作流

工作流 1：峰重叠分析

识别重叠的基因组特征：

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：机器学习预处理

为机器学习准备基因组数据：

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 脚本
• 批量处理文件
• 为工作流制作原型

参考文档

完整的模块文档：

• references/python-api.md - 完整的 Python API 参考，涵盖 RegionSet 操作、NumPy 集成和数据导出
• references/overlap.md - IGD 索引、重叠检测和集合操作
• references/coverage.md - 使用 uniwig 生成覆盖度轨道
• references/tokenizers.md - 面向机器学习应用的基因组分词
• references/refget.md - 参考序列管理和摘要
• references/cli.md - 命令行界面的完整参考

与 geniml 集成

Gtars 是 geniml Python 包的基础，为机器学习工作流提供核心基因组区间操作。处理 geniml 相关任务时，请使用 gtars 进行数据预处理和分词。

性能特征

• 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>