geniml

用途

Geniml 用于对基因组区间集合（genomic interval sets）进行机器学习与统计工作流。本技能围绕 Geniml 0.8.4 与 Gtars 提供规划与审计能力，把坐标、装配版本、token 词表、模型产物和样本分组视为显式契约。内置脚本只做校验或规划，不导入 Geniml、不联系外部服务、不反序列化模型、也不执行训练。

主要能力

BED 校验与规范化规划：对照可信的本地染色体大小文件，校验 BED 结构与声明的装配版本，报告建议动作但不改写 BED 文件。
语料审计：审计清单路径、校验和、装配版本，以及患者/供体泄漏（按独立单元划分 train/validation/test）。
分词器与模型兼容性检查：核对模型 config.yaml 的 vocab_size 与 embedding_dim、universe.bed 的字节/顺序与装配、分词器实现与特殊 token ID、checkpoint 张量形状等。
共识区间构建规划：规划 CC/CCF/ML/HMM 方法，不执行 Geniml 或覆盖度工具。
嵌入运行规划：规划 Region2Vec 等嵌入运行，不导入 ML 库。
模型产物检查：检查并校验模型目录中的产物，避免仅为读取元数据而加载 checkpoint。

使用方式

安装（可复现）：

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

需要 Region2Vec、scEmbed、评估或 universe 等 ML 方法时：

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

BED 校验示例：

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

语料审计、兼容性检查、共识规划、嵌入规划等脚本均以标准库实现，默认输出脱敏 JSON，可用 --help 查看资源限制与路径披露控制。

Region2Vec 现代 API 示例：

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)

适用场景

需要可复现、可审计的基因组区间机器学习项目。
在训练前校验 BED 与装配一致性、防止样本泄漏。
规划 Region2Vec、scEmbed、共识区间与嵌入评估流程。
检查模型、分词器与 universe 的兼容性。

限制与注意事项

内置脚本不执行训练、不导入 Geniml、不联网、不反序列化模型。
仅允许显式本地常规文件；除非用户明确更改策略，否则拒绝 URL、FIFO、设备与符号链接。
任何 BEDbase 或 Hugging Face 下载都需用户明确批准，不得从模型 ID 或 BEDbase 标识推断批准。
BED 区间通常为 0-based 半开区间 [start, end)，不要与 VCF/GFF 或浏览器的 1-based 闭区间混用。
排序与规范化不能修复装配不匹配。
上游文档存在过时示例，发布源码与已安装版本的 --help 输出优先。
0.8.4 中 geniml.region2vec 与 geniml.scembed 不再重新导出其现代类/函数，需使用具体模块路径；geniml scembed 命令体在 0.8.4 中为空操作，应使用 geniml.scembed.main.ScEmbed；官方页面仍显示 geniml assess，实际发布命令为 geniml assess-universe。
BEDspace 依赖已归档的 StarSpace 外部可执行文件，应视为遗留复现路径。
模型与 universe 兼容性需多项一致（config、universe 字节/顺序、分词器版本与特殊 token、checkpoint 形状、Geniml/Gtars 版本）。
涉及费用、共享 GPU/云配额、个人或患者数据、不可撤销操作时，须先征得同意。
版本相关细节可能过时，应以已安装版本的官方文档为准。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项