alterlab-geniml

Geniml：基因组区间机器学习

概述

Geniml 是一个 Python 软件包，用于基于 BED 文件中的基因组区间数据构建机器学习模型。它提供无监督方法，用于学习基因组区域、单细胞和元数据标签的嵌入，从而支持相似性搜索、聚类和下游机器学习任务。

何时使用此技能

在基因组区间上执行机器学习时使用此技能：训练或应用 Region2Vec / scEmbed / BEDspace 嵌入、为分词构建共识全集、根据区域标记对 scATAC-seq 细胞进行聚类，或使用 BEDshift 零模型和 BBClient 缓存。

不适用场景

场景	改用
常规区间运算——重叠、jaccard、IGD、uniwig 轨道、refget 摘要	alterlab-gtars
标准 scRNA-seq 质控 → 聚类 → 标记基因流程	alterlab-scanpy
深度生成式单细胞整合（scVI / MultiVI / PeakVI）	alterlab-scvi-tools
从 BAM 生成归一化覆盖轨道、TSS 热图	alterlab-deeptools

安装

已针对 geniml 0.8.4 验证（截至 2026-09 仍是当前版本；它会解析到 gtars 0.10）。使用 uv 安装（对于一次性运行，优先使用 uv run --with，以免依赖泄漏到项目环境中）：

uv pip install 'geniml[ml]'        # [ml] pulls torch/gensim; needed for region2vec/scembed

scEmbed 和 scATAC-seq 示例还需要 scanpy：uv pip install scanpy。构建全集（build-universe）和硬分词会调用外部二进制程序——uniwig（覆盖轨道）和 bedtools——因此需单独安装。

开发版本：uv pip install git+https://github.com/databio/geniml.git

导入路径（经验证的易错点）

geniml 的子包 __init__.py 文件不会重新导出其内部内容，因此常见的简写导入会失败并引发 ImportError。请改为从具体模块导入：

目标	错误（会失败）	正确（已验证）
硬分词	from geniml.tokenization import hard_tokenization	from geniml.tokenization.main import hard_tokenization_main
Region2Vec（旧版函数）	from geniml.region2vec import region2vec	from geniml.region2vec.main_legacy import region2vec
Region2Vec（模型类）	—	from geniml.region2vec.main import Region2VecExModel
scEmbed	from geniml.scembed import ScEmbed	from geniml.scembed.main import ScEmbed
标记数据集	from geniml.io import tokenize_cells（不存在）	from geniml.region2vec.utils import Region2VecDataset
分词器	—	from gtars.tokenizers import Tokenizer

ScEmbed 会通过 gtars Tokenizer 在内部处理单元格分词；不存在 geniml.io.tokenize_cells 函数。

核心功能

Geniml 提供五项主要功能，每项都在专门的参考文件中详细说明：

1. Region2Vec：基因组区域嵌入

使用 word2vec 风格的学习方法训练基因组区域的无监督嵌入。

用途： 对 BED 文件进行降维、分析区域相似性，以及为下游机器学习生成特征向量。

工作流：

1. 使用全集参考对 BED 文件进行分词
2. 在标记上训练 Region2Vec 模型
3. 为区域生成嵌入

参考： 详细工作流、参数和示例请参阅 references/region2vec.md。

2. BEDspace：区域与元数据联合嵌入

使用 StarSpace 为区域集和元数据标签训练共享嵌入。

用途： 感知元数据的搜索、跨模态查询（区域→标签或标签→区域），以及基因组内容与实验条件的联合分析。

工作流：

1. 预处理区域和元数据
2. 训练 BEDspace 模型
3. 计算距离
4. 跨区域和标签进行查询

参考： 详细工作流、搜索类型和示例请参阅 references/bedspace.md。

3. scEmbed：单细胞染色质可及性嵌入

在单细胞 ATAC-seq 数据上训练 Region2Vec 模型，以生成细胞级嵌入。

适用于： scATAC-seq 聚类、细胞类型注释、单细胞降维，以及与 scanpy 工作流集成。

工作流：

1. 准备包含峰坐标的 AnnData
2. 对细胞进行预分词
3. 训练 scEmbed 模型
4. 生成细胞嵌入
5. 使用 scanpy 进行聚类和可视化

