geniml

Geniml

使用 Geniml 对基因组区间集进行机器学习和统计工作流处理。将坐标、组装版本、词元词汇表、模型制品和样本分组视为明确的契约。随附脚本用于验证或规划；它们不会导入 Geniml、联系服务、反序列化模型或执行训练。

仅当用户明确批准本指南中展示的 uv、Python、Geniml、Gtars、Git 和原生命令行命令时，才会使用 Bash；随附的 Python 辅助程序不会生成子进程。data/、refs/、work/ 和 models/ 下的示例路径是用户提供的项目占位符，并非缺失的随附文件。

已验证的发行版快照

• 截至 2026-07-23 的最新稳定 PyPI 发行版：geniml==0.8.4（2026-01-14）。
• PyPI 未声明 Requires-Python；其分类器列出了 Python 3.10-3.14。优先使用 Python 3.11 或 3.12，以确保所有原生／机器学习 wheel 均可解析。
• geniml==0.8.4 接受 gtars>=0.2.5；已验证的基础冒烟测试使用当前版本 gtars==0.9.2（2026-06-17，Python >=3.10）。
• 可选依赖组为 ml 和 test。基础安装不包含 Torch、Gensim、Scanpy、Hugging Face Hub、pyBigWig 和 HMM 依赖项。
• 上游文档中有过时示例。发生冲突时，以发行版源代码和已安装命令的 --help 输出为准。

可复现地安装

使用项目环境，并提交其生成的锁文件：

uv venv --python 3.12
uv pip install "geniml==0.8.4" "gtars==0.9.2"

对于需要机器学习库的 Region2Vec、scEmbed、评估或 universe 方法：

uv pip install "geniml[ml]==0.8.4" "gtars==0.9.2"

对于持久性项目，优先使用：

uv add "geniml[ml]==0.8.4" "gtars==0.9.2"
uv lock

不要安装未固定版本的 Git 分支。记录 Python 版本、操作系统／架构、解析后的锁文件以及 PyPI 制品摘要。Geniml 本身采用 BSD-2-Clause 许可证；前置元数据中的 MIT 值仅用于许可本技能的内容。

先通过安全检查

在导入 Geniml 或运行外部二进制文件之前：

1. 仅处理明确指定的本地常规文件。除非用户有意更改此策略，否则拒绝 URL、FIFO、设备和符号链接。
2. 根据可信的本地染色体长度文件验证 BED 结构和声明的组装版本。
3. 限制文件数量、字节数、行数、工作线程数、epoch 数和输出大小。
4. 按患者、供体、生物学重复或其他独立单位划分训练集、验证集和测试集，而不是按 BED 行或单个细胞划分。
5. 清点并校验 universe、分词器、模型、配置、输入、元数据清单和原生二进制文件的校验和。
6. 任何 BEDbase 或 Hugging Face 下载都必须先获得明确批准。不得根据模型 ID 或 BEDbase 标识符推断用户已批准。
7. 日志只记录有限的汇总信息。BED 文件名、样本 ID、表型、标签、条形码和基因组区间都可能属于敏感信息。

坐标和组装版本契约

BED 区间通常使用 0 起始、左闭右开 坐标 [start, end)：包含起点，不包含终点，长度为 end - start。不要将其与 VCF／GFF 或面向用户的基因组浏览器中的 1 起始闭区间坐标混用。

对于每个数据集和制品，请记录：

• 组装版本及可能的补丁版本／登录号（例如 GRCh38 与 GRCh38.p14），以及染色体长度文件的校验和；
• contig 命名约定（chr1 与 1）、alt／random／decoy 处理策略，以及线粒体命名方式；
• 坐标约定、排序顺序、重复／重叠处理策略，以及 BED 链信息是否有意义；
• liftover 工具、chain 摘要、源／目标组装版本、未映射比例和 liftover 后的验证结果。

拒绝负坐标、end <= start、整数溢出、未知 contig、超出 contig 长度的终点、格式错误的列、混合组装版本以及静默重命名 contig 的情况。排序和规范化都无法修复组装版本不匹配。BED3 不含链信息；如果存在第 6 列，除非检测方法契约另有规定，否则应保留 +、- 或 .。

在分析前，先执行有限范围的验证和规范化规划：

python skills/geniml/scripts/bed_validator.py \
  --input data/peaks.bed \
  --assembly GRCh38 \
  --chrom-sizes refs/GRCh38.chrom.sizes

