alterlab-gtars

Gtars：Rust 基因组工具与算法

概述

Gtars（来自 databio，即 geniml 背后的实验室）是一套高性能 Rust 工具包，用于处理、分析和加工基因组区间数据。它的主要用途是作为 geniml 的性能关键型后端；geniml 是一个用于基因组区间机器学习的 Python 库。它提供重叠／集合运算、IGD 重叠索引、覆盖度（uniwig）轨道、面向机器学习的区域分词、单细胞片段伪合并，以及 GA4GH refget 序列集合管理。

何时使用此技能

在以下场景中使用此技能：

• 处理基因组区间文件（BED）——重叠、Jaccard、集合运算、覆盖度
• 使用 IGD 为大型区间数据库建立索引，以便快速查询重叠
• 通过 uniwig 生成覆盖度／累积轨道
• 基因组机器学习预处理和区域分词
• 处理单细胞片段文件（按簇拆分为伪合并数据集）
• 参考序列摘要和检索（refget）

不适用的场景

场景	改用
训练区域／单细胞嵌入（Region2Vec、scEmbed、BEDspace）	alterlab-geniml
逐条读取 BAM/CRAM/VCF（CIGAR、MAPQ、堆积图）	alterlab-pysam
从 BAM 生成标准化 bigWig 覆盖度、TSS 热图／曲线	alterlab-deeptools
地理（非基因组）空间连接和重叠	alterlab-geopandas

版本说明：示例已针对 gtars Python 包 0.10.0（PyPI，2026-09；最初为 0.8 编写——以下调用未变更）验证。Python API 通过子模块公开——gtars.models、gtars.tokenizers、gtars.refget、gtars.utils，以及较新的 gtars.genomic_distributions、gtars.lola、gtars.vrs——而不是顶层平铺函数。Python 中没有 gtars.igd 或 gtars.uniwig 子模块；IGD 构建和 uniwig 轨道生成仅支持 CLI。

安装

Python 包

uv pip install gtars   # or: uv add gtars

导入接口（已验证，0.10.0）：

from gtars.models import RegionSet, Region, RegionSetList
from gtars.tokenizers import Tokenizer, tokenize_fragment_file
from gtars import refget          # RefgetStore, digest_fasta, sha512t24u_digest, ...
from gtars import utils           # read/write .gtok token files

CLI（单独的 Rust 二进制文件）

CLI 以 gtars-cli crate（可执行文件名为 gtars）的形式发布，并通过 Cargo 安装。大多数子命令都需要启用功能标志：

# All commonly used commands
cargo install gtars-cli --features "uniwig overlaprs igd bbcache scoring fragsplit genomicdist"

# Or a subset
cargo install gtars-cli --features "uniwig igd"

可用的 CLI 子命令：igd、overlaprs、uniwig、bbcache、pb（片段伪合并）、scoring、genomicdist、ranges、consensus、prep。不同子命令的标志集各不相同，且会随版本演进——请务必通过 gtars <command> --help 确认。

核心功能

Gtars 由多个专用模块组成，每个模块专注于特定的基因组分析任务：

1. 重叠检测与集合运算

使用 RegionSet（Python）检测区域集合间的重叠并计算集合运算／相似度，或使用 IGD（CLI）为大型区间数据库建立索引。

适用场景：

• 查找重叠的调控元件、比较 ChIP-seq 峰
• 变异注释；识别共享的基因组特征
• 计算 BED 文件之间的 Jaccard／重叠系数相似度

快速示例（Python）：

from gtars.models import RegionSet

peaks = RegionSet("chip_peaks.bed")
promoters = RegionSet("promoters.bed")

# Regions in peaks that overlap a promoter (the real method is subset_by_overlaps)
in_promoters = peaks.subset_by_overlaps(promoters)
in_promoters.to_bed("peaks_in_promoters.bed")

print(peaks.count_overlaps(promoters))  # per-region overlap counts
print(peaks.jaccard(promoters))         # similarity score

如果需要多次查询大型参考数据库，可通过 CLI（gtars igd create ...）构建一次 IGD 索引，然后进行搜索（gtars igd search ...）。参见 references/overlap.md。

2. 覆盖度／累积轨道（uniwig，CLI）

使用 uniwig CLI 子命令，从 BED 或 BAM 文件生成覆盖度／累积轨道。

适用场景：

• ATAC-seq 可及性曲线、ChIP-seq 覆盖度、RNA-seq 读段覆盖度

快速示例（CLI）：

# uniwig reads a sorted BED/BAM and writes accumulation tracks.
# Flags differ by version; confirm with `gtars uniwig --help`.
gtars uniwig --file fragments.bed --filetype bed \
             --fileheader coverage --outputtype bw

有关已验证的标志，请参见 references/coverage.md；也可使用 RegionSet.coverage() 作为内存中的替代方案。

3. 基因组分词

将基因组区域转换为机器学习所需的离散令牌（这是 geniml 所基于的预处理层）。

适用场景：

• 将峰／区域预处理为基因组机器学习模型使用的固定词汇表
• 将令牌 ID 输入 geniml 或自定义 Transformer 模型

