gtars

用途

Gtars 是一个用于基因组区间（genomic interval）与参考序列（reference-sequence）处理的工具包，提供原生 Rust 实现、Python 绑定，以及一个通过 feature gate 启用的 gtars 命令行二进制。它适合在本地对 BED 等区间数据进行集合运算、重叠分析、覆盖度计算、tokenizer 处理与参考序列存储等操作。

主要能力

BED RegionSet 集合代数：reduce、setdiff、pintersect、concat、union、jaccard、coverage、overlap_coefficient、intersect_all、closest、cluster、gaps 等。
重叠查询：count_overlaps、any_overlaps、find_overlaps、intersect_all、coverage。
共识区间：通过 gtars.genomic_distributions 模块的 consensus 函数生成带 count 的共识行。
Tokenizer：Tokenizer.from_bed 与 tokenize/编码，用于将区间转换为 token。
refget 参考序列存储：RefgetStore.in_memory、open_local、open_remote 等。
附带六个确定性本地 CLI 辅助脚本：bed_validator、execution_plan、tokenizer_manifest、refget_digest_plan、coverage_preflight、artifact_inspector。

版本与安装

已验证快照（2026-07-23）：Python 包 gtars==0.9.2（2026-06-17 发布，Requires-Python >=3.10）；Rust 元 crate gtars=0.9.0（2026-06-15 发布，默认 feature 集为空）；CLI crate/二进制 gtars-cli=0.9.0，安装后二进制名为 gtars；直接 refget crate gtars-refget=0.9.1（2026-06-17 发布）。上游有意对 workspace crate、Python 绑定与 CLI 独立版本化，版本号相同不代表产物相同。

Python 安装示例： uv venv --python 3.11 .venv-gtars uv pip install --dry-run --python .venv-gtars/bin/python "gtars==0.9.2" uv pip install --python .venv-gtars/bin/python "gtars==0.9.2" .venv-gtars/bin/python -c "import gtars; assert gtars.version == '0.9.2'; print(gtars.version)"

CLI 安装示例： cargo install gtars-cli --version 0.9.0 --locked gtars --version gtars --help

Rust 项目依赖示例： [dependencies] gtars = { version = "=0.9.0", default-features = false, features = [ "core", "overlaprs", "uniwig", "tokenizers", "refget" ] }

使用方式

Python 导入来自子模块而非 gtars 顶层： from gtars.models import Region, RegionSet

query = RegionSet.from_regions( [ Region(chr="chr1", start=100, end=200, rest=None), Region(chr="chr1", start=300, end=400, rest=None), ], strands=["+", "-"], ) universe = RegionSet.from_vectors( ["chr1", "chr1"], [150, 500], [350, 600], )

counts = query.count_overlaps(universe) flags = query.any_overlaps(universe) indices = query.find_overlaps(universe) pieces = query.intersect_all(universe) fraction = query.coverage(universe)

RegionSet.sort() 会原地修改并返回 None。共识函数位于不同模块： from gtars.genomic_distributions import consensus rows = consensus([query, universe])

本地校验脚本示例： python3 -B scripts/bed_validator.py
--input data.bed.gz
--assembly GRCh38.p14
--chrom-sizes GRCh38.p14.chrom.sizes
--require-sorted

适用场景

对 BED 区间进行集合运算、重叠计数与覆盖度分析。
构建与使用 tokenizer 处理基因组区间。
通过 refget 存储与读取参考序列。
在本地对基因组区间数据进行校验、规划与预检。

限制与注意事项

坐标契约：BED 为 0-based 半开区间 [start, end)，要求 0 <= start < end <= contig_length；Gtars 坐标为 u32，拒绝超过 4,294,967,295 的值。
装配与 contig：需记录装配 accession/version 与染色体大小或 refget 元数据的 SHA-256；contig 名称需精确比较，1 与 chr1 等不可互换。
排序：Python RegionSet(path) 加载时按 contig 与 start 字典序排序，不应依赖原始行顺序。
链方向：BED6 使用 +、- 或 .；文件支持的 Python RegionSet 当前将 strands 向量初始化为 *，部分集合运算会丢弃链信息，需在外部保留与校验。
重复/相邻：reduce() 与 consensus 会合并重叠与相邻区间；普通半开重叠不将 [0,10) 与 [10,20) 视为重叠。
网络与缓存：RegionSet(path) 支持 HTTP，不存在的本地字符串可能被当作 URL；Tokenizer.from_pretrained 可能下载 universe.bed.gz 到 Hugging Face 缓存；RefgetStore.on_disk 会创建/写入存储；open_remote 默认启用持久化；gtars bbcache 会创建缓存目录。任何网络调用前需获得明确批准并记录来源与校验和。
原生代码信任：Python wheel 含 PyO3 原生扩展，Cargo 安装会编译原生二进制并可能运行依赖构建脚本，应视为代码执行，需确认官方来源、版本、许可证与 SHA-256，并在隔离与资源限制下运行。
许可证：本技能标注 MIT；已发布的 gtars crate 声明 MIT，而 GitHub 仓库根目录当前显示 BSD-2-Clause，再分发前需核实具体产物的许可证。
文档漂移：已发布文档 changelog 止于 0.5.1；部分旧示例（如 gtars.RegionSet、RegionSet.from_bed、TreeTokenizer、gtars.igd.build_index、gtars.uniwig.coverage_from_bed、gtars.RefgetStore、global set_option/set_log_level、parallel_apply 等）以及 CLI 形式（uniwig generate、igd build、scoring score、fragsplit cluster-split）在 0.9.0 中已过时。
Python 0.9.2 未暴露 gtars.uniwig；信号轨道生成需使用 CLI 或 Rust API。RegionSet.coverage() 是碱基对集合度量，不是 WIG/bigWig 生成器。
敏感信息：基因组区间、罕见位点、barcode、样本名、表型与装配选择可能具有可识别性，日志中应避免完整路径与原始坐标。
数据划分：应先按患者/供体冻结划分，再保持技术/生物学重复在同一划分内；共识集、universe、tokenizer、缩放、阈值与 QC 规则仅在训练数据上拟合，避免泄漏。
附带参考文档共六份：references/python-api.md、references/overlap.md、references/coverage.md、references/tokenizers.md、references/refget.md、references/cli.md。
若安装版本中缺少某函数、标志或端点，应查阅该版本自身文档并告知用户，不得臆造 API。