参考： 详细工作流、参数和示例请参见 references/scembed.md。

4. Consensus Peaks：构建全集

使用多种统计方法，从 BED 文件集合构建参考峰集（全集）。

适用于： 创建分词参考、统一不同数据集中的区域，以及以严谨的统计方法定义共识特征。

工作流：

1. 合并 BED 文件
2. 生成覆盖轨迹
3. 使用 CC、CCF、ML 或 HMM 方法构建全集

方法：

• CC（Coverage Cutoff，覆盖阈值）：基于简单阈值
• CCF（Coverage Cutoff Flexible，灵活覆盖阈值）：为边界计算置信区间
• ML（Maximum Likelihood，最大似然）：对位置进行概率建模
• HMM（Hidden Markov Model，隐马尔可夫模型）：复杂状态建模

参考： 方法对比、参数和示例请参见 references/consensus_peaks.md。

5. 实用工具：辅助工具

用于缓存、随机化、评估和搜索的其他工具。

可用工具：

• BBClient：缓存 BED 文件，便于重复访问
• BEDshift：保留基因组背景的随机化
• Evaluation：评估嵌入质量的指标（轮廓系数、Davies-Bouldin 等）
• Tokenization：区域分词工具（硬分词、软分词、基于全集的分词）
• Text2BedNN：用于基因组查询的神经搜索后端

参考： 各工具的详细用法请参见 references/utilities.md。

常见工作流

基础区域嵌入流程

from geniml.tokenization.main import hard_tokenization_main
from geniml.region2vec.main_legacy import region2vec

# Step 1: Tokenize BED files against a universe.
# `fraction` (default 1e-9) is the minimum overlap fraction for a hit — NOT a p-value.
# Requires the `bedtools` binary on PATH.
hard_tokenization_main(
    src_folder='bed_files/',
    dst_folder='tokens/',
    universe_file='universe.bed',
    fraction=1e-9,
)

# Step 2: Train Region2Vec (word2vec-style over the token "sentences")
region2vec(
    token_folder='tokens/',
    save_dir='model/',
    num_shufflings=1000,   # this is also the number of training epochs
    embedding_dim=100,
    context_win_size=5,    # half-window; CLI flag is --context-len
)

scATAC-seq 分析流程

import scanpy as sc
from geniml.scembed.main import ScEmbed
from geniml.region2vec.utils import Region2VecDataset
from gtars.tokenizers import Tokenizer

# Step 1: Load AnnData. Peaks must live in adata.var with chr/start/end.
adata = sc.read_h5ad('scatac_data.h5ad')

# Step 2: Build a model bound to a universe tokenizer (gtars).
model = ScEmbed(tokenizer=Tokenizer('universe.bed'))

# Step 3: Train on pre-tokenized cells (a parquet of .gtok tokens).
# Embedding size / negative samples are passed via gensim_params, e.g.
# gensim_params={'vector_size': 100, 'negative': 5}
dataset = Region2VecDataset('tokens.parquet', convert_to_str=True)
model.train(dataset, epochs=100, min_count=1)

# Step 4: Generate cell embeddings and store them.
adata.obsm['scembed_X'] = model.encode(adata, pooling='mean')

# Step 5: Cluster with scanpy
sc.pp.neighbors(adata, use_rep='scembed_X')
sc.tl.leiden(adata)
sc.tl.umap(adata)

全集构建与评估

