findscripter 何时使用
当你手头是基因组区间数据（BED 文件集合、scATAC-seq 染色质可及性、峰集合），并希望用无监督机器学习把区间 / 单细胞 / 元数据标签映射成向量，进而做相似检索、聚类、降维或下游 ML 时，用 geniml。典型场景：
- 给 BED 文件集合学习区间嵌入做特征向量 → Region2Vec
- 区间与元数据（细胞类型、组织、条件）联合嵌入、跨模态检索（区间↔标签）→ BEDspace
- scATAC-seq 单细胞聚类 / 细胞类型注释、与 scanpy 集成 → scEmbed
- 从多份 BED 构建统计严谨的共识峰参考集（universe）→ Consensus Peaks
不该用的边界：geniml 解决的是「区间嵌入 / 共识峰 / 区间级 ML」。若任务是变异检测、序列比对、基因表达定量、motif 扫描、通路富集等非区间嵌入分析，本技能不适用，应改用对应专用工具（GATK、STAR、DESeq2 等）。另外它要求输入为 BED / AnnData 形式的区间坐标；纯序列 FASTA 不是其输入。
步骤
总体顺序：构建 universe → 分词 → 训练 → 评估 / 检索。universe（共识峰参考集）是分词的字典，质量决定一切。
安装
uv pip install geniml # 基础
uv pip install 'geniml[ml]' # 含 PyTorch 等 ML 依赖
uv pip install git+https://github.com/databio/geniml.git # 开发版
1. 构建 universe（共识峰）
四种方法，按统计严谨度递增、算力消耗递增：
- CC（Coverage Cutoff）：阈值法，最简单
- CCF（Coverage Cutoff Flexible）：给边界加置信区间
- ML（最大似然）：对位置做概率建模
- HMM（隐马尔可夫）：复杂状态建模，最重
cat bed_files/*.bed > combined.bed
uniwig -m 25 combined.bed chrom.sizes coverage/ # 生成覆盖度轨道
geniml universe build cc \
--coverage-folder coverage/ \
--output-file universe.bed \
--cutoff 5 --merge 100 --filter-size 50
geniml universe evaluate \
--universe universe.bed \
--coverage-folder coverage/ \
--bed-folder bed_files/
2. Region2Vec：区间嵌入
word2vec 风格无监督学习，三步：分词 → 训练 → 评估。
from geniml.tokenization import hard_tokenization
from geniml.region2vec import region2vec
from geniml.evaluation import evaluate_embeddings
hard_tokenization(src_folder='bed_files/', dst_folder='tokens/',
universe_file='universe.bed', p_value_threshold=1e-9)
region2vec(token_folder='tokens/', save_dir='model/',
num_shufflings=1000, embedding_dim=100)
metrics = evaluate_embeddings(embeddings_file='model/embeddings.npy',
labels_file='metadata.csv')
CLI：geniml region2vec --token-folder tokens/ --save-dir model/ --num-shuffle 1000
3. BEDspace：区间 + 元数据联合嵌入
基于 StarSpace，把区间集与元数据标签嵌入同一空间，支持 r2l（区间查标签）/ l2r 等检索。流程：预处理 → 训练 → 算距离 → 检索。
geniml bedspace preprocess --input regions/ --metadata labels.csv --universe universe.bed
geniml bedspace train --input preprocessed.txt --output model/ --dim 100
geniml bedspace search -t r2l -d distances.pkl -q query.bed -n 10
4. scEmbed：单细胞 ATAC-seq 嵌入
在 scATAC-seq 上训练 Region2Vec 得到细胞级嵌入，与 scanpy 无缝集成。务必先预分词以加速训练。
import scanpy as sc
from geniml.scembed import ScEmbed
from geniml.io import tokenize_cells
adata = sc.read_h5ad('scatac_data.h5ad')
tokenize_cells(adata='scatac_data.h5ad', universe_file='universe.bed', output='tokens.parquet')
model = ScEmbed(embedding_dim=100)
model.train(dataset='tokens.parquet', epochs=100)
adata.obsm['scembed_X'] = model.encode(adata)
sc.pp.neighbors(adata, use_rep='scembed_X')
sc.tl.leiden(adata); sc.tl.umap(adata)
5. 配套工具（Utilities）
- BBClient：缓存远端 BED（BEDbase 仓库），避免重复下载
- BEDshift：保留基因组上下文的随机化，生成统计零模型：
geniml bedshift --input peaks.bed --genome hg38 --preserve-chrom --iterations 100 - Evaluation：嵌入质量指标（silhouette、Davies-Bouldin 等）
- Tokenization：hard / soft / universe-based 多种分词
- Text2BedNN：基因组查询的神经检索后端
示例
选型速查：
- 批量数据（ChIP-seq / ATAC-seq）、无元数据、跨实验比较区间集 → Region2Vec
- 有元数据标签、要按标签查区间或反查、建可检索基因组库 → BEDspace
- 单细胞 ATAC-seq 聚类 / 细胞类型注释、要接 scanpy → scEmbed
- 需要分词参考集、把多实验合成共识、要统计严谨的区间定义 → Universe Building
- 缓存远端 BED / 造零模型 / 评估嵌入 / 建检索接口 → Utilities
注意事项
- universe 质量是命门：分词覆盖率理想 >80%，训练前先核验。
- 基因组版本要对齐：universe 与数据的 assembly 必须一致（如都是 hg38），否则分词覆盖率会崩。
- 可复现：记录所有参数与随机种子。
- 算力：ML / HMM 的 universe 方法很重；scEmbed 大数据集要分批或降采样。
- 常见报错排查：
- 「分词覆盖率过低」→ 检查 universe 完整性，p 值阈值放宽（1e-9 → 1e-6），确认 assembly 一致。
- 「训练不收敛」→ 学习率调到 0.01–0.05，增大 epoch，检查预处理。
- 「内存溢出」→ scEmbed 减小 batch、分块、用预分词。
- 「StarSpace not found」（BEDspace）→ 单独装 StarSpace，正确设置
--path-to-starspace。
- 集成：scEmbed 嵌入直接进
adata.obsm；远端仓库用 BBClient；模型可导出到 Hugging Face（databio 组织）分享；R 端可用 reticulate。
互见
- 生态：BEDbase（统一区间平台）、BEDboss（BED 处理流水线）、Gtars（基因组工具）、BBClient（仓库客户端）。
- 文档：https://docs.bedbase.org/geniml/ ，源码：https://github.com/databio/geniml ，预训练模型在 Hugging Face（databio）。
- 同领域可对照其他单细胞 / 基因组嵌入技能（scanpy 工作流、共识峰构建相关条目）。
采编自 K-Dense-AI/scientific-agent-skills（MIT）。