验证器会报告建议采取的操作，但绝不会改写 BED 文件。

当前 API 一览

区域和分词器 I/O

新编写的区间／分词器代码优先使用 Gtars：

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

regions = RegionSet("data/peaks.bed")
tokenizer = Tokenizer.from_bed("refs/universe.bed")
encoded = tokenizer(regions)
input_ids = encoded["input_ids"]

RegionSet 和 Tokenizer 的某些构造函数也接受远程输入；除非已明确批准网络访问，否则此技能仅允许使用本地路径。geniml.io.RegionSet(regions, backed=False) 仍可作为旧版 Python 实现使用；backed 集合可迭代，但不可索引。geniml.io.Region 使用 stop，而 gtars.models.Region 使用 end。

使用 gtars 0.9.2 时，BED 词汇表中会添加 7 个特殊词元。因此，len(tokenizer) 不等于 universe 行数。请保留 universe 行顺序和精确的特殊词元映射。

Region2Vec

现代类位于一个具体的模块路径：

from geniml.region2vec.main import Region2VecExModel
from geniml.region2vec.utils import Region2VecDataset
from gtars.tokenizers import Tokenizer

tokenizer = Tokenizer.from_bed("refs/universe.bed")
dataset = Region2VecDataset("work/tokens.parquet", shuffle=True)
model = Region2VecExModel(tokenizer=tokenizer, embedding_dim=100)
model.train(dataset, epochs=10, window_size=5, num_cpus=4, seed=42)

Parquet 输入必须包含一个列表类型的 tokens 列，每行对应一篇文档。导出、编码、旧版 CLI 和评估的详细信息请参阅 references/region2vec.md。

scEmbed

从 geniml.scembed.main 导入 ScEmbed。AnnData .var 必须包含 chr、start 和 end；每行对应一个细胞，非零特征表示可访问区域。请预先分词并存入 Parquet 的 tokens 列，训练和推理时使用同一个 Tokenizer。请参阅 references/scembed.md。

BEDspace

BEDspace 在 0.8.4 中仍可用，并会调用外部 StarSpace 可执行文件。StarSpace 已归档，上游 Geniml 未固定兼容的修订版本。请将 BEDspace 视为旧版复现路径，而非新系统的默认选项。确切且稳定的 CLI 拼写，以及不可变但未经明确验证的构建基线，请参阅 references/bedspace.md。

共识 universe 和评估

已安装的 0.8.4 CLI 使用：

geniml build-universe {cc,ccf,ml,hmm} ...
geniml assess-universe ...
geniml eval {gdst,npt,ctt,rct,bin-gen} ...

CC／CCF／ML／HMM 使用预先计算的覆盖度 bigWig。所有 BED 文件通过相同的组装版本约定之前，请勿拼接或生成覆盖度。评估和嵌入指标有所区别：assess-universe 用于衡量 universe 与区间集合的拟合度，而 eval 为嵌入实现 CTT、RCT、GDST 和 NPT。请参阅 references/consensus_peaks.md 和 references/utilities.md。

重要的 0.8.4 迁移说明

• 0.7.0 的变更日志将新的 RegionSet／分词器工作转向 Gtars。
• 0.4.0 中的 TreeTokenizer 和 AnnDataTokenizer 是历史名称；当前 Gtars API 提供 Tokenizer。
• 在 0.8.4 wheel 中，geniml.region2vec 和 geniml.scembed 不会重新导出其现代类／函数。请使用上文所列的具体模块路径。
• geniml tokenize 和 geniml region2vec 调用的名称已不再由各自的包 __init__ 文件导出；未经安装版本的冒烟测试，请勿围绕这些 CLI 路径构建新工作流。
• geniml scembed 会解析旧版 MatrixMarket 选项，但其命令主体在 0.8.4 中为空操作。请使用 geniml.scembed.main.ScEmbed。
• 官方页面仍显示 geniml assess；该版本的命令是 geniml assess-universe。
• .gtok 仍存在于旧版数据集中，但上游 issue #14 提议弃用涉及多个文件的 .gtok 工作流。建议使用一个有界 Parquet 语料库。
• 配置键 embedding_size 仅为向后兼容而接受；请使用 embedding_dim。

模型与基因组兼容性

