gtars

Gtars

Gtars 提供原生 Rust 实现、Python 绑定，以及通过功能特性门控的 gtars 二进制文件，用于基因组区间和参考序列处理。请先使用内置的本地检查工具；只有在数据契约、溯源信息、资源限制和副作用都明确后，才调用上游代码。

已验证快照（2026-07-23）

• Python：gtars==0.9.2，于 2026-06-17 发布，Requires-Python >=3.10。
• Rust 元 crate：gtars=0.9.0，于 2026-06-15 发布。其默认功能集为空。
• CLI crate/二进制文件：gtars-cli=0.9.0；安装后的二进制文件名为 gtars。
• 直接 refget crate：gtars-refget=0.9.1，于 2026-06-17 发布。gtars=0.9.0 本身会固定其组件发布版本集，其中包括 refget 0.9.0。
• 上游有意对工作区 crate、Python 绑定和 CLI 分别进行版本管理。不要认为版本号相同就意味着构件相同。
• 已发布文档中的变更日志截至 0.5.1。此处的 API 示例已根据 0.9.2 Python 存根/运行时以及 v0.9.0 CLI/Rust 源码进行核验。

license: MIT 字段适用于此技能。已发布的 gtars crate 声明使用 MIT 许可证，但 GitHub 仓库根目录当前显示 BSD-2-Clause；再分发前请核实确切构件的许可证。

原生代码信任门槛与精确固定版本

Python wheel 包含 PyO3 原生扩展。Cargo 安装会编译原生二进制文件，并可能运行依赖项构建脚本。请将这两种路径都视为代码执行：

1. 确认官方 PyPI/crates.io/GitHub 所有者和不可变版本。
2. 检查文件名、平台标签、发布来源、许可证和 SHA-256。GitHub 的 v0.9.0 二进制发布包含各归档文件对应的 .sha256 旁车文件。
3. 切勿运行不可信的预编译二进制文件、wheel、源代码树、Cargo 构建脚本或归档安装程序。请使用隔离环境，并限制 CPU/RAM/磁盘/运行时间。
4. 将锁文件和构件哈希与分析清单一并保存。

完成审查后，创建隔离的 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 项目，请精确固定包装 crate 的版本，并仅启用必需的功能：

[dependencies]
gtars = { version = "=0.9.0", default-features = false, features = [
  "core", "overlaprs", "uniwig", "tokenizers", "refget"
] }

只有在需要更新的直接组件 API 且已测试兼容性时，才直接使用 gtars-refget = "=0.9.1"。不要将这些固定版本替换为 Git 分支或未经审查的发布版本。

基因组数据契约

每次操作前都应用此契约：

1. 坐标： BED 区间采用从 0 开始、左闭右开的格式：[start, end)。要求 0 <= start < end <= contig_length。Gtars 坐标为 u32，因此超出 4,294,967,295 的值必须拒绝。
2. **组装版本：**记录组装版本登录号/版本，以及确切染色体大小或 refget 序列集合元数据的 SHA-256。切勿根据文件名或 chr 前缀推断组装版本。
3. **Contig：**严格比较名称。1 和 chr1、替代位点、诱饵序列以及线粒体别名不可互换。重命名或 liftover 只能作为单独审查的转换操作。
4. **排序：**保留原始文件；当操作有此要求时，按染色体大小文件中的顺序以及数值型起始/结束坐标对副本排序。Python RegionSet(path) 当前会在加载时按 contig 和起始坐标的字典序排序；之后不要依赖原始行顺序。
5. **链方向：**BED6 使用 +、- 或 .。Region.rest 会保留尾部 BED 字段，但基于文件的 Python RegionSet 当前会将单独的 strands 向量初始化为 *。一些集合操作会丢弃链方向信息。如果链方向在科学上有意义，请在外部保留并验证。
6. 重复项/相邻区间：明确选择处理策略。reduce() 和共识操作会合并重叠及相邻区间；普通的半开区间重叠判定不会将 [0,10) 和 [10,20) 视为重叠。