快速示例（Python）：

from gtars.tokenizers import Tokenizer
from gtars.models import Region

tokenizer = Tokenizer.from_bed("universe.bed")   # vocab = the universe BED
tokens = tokenizer.tokenize([Region("chr1", 1000, 2000, None)])  # -> ['chr1:1000-2000']
ids = tokenizer.convert_tokens_to_ids(tokens)                     # -> [<int>]

参见 references/tokenizers.md。注意：该类名为 Tokenizer（没有 TreeTokenizer）。

4. 参考序列管理（refget）

计算 GA4GH refget 摘要，并管理／检索参考序列。

适用场景：

• 通过序列摘要验证参考基因组的完整性
• 构建本地序列集合存储并提取子序列

快速示例（Python）：

from gtars import refget

# Digest a FASTA into a GA4GH SequenceCollection (no sequence data loaded)
collection = refget.digest_fasta("hg38.fa")

# Or a one-off sequence digest
d = refget.sha512t24u_digest("ACGTACGT")   # 32-char base64url GA4GH sha512t24u digest

关于 RefgetStore（加载、存储和 get_substring），请参阅 references/refget.md。

5. 片段伪汇总（pb，CLI）

根据簇／细胞组映射，将单细胞片段文件拆分为伪汇总。

适用场景：

• 处理单细胞 ATAC-seq；按簇聚合片段

快速示例（CLI）：

# The fragsplit feature exposes the `pb` (pseudobulk) subcommand.
gtars pb --fragments fragments.bed.gz --mapping cluster_mapping.tsv

Python 端还提供 gtars.tokenizers.tokenize_fragment_file(...)，可直接对片段进行分词。请参阅 references/cli.md。

6. 片段／区域评分

使用 scoring CLI 子命令，根据参考数据集对区域／片段文件进行评分。

适用场景：

• 评估区域相对于参考全集的富集情况
• 跨样本批量计算质量指标

gtars scoring --help   # confirm subcommands and flags for your installed version

常见工作流

工作流 1：峰重叠分析

识别与启动子重叠的峰（Python）：

from gtars.models import RegionSet

peaks = RegionSet("chip_peaks.bed")
promoters = RegionSet("promoters.bed")

overlapping_peaks = peaks.subset_by_overlaps(promoters)
overlapping_peaks.to_bed("peaks_in_promoters.bed")

# Iterate results (regions expose .chr/.start/.end)
for r in overlapping_peaks:
    print(r.chr, r.start, r.end)

工作流 2：IGD 索引 + 重复重叠查询（CLI）

对大型参考数据库建立一次索引，然后多次搜索：

# Build the IGD database from a directory or list of BED files
gtars igd create --help     # confirm the exact input/output flags for your version

# Search the database with query regions
gtars igd search --help

工作流 3：机器学习预处理（分词）

为机器学习模型准备基因组区域：

from gtars.tokenizers import Tokenizer
from gtars.models import RegionSet

# Step 1: Build a tokenizer from the universe BED (defines the vocabulary)
tokenizer = Tokenizer.from_bed("universe.bed")

# Step 2: Tokenize a region set (tokenize accepts a RegionSet or a list of Region)
regions = RegionSet("training_peaks.bed")
tokens = tokenizer.tokenize(regions)                      # list of 'chr:start-end' strings
ids = tokenizer.convert_tokens_to_ids(tokens)             # integer IDs for the model

# Step 3: feed `ids` to geniml or a custom model (see alterlab-geniml for training)

Python 与 CLI 用法对比

适合使用 Python API 的场景：

• 集成到分析流水线中
• 需要以编程方式进行控制
• 使用 NumPy/Pandas
• 构建自定义工作流

适合使用 CLI 的场景：

• 快速进行一次性分析
• 编写 Shell 脚本
• 批量处理文件
• 对工作流进行原型验证

参考文档

• references/python-api.md — RegionSet / Region 操作、集合运算、重叠、导出
• references/overlap.md — 重叠检测和 IGD 索引
• references/coverage.md — uniwig 覆盖度轨道
• references/tokenizers.md — 用于机器学习的区域分词
• references/refget.md — refget 摘要和 RefgetStore
• references/cli.md — CLI 子命令概览

与 geniml 的关系

gtars 是 geniml（databio 的基于基因组区间的机器学习库）的 Rust 性能后端。使用 gtars 执行繁重的区间操作和分词；使用 geniml（技能 alterlab-geniml）基于这些词元进行嵌入／模型训练。

数据格式

• BED：基因组区间（3 列或扩展格式）——核心输入
• BigWig / WIG：覆盖度／累积轨道（uniwig 输出）
• FASTA：参考序列（refget）
• 片段文件：单细胞片段（通常为 .bed.gz），pb 还需要单独的簇映射文件

验证 API

此软件包的接口在不同版本之间有所差异，Python API 和 CLI API 并非一一对应。使用不熟悉的方法或标志前，请先根据已安装的版本进行确认：

uv run python -c "from gtars import models, tokenizers, refget; print(dir(models), dir(tokenizers), dir(refget))"
gtars <command> --help

属于 AlterLab Academic Skills 套件。