geniml

Geniml：基因组区间机器学习

概述

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

安装

使用 uv 安装 geniml：

uv uv pip install geniml

安装机器学习依赖（PyTorch 等）：

uv uv pip install 'geniml[ml]'

从 GitHub 安装开发版本：

uv uv pip install git+https://github.com/databio/geniml.git

核心功能

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

1. Region2Vec：基因组区域嵌入

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

适用场景： 对 BED 文件进行降维、区域相似性分析、为下游机器学习任务生成特征向量。

工作流：

1. 使用 universe 参考对 BED 文件进行分词
2. 基于 token 训练 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. 共识峰：构建 universe

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

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

工作流：

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

方法：

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

参考： 有关方法比较、参数和示例，请参阅 references/consensus_peaks.md。

5. 实用工具：辅助工具

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

可用工具：

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

参考： 有关各项实用工具的详细用法，请参阅 references/utilities.md。

常见工作流

基本区域嵌入流程

from geniml.tokenization import hard_tokenization
from geniml.region2vec import region2vec
from geniml.evaluation import evaluate_embeddings

# Step 1: Tokenize BED files
hard_tokenization(
    src_folder='bed_files/',
    dst_folder='tokens/',
    universe_file='universe.bed',
    p_value_threshold=1e-9
)

# Step 2: Train Region2Vec
region2vec(
    token_folder='tokens/',
    save_dir='model/',
    num_shufflings=1000,
    embedding_dim=100
)

# Step 3: Evaluate
metrics = evaluate_embeddings(
    embeddings_file='model/embeddings.npy',
    labels_file='metadata.csv'
)

scATAC-seq 分析流程

import scanpy as sc
from geniml.scembed import ScEmbed
from geniml.io import tokenize_cells

# Step 1: Load data
adata = sc.read_h5ad('scatac_data.h5ad')

# Step 2: Tokenize cells
tokenize_cells(
    adata='scatac_data.h5ad',
    universe_file='universe.bed',
    output='tokens.parquet'
)

# Step 3: Train scEmbed
model = ScEmbed(embedding_dim=100)
model.train(dataset='tokens.parquet', epochs=100)

# Step 4: Generate embeddings
embeddings = model.encode(adata)
adata.obsm['scembed_X'] = embeddings

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

Universe 构建与评估

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

# Build universe with coverage cutoff
geniml universe build cc \
  --coverage-folder coverage/ \
  --output-file universe.bed \
  --cutoff 5 \
  --merge 100 \
  --filter-size 50

# Evaluate universe quality
geniml universe evaluate \
  --universe universe.bed \
  --coverage-folder coverage/ \
  --bed-folder bed_files/

命令行界面参考

Geniml 为主要操作提供命令行界面：

# Region2Vec training
geniml region2vec --token-folder tokens/ --save-dir model/ --num-shuffle 1000

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

# BEDspace training
geniml bedspace train --input preprocessed.txt --output model/ --dim 100

# BEDspace search
geniml bedspace search -t r2l -d distances.pkl -q query.bed -n 10

# Universe building
geniml universe build cc --coverage-folder coverage/ --output universe.bed --cutoff 5

# BEDshift randomization
geniml bedshift --input peaks.bed --genome hg38 --preserve-chrom --iterations 100

何时使用哪种工具

在以下情况下使用 Region2Vec：

• 处理批量基因组数据（ChIP-seq、ATAC-seq 等）
• 需要不依赖元数据的无监督嵌入
• 比较不同实验中的区域集
• 为下游监督学习构建特征

在以下情况下使用 BEDspace：

• 有可用的元数据标签（细胞类型、组织、条件）
• 需要按元数据查询区域，或反向查询
• 希望为区域和标签构建联合嵌入空间
• 构建可搜索的基因组数据库

在以下情况下使用 scEmbed：

• 分析单细胞 ATAC-seq 数据
• 根据染色质可及性对细胞进行聚类
• 根据 scATAC-seq 注释细胞类型
• 希望与 scanpy 集成

在以下情况下构建 Universe：

• 需要用于分词的参考峰集
• 将多个实验合并为共识集
• 希望以统计学上严谨的方式定义区域
• 为项目构建标准参考集

在以下情况下使用实用工具：

• 需要缓存远程 BED 文件（BBClient）
• 为统计分析生成零模型（BEDshift）
• 评估嵌入质量（Evaluation）
• 构建搜索界面（Text2BedNN）

最佳实践

通用指南

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

性能注意事项

• 预分词：对于 scEmbed，始终预先对细胞进行分词，以加快训练
• 内存管理：大型数据集可能需要批处理或降采样
• 计算资源：ML/HMM Universe 方法的计算开销较大
• 模型缓存：使用 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/
• GitHub：https://github.com/databio/geniml
• 预训练模型：可在 Hugging Face 上获取（databio 组织）
• 出版物：文档中引用了相关出版物，详述方法细节

故障排除

“分词覆盖率过低”：

• 检查 Universe 的质量和完整性
• 调整 p 值阈值（试试 1e-6，而不是 1e-9）
• 确保 Universe 与基因组组装版本匹配

“训练未收敛”：

• 调整学习率（试试 0.01-0.05 范围）
• 增加训练轮数
• 检查数据质量和预处理

“内存不足错误”：

• 减小 scEmbed 的批次大小
• 分块处理数据
• 对单细胞数据使用预分词

“未找到 StarSpace”（BEDspace）：

• 单独安装 StarSpace：https://github.com/facebookresearch/StarSpace
• 正确设置 --path-to-starspace 参数

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