先运行本地验证器：

python3 -B scripts/bed_validator.py \
  --input data.bed.gz \
  --assembly GRCh38.p14 \
  --chrom-sizes GRCh38.p14.chrom.sizes \
  --require-sorted

安全的本地工作流

1. 清点本地文件、校验和、组装、contig 字典、坐标 系统、链策略、患者/重复组以及预期输出。
2. 验证 BED/片段并估算工作量。先用小型合成文件进行试运行。
3. 根据文档说明选择 Python、CLI 或 Rust；不要凭猜测翻译 API 名称。
4. 为输入字节数/记录数/文件数、线程/作业数、内存、临时 磁盘、输出大小和运行时间设置硬性限制。
5. 在专用输出目录中运行。除非已明确批准覆盖，否则拒绝文件冲突。
6. 重新验证输出排序、边界、行数、校验和和来源信息。

当前 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)       # one count per query region
flags = query.any_overlaps(universe)          # one bool per query region
indices = query.find_overlaps(universe)       # indices into universe
pieces = query.intersect_all(universe)        # all intersection fragments
fraction = query.coverage(universe)           # fraction of query bp covered

RegionSet.sort() 会修改对象并返回 None。集合运算包括 reduce、 setdiff、pintersect（按索引配对）、concat、union、jaccard、 coverage、overlap_coefficient、intersect_all、closest、cluster 和 gaps。依赖排序或链信息之前，请先阅读 references/python-api.md。

共识功能绑定在另一个模块中：

from gtars.genomic_distributions import consensus

rows = consensus([query, universe])
# rows: [{"chr": ..., "start": ..., "end": ..., "count": ...}, ...]

在 Python 0.9.2 中，信号轨道生成并未通过 gtars.uniwig 暴露； 请使用经过审查的 CLI 或 Rust API。RegionSet.coverage() 是碱基对集合指标， 并非 WIG/bigWig 生成器。

分词器、片段和参考存储

默认仅使用本地构造函数：

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

tokenizer = Tokenizer.from_bed("reviewed-universe.bed")
regions = RegionSet("local-query.bed")
tokens = tokenizer.tokenize(regions)
encoding = tokenizer(regions)
ids = encoding["input_ids"]

如果参数不是现有本地目录，Tokenizer.from_pretrained(name) 会联系 Hugging Face 并写入其缓存；它不提供 revision 或缓存参数。请先获得明确批准，通过经过审查的机制获取不可变版本，验证校验和，然后传入本地快照目录。参见 references/tokenizers.md。

对于 refget，优先使用 RefgetStore.in_memory() 或 RefgetStore.open_local(path)。 open_remote(cache_path, remote_url) 会联系远程服务、创建/使用本地缓存，并按需执行范围读取。参见 references/refget.md。

网络和缓存审核

此技能不会隐式下载或写入缓存。进行任何具备联网能力的上游调用之前：

• 针对确切的主机、端点、数据和缓存，获得用户明确批准；
• 将 HTTPS 主机列入允许列表，并拒绝未经审核的重定向；
• 记录不可变版本/标识符、获取时间、预期 SHA-256 和领域摘要、组装登录号、大小配额及来源信息；
• 说明可能离开获批环境的敏感 BED 坐标、条形码、样本标签和参考选择；
• 将下载内容视为不可信内容进行验证后再使用。

重要副作用：

• RegionSet(path) 支持 HTTP；不存在的本地字符串可能会被视为 URL。构造之前，请检查本地路径是否存在。
• Tokenizer.from_pretrained 可能会将 universe.bed.gz 下载到 Hugging Face 缓存。
• RefgetStore.on_disk 会创建/写入存储。open_remote 会加载远程元数据，并默认启用持久化。
• 即使在构造客户端时，gtars bbcache 也会创建缓存目录。缓存/下载命令使用 BBCLIENT_CACHE（默认值为 ~/.bbcache）和 BEDBASE_API（默认值为 https://api.bedbase.org）。

