Gtars Python API 0.9.2 完全指南基因组区间模型、集合代数、Tokenization 与 refget 实操解析【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skillsGtars 是一套面向基因组区间genomic interval与参考序列处理的原生 Rust 实现其 Python 绑定gtars0.9.2通过 PyO3 扩展提供了Region、RegionSet、Tokenizer、RefgetStore等核心对象。本文以仓库内 python-api.md 为骨架结合 SKILL.md、overlap.md、tokenizers.md、refget.md 以及 bed_validator.py 等源码与测试系统梳理 0.9.2 的精确导入面、已验证签名、构造规则、集合代数语义、consensus 实现、tokenizer 边界与错误处理约定帮助你避免踩中旧版文档与真实运行时之间的 API 漂移陷阱。版本基线与环境前提本文所有结论均针对gtars0.9.2研究核验日期 2026-07-23。该 PyPI 包要求Python 3.10且轮子内含PyO3 原生扩展——安装即意味着执行原生代码因此仓库 SKILL.md 强调先核验官方发布者的不可变版本、平台标签、许可证与 SHA-256再在隔离环境中安装。推荐的隔离安装与版本断言流程如下uv venv --python 3.11 .venv-gtars uv pip install --dry-run --python .venv-gtars/bin/python gtars0.9.2 uv pip install --python .venv-gtars/bin/python gtars0.9.2 .venv-gtars/bin/python -c \ import gtars; assert gtars.__version__ 0.9.2; print(gtars.__version__)版本事实速览来自 SKILL.md 的 Verified snapshotPython 绑定gtars0.9.2Requires-Python 3.10Rust meta-crategtars0.9.0默认 feature 集为空CLI 二进制gtars-cli0.9.0安装后命令名为gtars直接引用的 refget 组件gtars-refget0.9.1。上游刻意让 workspace crates、Python 绑定与 CLI 独立版本化不要假设数字相同就是同一产物。Import surface功能挂在子模块而非顶层gtars0.9.2 的公开功能按子模块组织官方文档和 0.9.2 stubs 推荐如下导入方式import gtars from gtars.models import Region, RegionSet from gtars.genomic_distributions import consensus from gtars.tokenizers import Tokenizer, tokenize_fragment_file from gtars.refget import RefgetStore, digest_fasta, digest_sequence关键事实gtars.__version__为0.9.2Region、RegionSet、Tokenizer、RefgetStore不是顶层导出类必须从子模块导入Python 0.9.2不导出uniwig、igd、scoring、fragsplit、bbcache等 Python 子模块。信号轨道signal track生成等能力请走 CLI 或 Rust API而不是在 Python 里寻找gtars.uniwig。已验证的方法签名清单0.9.2 轮子在运行时报告的签名如下python-api.md 的 Verified signatures 段Region(chr, start, end, rest) RegionSet(path) RegionSet.from_regions(regions, strandsNone) RegionSet.from_vectors(chrs, starts, ends, strandsNone) RegionSet.count_overlaps(self, other) RegionSet.coverage(self, other) Tokenizer(path) Tokenizer.from_bed(path) Tokenizer.from_pretrained(path) tokenize_fragment_file(file, tokenizer) consensus(region_sets) RefgetStore.open_local(path) RefgetStore.open_remote(cache_path, remote_url) RefgetStore.get_substring(self, seq_digest, start, end)一个值得注意的细节随轮子分发的.pyistub 文件遗漏了部分运行时方法如from_vectors、disjoin、strands以及若干 refget 加载方法。核验此类遗漏时应以标签版本tagged的 PyO3 源码与实际安装的运行时为准而不是只信 stub。Region最小区间单元Region是表示单个 BED 区间的核心对象from gtars.models import Region region Region( chrchr1, start100, end200, restpeak_001\t500\t, ) assert len(region) 100 assert (region.chr, region.start, region.end) (chr1, 100, 200)语义要点start与end是 Rust 的u32构造前应自行验证0 start end contig_length构造函数本身不证明assembly 或 contig 兼容性它只承载数据不负责数据契约相等性仅比较 chr/start/end尾部rest内容不参与相等判断——这意味着两条坐标相同但注释不同的区间会被视为相等做去重或集合运算时要留意。RegionSet 的构造方式从本地文件构造from pathlib import Path from gtars.models import RegionSet path Path(reviewed-input.bed.gz) if not path.is_file() or path.is_symlink(): raise ValueError(expected a reviewed local regular file) regions RegionSet(str(path))这里is_file()检查不只是错误提示的改进而是一道安全边界Python 构建启用了gtars-core的 HTTP feature当传入字符串不是已存在的本地文件时core 代码会尝试把它当作 URL 打开。因此构造前必须确认路径是本地常规文件避免意外触发网络访问。文件解析规则来自 python-api.md接受制表符分隔的 BED 类输入与.gz压缩文件跳过browser、track、#行若首行第二字段非数字视为列头column header至少需要三列第 4 列及之后的所有列合并为一个以制表符连接的Region.rest字符串拒绝空区间集合加载时在内存中按「染色体字典序 start 数值序」排序。注意原文件不会被改写但输入行序不会保留在对象中。因此如果你需要把查询结果与原始行号对齐必须自行携带稳定标识符而不能依赖构造后的索引位置。从内存区间构造from gtars.models import Region, RegionSet regions RegionSet.from_regions( [ Region(chr1, 100, 200, None), Region(chr2, 300, 450, None), ], strands[, -], ) same RegionSet.from_vectors( [chr1, chr2], [100, 300], [200, 450], strands[, -], )约束所有坐标向量以及可选的 strand 向量长度必须相等省略 strands 时独立的 strand 向量会被初始化为*。注意文件构造的RegionSet目前也会把独立 strand 向量初始化为*即使 BED6 里有真实链向所以当链向在科学上重要时需要在外部单独保留与验证。属性与可变性n len(regions) first regions[0] # 支持负索引 identifier regions.identifier file_digest regions.file_digest header regions.header strands regions.strands regions.sort() # in-place返回 None regions.to_bed(out.bed) regions.to_bed_gz(out.bed.gz) regions.to_bigbed(out.bb, assembly.chrom.sizes)identifier是对排序后的前三维内容计算的 MD5 类标识file_digest则包含被保留的尾部列。两者都不能替代独立记录的 SHA-256 溯源哈希由 regions/vectors 构造的集合其path属性会抛出ValueError所有写出方法都会覆盖/创建指定输出文件先确认输出策略再调用to_bigbed需要与每个 contig 及区间边界匹配的染色体长度文件。区间统计与结构操作widths regions.widths() # list[int] same_widths regions.region_widths() # 别名 mean_width regions.mean_region_width() # 运行时返回 float length regions.get_nucleotide_length() max_ends regions.get_max_end_per_chr() stats regions.chromosome_statistics() reduced regions.reduce() disjoint regions.disjoin() trimmed regions.trim({chr1: 248956422}) gaps regions.gaps({chr1: 248956422}) clusters regions.cluster(max_gap100)几个必须牢记的语义细节reduce()合并重叠且相邻的区间——相邻adjacent也合并这与普通 half-open 重叠[0,10)与[10,20)不重叠是两个不同的判定标准trim()会丢弃未知 contig 并夹紧越界端点这些变换不做 liftover且可能丢掉独立的 strand 向量promoters(upstream, downstream)目前是相对于每个区间 start 计算的不是链向感知的 TSS 替代方案需要链向语义时请独立建立 TSS 工作流neighbor_distances()与nearest_neighbors()因为会跳过染色体上的单例区间返回数量可能少于输入区间数结果不是按行对齐的distribution(n_bins250, chrom_sizesNone)在缺少染色体长度时使用观测到的最大 end导致不同文件之间的结果不可比务必传入精确的 assembly 字典。传入 sizes 时未知/越界区间会被跳过因此求和计数可能低于输入计数。两两与全对all-vs-all操作a RegionSet(a.bed) b RegionSet(b.bed) concatenated a.concat(b) # 不合并 union a.union(b) # 最小合并集 difference a.setdiff(b) # 从 a 中减去 b 的碱基 pairwise a.pintersect(b) # 按索引配对而非基因组全对 all_pieces a.intersect_all(b) # 每个基因组重叠片段 jaccard a.jaccard(b) coverage a.coverage(b) coefficient a.overlap_coefficient(b) closest a.closest(b)指标口径详见 overlap.mdJaccard intersection_bp / union_bpcoveragea 中被覆盖的碱基对 / a 合并后的碱基对取值在[0,1]。它是碱基对集合度量不是信号覆盖度也不会产出 WIG/bigWigoverlap coefficient intersection_bp / min(query_bp, universe_bp)concat不合并union会合并setdiff可能把查询区间拆开pintersect依赖构造器排序后的索引位置配对不是基因组全对相交。重叠查询方法是有方向性的counts a.count_overlaps(b) # 对 a 中每个区间返回一个整数 flags a.any_overlaps(b) # 对 a 中每个区间返回一个布尔 indices a.find_overlaps(b) # 对 a 中每个区间返回 b 中的索引 subset a.subset_by_overlaps(b) # 只保留至少命中一次的 a 区间counts[i]是与查询区间i重叠的 universe 区间数量hit_indices[i]是内存中 universe 的 0-based 索引文件构造的两侧集合都会被构造器排序因此不要把这些数组直接对回原始未排序行号。Consensus共识区间语义consensus是gtars.genomic_distributions模块的绑定from gtars.genomic_distributions import consensus result consensus([a, b]) # [{chr: chr1, start: 100, end: 500, count: 2}, ...]算法实现overlap.md 与 python-api.md 一致拼接所有集合reduce 成非重叠的合并 union 区间包含相邻合并对每个 union 区间统计有多少个输入集合至少重叠一次返回 BED4 形式的chr, start, end, count按染色体/start 排序。关键理解consensus不会在每个支持度变化的边界处切分区间。例如部分重叠的[0,10)与[5,15)会得到 union[0,15)且 count2尽管两侧边缘实际只有一个集合支持。这是合并 union 组件的集合级支持数不是 per-base 支持度。在解释count时必须使用这个精确含义。Tokenizer 与片段边界Tokenizer.tokenize()接受RegionSet或原生 extractor 接受的 region 对象from gtars.tokenizers import Tokenizer tokenizer Tokenizer.from_bed(local-universe.bed) tokens tokenizer.tokenize(a) ids tokenizer(a)[input_ids]兼容性陷阱虽然旧版文档有字符串列表示例但已验证的 0.9.2 轮子拒绝[chr1:100-200]这类字符串列表因为原生 extractor 期望 region 对象。请传入RegionSet或Region对象。Tokenizer(path)构造函数只自动识别.toml、.bed、.bed.gz三种文件本地构造器读取本地文件并构建内存重叠索引。重叠索引会返回与每个查询区间重叠的所有universe 区间因此一次查询可能产出 0、1 或多个 region token若整体无重叠则返回 unknown token未知 contig 同样落入 unknown 行为。关于特殊 token、universe 顺序、远程下载与 fragment 文件行为的完整细节见 tokenizers.md。几个核心事实Tokenizer.from_config期望TOML非 YAML配置形如universe universe.bed.gz可选tokenizer_type bits或ailist默认bits默认特殊 token 角色为unk, pad, mask, cls, bos, eos, sep对 N 行唯一 universe测试实现得到N 7个词表条目不要硬编码来自其他 universe 的 IDTokenizer.from_pretrained(name)在参数不是已存在本地目录时会访问 Hugging Face 并写入缓存且签名不暴露 revision/cache 参数——默认不要直接调用应先批准宿主、锁定不可变 revision、校验 SHA-256 后传入本地快照目录。片段fragmenttokenization 的当前绑定是from gtars.tokenizers import Tokenizer, tokenize_fragment_file tokenizer Tokenizer.from_bed(training-universe.bed) by_barcode tokenize_fragment_file(fragments.tsv.gz, tokenizer) # dict[str, list[int]]tagged 实现要求每行至少 5 个空白分隔字段chrom start end barcode count只使用前四维第五个 count 字段被忽略每个 barcode 列表会保留重复 ID——这与按 count 展开权重不同使用前要确认这是否是你想要的加权方式。该函数会把所有 barcode 与 token 列表累积在内存中处理单细胞数据前务必设置压缩/展开字节、行数、去重 barcode 数、每行 token 数等上限。错误处理约定0.9.2 包不导出旧版 skill 中虚构的gtars.FileNotFoundError、InvalidFormatError、ParseError异常类。正确的做法是先验证、再只捕获与操作相关的窄内置/原生错误try: regions RegionSet(reviewed-local.bed) except (OSError, RuntimeError, ValueError) as exc: raise RuntimeError(Gtars could not load the validated BED) from exc不要用宽泛的except吞掉损坏行继续跑——数据契约问题应当失败并暴露。0.9.2 中不存在的 API 清单迁移旧代码时务必对照以下清单python-api.md 的 APIs that are not presentgtars.RegionSet顶层或RegionSet.from_bed旧名下的total_coverage、filter_by_size、filter_by_chromosome、intersect、subtract、symmetric_differenceto_json、from_json、NumPy 数组 getter、from_arraysstream_bed、mmapTrue、parallelTrue、parallel_apply全局set_option、option_context、set_log_levelPython 的uniwigcoverage 对象。SKILL.md 的 Migration traps 段还补充gtars.RegionSet、RegionSet.from_bed、TreeTokenizer、gtars.igd.build_index、gtars.uniwig.coverage_from_bed、gtars.RefgetStore应为gtars.refget.RefgetStore等旧示例对 0.9.2 均已失效CLI 的uniwig generate、igd build、scoring score、fragsplit cluster-split对 0.9.0 也已过时。仓库配套本地验证工具与测试佐证数据契约先行在使用任何 Python API 之前仓库 SKILL.md 强制要求先明确基因组数据契约坐标BED 为 0-based、half-open[start, end)要求0 start end contig_lengthGtars 坐标为u32拒绝超过4,294,967,295的值scripts/_common.py 中MAX_COORDINATE 2**32 - 1正是这一约束的实现Assembly记录 accession/版本与染色体长度文件或序列集合元数据的 SHA-256禁止从文件名或chr前缀推断Contig名称精确比较1与chr1、alt 位点、decoy、线粒体别名都不可互换排序保留原文件按需对副本排序PythonRegionSet(path)目前按字典序加载并排序链向BED6 使用/-/.但文件构造的 PythonRegionSet独立 strand 向量初始化为*且若干集合操作会丢链向重复/相邻显式选择策略reduce()与 consensus 合并重叠且相邻区间。本地校验器 bed_validator.py在构造RegionSet之前可以先用仓库自带的依赖无关校验器做本地预检bed_validator.pypython3 -B scripts/bed_validator.py \ --input data.bed.gz \ --assembly GRCh38.p14 \ --chrom-sizes GRCh38.p14.chrom.sizes \ --require-sorted该脚本只使用 Python 3.10 标准库、无网络、不写输出文件并拒绝 URL、路径穿越、符号链接与特殊文件scripts/_common.py。它的默认上限为 512 MiB 字节与 1,000,000 条记录--require-sorted会按 chrom.sizes 顺序加数值 start/end 检查排序输出 JSON 报告且默认--path-mode redacted隐去路径、只报告计数与校验和防止基因组坐标与样本路径泄漏。测试用例如何佐证 API 语义仓库 tests/gtars/test_scripts.py 提供了不依赖 gtars 导入的合成测试可作为理解 API 边界的最佳注脚test_valid_local_bed合法 BED 校验通过、记录数为 2、输出不包含临时根目录路径路径脱敏验证test_bad_bounds_and_url_are_rejectedchr1\t90\t101end 超出 contig 长度返回码 2 且报end_beyond_contigURL 输入被拒绝且不泄漏文件名——这与RegionSet(path)的 HTTP 语义形成对照test_tokenizer_manifest_matches_exact_universe2 行 universe 对应vocab_size 9即 N7且校验universe 字节与顺序完全匹配证实 token ID 对 universe 行内容与顺序字节级敏感test_refget_digest_validation_uses_known_acgt_digest对ACGT计算sha512t24u得到已知值验证序列摘要语义test_wheel_filename_and_checksum_are_screened_without_loading校验轮子文件名与 SHA-256 清单时不加载原生代码、不解压归档呼应原生扩展即代码执行的信任门。refget 摘要与存储补充虽然 python-api.md 只列出RefgetStore.open_local、open_remote、get_substring三个签名完整构造器集合见 refget.mdin_memory()、on_disk(cache_path)、open_local(path)、open_remote(cache_path, remote_url)、store_exists(path)。摘要函数包括from gtars.refget import ( digest_fasta, digest_sequence, md5_digest, sha512t24u_digest, ) digest sha512t24u_digest(ACGT) assert digest aKF498dAxcJAqme6QYQ7EZ07-fiw8Kw2 assert md5_digest(ACGT) f1f8f4bf413b16ad135722aa4591043eGtars 返回不带前缀的 32 字符sha512t24u值GA4GH refget 官方 ID 会加上SQ.前缀SQ.aKF498dAxcJAqme6QYQ7EZ07-fiw8Kw2。open_remote默认启用持久化、可做按需远程字节区间读取但没有任何 revision/校验和/离线参数——调用前必须经过网络与缓存审批门。一个端到端的本地工作流示例综合以上 API 与仓库配套工具一个合规的本地工作流可以组织为# 1. 数据契约预检无网络、无输出文件 python3 -B scripts/bed_validator.py \ --input peaks.bed.gz --assembly GRCh38.p14 \ --chrom-sizes GRCh38.p14.chrom.sizes --require-sorted # 2. 干跑式执行计划固定 argv 模板绝不真正启动命令 python3 -B scripts/execution_plan.py \ --operation overlap --query query.bed --universe universe.bed \ --assembly GRCh38.p14 --chrom-sizes GRCh38.p14.chrom.sizesfrom gtars.models import Region, RegionSet from gtars.genomic_distributions import consensus from gtars.tokenizers import Tokenizer query RegionSet.from_regions( [Region(chrchr1, start100, end200, restNone)], strands[], ) universe RegionSet.from_vectors( [chr1, chr1], [150, 500], [350, 600] ) counts query.count_overlaps(universe) # 每个查询区间一个整数 flags query.any_overlaps(universe) # 每个查询区间一个布尔 pieces query.intersect_all(universe) # 每个重叠片段 [max(starts), min(ends)) fraction query.coverage(universe) # 查询区间被覆盖的碱基比例 rows consensus([query, universe]) # BED4: chr, start, end, count tokenizer Tokenizer.from_bed(reviewed-universe.bed) encoding tokenizer(query) # 重叠 tokenization 编码 ids encoding[input_ids]总结Gtars Python 0.9.2 提供了完整、高性能的基因组区间建模能力但其 API 面与旧版文档存在多处漂移功能从子模块导入、文件构造即排序、reduce/consensus 合并相邻区间、tokenizer 只接受 region 对象、异常类不做包装、若干旧 API 已整体移除。在使用前务必以 python-api.md 的签名清单与本文整理的行为细节为准并结合 SKILL.md 的数据契约、bed_validator.py 的本地预检与 test_scripts.py 的语义验证在隔离环境中对目标版本做一次签名冒烟测试再进入正式分析流程。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考