geniml

用途

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

主要能力

Geniml 提供五项核心能力：

Region2Vec：基因组区域嵌入 使用 word2vec 风格的学习方式训练基因组区域的无监督嵌入。适用于 BED 文件的降维、区域相似性分析，以及为下游机器学习提供特征向量。工作流程为：使用 universe 参考对 BED 文件进行分词，在 token 上训练 Region2Vec 模型，再为区域生成嵌入。
BEDspace：区域与元数据联合嵌入 使用 StarSpace 为区域集和元数据标签训练共享嵌入。适用于元数据感知搜索、跨模态查询（区域→标签或标签→区域），以及基因组内容与实验条件的联合分析。工作流程为：预处理区域和元数据，训练 BEDspace 模型，计算距离，跨区域和标签进行查询。
scEmbed：单细胞染色质可及性嵌入 在单细胞 ATAC-seq 数据上训练 Region2Vec 模型，以获得细胞级嵌入。适用于 scATAC-seq 聚类、细胞类型注释、单细胞降维，以及与 scanpy 工作流的集成。工作流程为：准备带峰坐标的 AnnData，预分词细胞，训练 scEmbed 模型，生成细胞嵌入，再用 scanpy 进行聚类和可视化。
Consensus Peaks：Universe 构建 使用多种统计方法从 BED 文件集合构建参考峰集（universe）。适用于创建分词参考、跨数据集标准化区域，以及以统计严谨性定义共识特征。方法包括：CC（Coverage Cutoff，基于简单阈值）、CCF（Coverage Cutoff Flexible，为边界提供置信区间）、ML（Maximum Likelihood，对位置进行概率建模）、HMM（Hidden Markov Model，复杂状态建模）。
Utilities：支持工具 提供缓存、随机化、评估和搜索等附加工具，包括：BBClient（用于重复访问的 BED 文件缓存）、BEDshift（保留基因组上下文的随机化）、Evaluation（嵌入质量指标，如 silhouette、Davies-Bouldin 等）、Tokenization（区域分词工具，支持 hard、soft、基于 universe 的方式）、Text2BedNN（用于基因组查询的神经搜索后端）。

使用方式

安装

使用 uv 安装 geniml：

uv pip install geniml

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

uv pip install 'geniml[ml]'

从 GitHub 安装开发版本：

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

基础区域嵌入流程（Python API）

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/

命令行接口

# 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 构建：需要用于分词的参考峰集；将多个实验合并为共识；希望获得统计严谨的区域定义；为项目构建标准参考。
使用 Utilities：需要缓存远程 BED 文件（BBClient）；为统计生成零模型（BEDshift）；评估嵌入质量（Evaluation）；构建搜索接口（Text2BedNN）。

最佳实践

Universe 质量至关重要：应投入时间构建全面、结构良好的 universe。
分词验证：训练前检查覆盖率（理想情况 >80%）。
参数调优：尝试不同的嵌入维度、学习率和训练轮数。
评估：始终使用多种指标和可视化验证嵌入。
文档记录：记录参数和随机种子以保证可复现性。

性能方面：对 scEmbed 始终预分词细胞以加快训练；大型数据集可能需要批处理或降采样；ML/HMM universe 方法计算密集；使用 BBClient 避免重复下载。

集成模式：scEmbed 嵌入可作为 adata.obsm 条目无缝集成 scanpy；使用 BBClient 访问远程 BED 仓库；可将训练好的模型导出到 Hugging Face 以便共享和复现；可通过 reticulate 与 R 集成。

限制与注意事项

使用 BEDspace 时，StarSpace 需单独安装（https://github.com/facebookresearch/StarSpace），并正确设置 --path-to-starspace 参数。
常见问题包括：分词覆盖率过低（需检查 universe 质量、调整 p 值阈值、确保 universe 与基因组组装匹配）；训练不收敛（调整学习率、增加轮数、检查数据质量）；内存不足（减小 scEmbed 批大小、分块处理、对单细胞数据使用预分词）。
关于收费、价格、平台支持等具体信息，资料中暂未提供。

技能介绍

用途