敏感元数据与泄露

基因组区间、罕见位点、条形码、样本名称、表型和组装选择都可能用于身份识别。不要将完整路径和原始坐标写入日志；默认情况下，捆绑报告会对路径脱敏，仅输出计数/校验和。

先按患者/供体固定数据划分，然后将所有技术和生物学重复保留在同一划分中。仅使用训练数据拟合共识集合、全集、分词器、缩放参数、阈值和 QC 规则。不要先根据所有样本创建全集再进行划分：这会泄露验证集/测试集的位点支持信息。分别记录排除的样本和重复聚合情况。

Bundled deterministic CLIs

这六个辅助工具都会拒绝 URL、路径遍历、符号链接和特殊文件；对字节数、记录数、文件数、坐标和工作进程数设置上限；不使用网络或导入 gtars；也不会写入任何输出文件。计划包含固定的 argv 模板，且绝不会启动这些模板。

python3 -B scripts/bed_validator.py --help
python3 -B scripts/execution_plan.py --help
python3 -B scripts/tokenizer_manifest.py --help
python3 -B scripts/refget_digest_plan.py --help
python3 -B scripts/coverage_preflight.py --help
python3 -B scripts/artifact_inspector.py --help

运行合成测试，不生成字节码：

PYTHONDONTWRITEBYTECODE=1 python3 -B -m unittest discover \
  -s tests/gtars -p 'test_*.py' -v

1.1 中移除的迁移陷阱

不要使用包含 gtars.RegionSet、RegionSet.from_bed、TreeTokenizer、gtars.igd.build_index、gtars.uniwig.coverage_from_bed、gtars.RefgetStore、全局 set_option/set_log_level、parallel_apply 或虚构异常类的过时示例。uniwig generate、igd build、scoring score 和 fragsplit cluster-split 等 CLI 用法对于 0.9.0 也已过时。

上游发布的文档和存根存在一些差异（例如较旧的 GlobalRefgetStore 教程和不完整的 0.9.2 存根）。如果出现冲突，请优先参考已安装版本的签名冒烟测试和不可变的标签源代码。

随附参考资料

以下是随附的仅有六份参考资料；所有链接均为本地链接且均存在：

• references/python-api.md — Python 0.9.2 的确切导入方式和行为
• references/overlap.md — 重叠、计数、集合代数和共识语义
• references/coverage.md — uniwig、bigWig、覆盖度、排序和资源
• references/tokenizers.md — 分词器、宇宙定义和片段兼容性
• references/refget.md — 摘要、存储、BEDbase、网络和缓存控制
• references/cli.md — CLI 0.9.0 命令、功能和迁移

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组／注释版本和输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 先在小型子集上运行流水线（一个样本、一条染色体、几千个细胞）。
4. 执行完整任务， 使用以上说明和参考资料。
5. 验证结果。 在解读结果之前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请执行此操作
输入之间的基因组版本或标识符不匹配	停止并统一数据（liftover、ID 映射）后再继续。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），进行调整并告知用户。绝不要虚构 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所采用的假设。

完整性规则

• 绝不捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请直言说明。
• 不要解读超出统计结果支持范围的生物学意义；报告多重检验校正。
• 此处与版本相关的细节可能已经过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，必须先征求同意。

相关技能

• geniml：使用 Geniml（0.8.4）和 Gtars 规划并审查本地基因组区间机器学习工作流：根据染色体 si… 验证 BED 文件
• polars-bio：用于基因组区间操作和生物信息学文件 I/O 的 Python 库，面向 Polars DataFrame 构建，基于 Arrow 和 DataFusion。
• genomic-coordinates：在坐标约定之间转换基因组区间，规范化并比较变异表示形式，以及检测组装版本或 contig 名称…