Region2Vec/scEmbed 推理包只有在以下内容一致时才有效：

• 模型 config.yaml 中的 vocab_size 和 embedding_dim；
• universe.bed 的确切字节内容与顺序，以及组装版本；
• 分词器实现和版本，以及特殊 token ID；
• 检查点张量形状和池化策略；
• Geniml/Gtars 版本及任何分词参数。

Geniml 0.8.4 默认使用 checkpoint.pt、config.yaml 和 universe.bed。 其加载器使用 torch.load(..., weights_only=True)，但 .pt、Gensim .model、pickle、joblib 和原生二进制文件仍属于不可信输入。加载前请检查 制品并校验其哈希；使用隔离环境，切勿仅为查看元数据而加载检查点。

python skills/geniml/scripts/model_artifact_inspector.py \
  --model-dir models/region2vec

python skills/geniml/scripts/tokenizer_compatibility.py \
  --model-dir models/region2vec \
  --universe refs/universe.bed \
  --assembly GRCh38

Region2VecExModel(model_path="org/repo")、ScEmbed(model_path="org/repo") 以及 Gtars Tokenizer.from_pretrained(...) 都可以从 Hugging Face 下载。 本地 from_pretrained("models/local") 会加载本地包。用户批准下载后，请固定 Hub 修订版本 和预期哈希；随后从已验证的缓存离线工作。

BEDbase 下载与缓存

BBClient.load_bed、load_bedset 和 token 缓存操作可能会访问 https://api.bedbase.org。默认缓存位置为 $BBCLIENT_CACHE 或 ~/.bbcache；BEDBASE_API 用于更改端点。不要读取无关的环境变量。请设置明确的项目缓存，估算大小，审批标识符和端点，并在使用前验证返回的校验和。

本地检查命令更安全：

geniml bbclient seek ID --cache-folder /absolute/project/cache
geniml bbclient inspect-bedfiles --cache-folder /absolute/project/cache
geniml bbclient inspect-bedsets --cache-folder /absolute/project/cache

cache-bed、cache-bedset 和 cache-tokens 子命令可能会使用 网络。不要隐式运行这些命令，也不要在上传/缓存工作流中包含敏感的本地 BED 文件。

本地审计与规划 CLI

所有脚本仅使用标准库，默认输出已脱敏的 JSON：

# Audit manifest paths, checksums, assemblies, and patient/donor leakage
python skills/geniml/scripts/corpus_auditor.py \
  --manifest data/manifest.tsv --assembly-column assembly \
  --group-column patient_id --split-column split

# Plan tokenizer/model compatibility checks
python skills/geniml/scripts/tokenizer_compatibility.py \
  --model-dir models/r2v --universe refs/universe.bed --assembly GRCh38

# Plan consensus construction; does not execute Geniml or coverage tools
python skills/geniml/scripts/consensus_plan.py \
  --manifest data/manifest.tsv --chrom-sizes refs/GRCh38.chrom.sizes \
  --assembly GRCh38 --method cc --output-dir work/consensus

# Plan an embedding run; does not import ML libraries
python skills/geniml/scripts/embedding_plan.py \
  --mode region2vec --data work/tokens.parquet \
  --universe refs/universe.bed --output-dir work/r2v \
  --assembly GRCh38

使用 --help 查看资源限制和显式路径披露控制选项。

参考资料

• Region2Vec：现代 API、制品、CLI 差异、 训练、编码和评估。
• scEmbed：AnnData/token 准备、训练、 推理、注释、隐私和数据泄漏。
• BEDspace：元数据架构、精确的旧版 CLI、 StarSpace 状态、制品和检索。
• 共识峰：覆盖率前提条件、 CC/CCF/ML/HMM、评估和组装版本防护。
• 实用工具：I/O、Gtars 分词器、BBClient、 评估、模型安全、迁移和带日期的来源。

来源快照和主要论文链接的日期见 references/utilities.md。更改固定版本前，请重新检查发行版元数据 和已安装的签名。

Agent 操作流程

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

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

完整性规则

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

相关技能

• gtars：检查和规划使用 Gtars（用于基因组区间的 Rust/Python/CLI 工具包）开展的工作：BED RegionSet 集合代数（reduce、setdiff、intersec…
• genomic-coordinates：在不同坐标约定之间转换基因组区间、规范化并比较变异表示，以及检测组装版本或 contig 名称…