# Generate coverage
cat bed_files/*.bed > combined.bed
uniwig -m 25 combined.bed chrom.sizes coverage/

# Build universe with coverage cutoff (top-level command is `build-universe`)
geniml build-universe cc \
  --coverage-folder coverage/ \
  --output-file universe.bed \
  --cutoff 5 \
  --merge 100 \
  --filter-size 50

# Assess universe quality (command is `assess-universe`)
geniml assess-universe --help   # see flags; varies by metric

CLI 参考

Geniml 为主要操作提供命令行接口：

# Region2Vec training (--context-len is the half-window; there is no --window-size)
geniml region2vec --token-folder tokens/ --save-dir model/ --num-shuffle 1000 --embed-dim 100

# BEDspace preprocessing
geniml bedspace preprocess --input regions/ --metadata labels.csv --universe universe.bed --output preprocessed/

# BEDspace training (StarSpace must be installed separately)
geniml bedspace train --input preprocessed.txt --output model/ --dim 100

# BEDspace search — the query is POSITIONAL (last arg), not a -q flag
geniml bedspace search -t r2l -d distances.pkl -n 10 query.bed

# Universe building (top-level command is `build-universe`; --output-file, not --output)
geniml build-universe cc --coverage-folder coverage/ --output-file universe.bed --cutoff 5

# BEDshift randomization (-b bedfile, -g refgenie genome OR -l chrom sizes; perturbations
# are rates: -d drop, -a add, -s shift, -c cut, -m merge; -r repeat, -o output)
geniml bedshift -b peaks.bed -g hg38 -s 0.3 -r 100 -o randomized.bed

如何选择工具

你拥有的内容 / 想要实现的目标	工具
批量区域集（ChIP/ATAC-seq）、无监督嵌入、无元数据	Region2Vec
区域集加上元数据标签；跨模态标签↔区域搜索	BEDspace
需要聚类/注释的 scATAC-seq 细胞（与 scanpy 集成）	scEmbed
根据多个 BED 文件构建共识峰集 / 分词参考	build-universe
缓存远程 BED 文件、空模型、嵌入指标	Utilities（BBClient/BEDshift/eval）
普通区间重叠/交集/合并计数，不涉及机器学习	gtars — 而非 geniml

最佳实践

通用指南

• 全集质量至关重要：投入时间构建全面且完善的全集
• 分词验证：训练前检查覆盖率（理想值为 >80%）
• 参数调优：尝试不同的嵌入维度、学习率和训练轮数
• 评估：务必使用多种指标和可视化验证嵌入
• 文档记录：记录参数和随机种子，以确保可复现性

性能注意事项

• 预分词：对于 scEmbed，务必预先对细胞进行分词，以加快训练
• 内存管理：大型数据集可能需要分批处理或下采样
• 计算资源：ML/HMM 全集方法的计算开销较大
• 模型缓存：使用 BBClient 避免重复下载

集成模式

• 与 scanpy 集成：scEmbed 嵌入可无缝作为 adata.obsm 条目使用
• 与 BEDbase 集成：使用 BBClient 访问远程 BED 存储库
• 与 Hugging Face 集成：导出训练好的模型，以便共享和复现
• 与 R 集成：使用 reticulate 进行 R 集成（参见实用工具参考）

相关项目

Geniml 是 BEDbase 生态系统的一部分：

• BEDbase：基因组区域的统一平台
• BEDboss：BED 文件处理流水线
• Gtars：基因组工具和实用程序
• BBClient：BEDbase 仓库的客户端

更多资源

• 文档：https://docs.bedbase.org/geniml/（也可通过 https://geniml.databio.org 访问）
• GitHub：https://github.com/databio/geniml
• 预训练模型：可在 Hugging Face（databio 组织）上获取

故障排除

**从 geniml.X import ... 导入时出现 ImportError：**子包 __init__ 不会重新导出该项，请从具体模块导入（参见上方的导入路径表）。

“分词覆盖率过低”：

• 检查 universe 的质量和完整性
• 放宽重叠 fraction（例如使用 1e-6，而不是 1e-9）——请注意，这是重叠比例，不是 p 值
• 确保 universe 与基因组组装版本相匹配

“训练未能收敛”：

• 调整学习率（init_lr / gensim 参数，约 0.01-0.05）
• 增加训练轮数（region2vec 使用 num_shufflings；scEmbed 使用 epochs）
• 检查数据质量和预处理

“内存不足错误”：

• 预先对细胞进行分词，使训练流式处理词元，而不是处理整个矩阵
• 分块处理数据或对数据进行下采样
• 减小 embedding_dim

“未找到 StarSpace”（BEDspace）：

• 单独安装/构建 StarSpace：https://github.com/facebookresearch/StarSpace
• 使用 -s / --path-to-starsapce 指定 bedspace train/distances 所用的路径（注意：geniml CLI 标志的拼写确实是错误的“starsapce”）

有关详细的故障排除信息和特定方法的问题，请参阅相应的参考文件。

属于 AlterLab Academic Skills 套件。