格尼姆尔

数据 社区

技能解读

当前原文的自动摘译,尚未人工审校。

何时使用

您有许多 BED 文件,并且需要用于聚类、相似性搜索或下游监督学习(例如 ChIP-seq/ATAC-seq 区域集)的数字特征。您希望基因组区域的无监督嵌入来比较实验中的区域集 (Region2Vec)。您需要区域和元数据标签(例如组织/细胞类型/条件)的联合嵌入,以启用跨模式查询,例如 Region → Label 或 Label → Region (BEDspace)。

主要特点

Region2Vec:来自标记化 BED 数据的基因组区域的 Word2vec 式无监督嵌入。 BEDspace:基于StarSpace的区域集和元数据标签的联合嵌入空间;支持相似性搜索和跨模态检索。 scEmbed:与 Scanpy 兼容的单细胞 ATAC-seq 嵌入工作流程(标记细胞→训练→编码细胞)。 Universe(共识峰)生成器:使用多种统计方法(CC、CCF、ML、HMM)生成参考峰集。

依赖关系

Python:3.9+(推荐)geniml:来自 PyPI(或 GitHub 主版)的最新版本 可选 ML 附加功能:geniml[ml](通常会拉取 PyTorch 和相关 ML 依赖项) Scanpy 堆栈(用于 scEmbed 工作流程):scanpy(加上 anndata、numpy、scipy)StarSpace(用于BEDspace 训练):来自 https://github.com/facebookresearch/StarSpace 的外部二进制文件

代币化(基于宇宙)

目标:将基因组间隔转换为由参考宇宙(共识峰值集)定义的离散“标记”。硬标记化:确定性地将间隔分配给 Universe bin/peak(通常用于 Region2Vec/scEmbed 管道)。关键参数:p_value_threshold控制映射/重叠显着性的严格性(越低越严格;过于严格的阈值会降低覆盖范围)。

Region2Vec(区域嵌入)

核心思想:将每个BED文件(或区域集)视为一个“文档”,将每个宇宙峰视为一个“单词”;使用 word2vec 风格的目标学习嵌入。重要的旋钮:embedding_dim:学习向量的维数(例如,50-300)。 num_shufflings:通过洗牌/共现增强来增加训练信号;较高的值会增加运行时间。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
数据
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
Python
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md
> **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills)

## When to Use

- **You have many BED files and need numeric features** for clustering, similarity search, or downstream supervised learning (e.g., ChIP-seq/ATAC-seq region sets).
- **You want unsupervised embeddings of genomic regions** to compare region sets across experiments (Region2Vec).
- **You need joint embeddings of regions and metadata labels** (e.g., tissue/cell type/condition) to enable cross-modal queries like *Region → Label* or *Label → Region* (BEDspace).
- **You are analyzing single-cell ATAC-seq** and want cell embeddings for clustering/annotation and integration with Scanpy workflows (scEmbed).
- **You need a consensus peak set (“universe”)** built from multiple BED files to standardize tokenization and region definitions across datasets (Universe construction).

## Key Features

- **Region2Vec**: Word2vec-style unsupervised embeddings for genomic regions from tokenized BED data.
- **BEDspace**: StarSpace-based joint embedding space for region sets and metadata labels; supports similarity search and cross-modal retrieval.
- **scEmbed**: Single-cell ATAC-seq embedding workflow (tokenize cells → train → encode cells) compatible with Scanpy.
- **Universe (Consensus Peaks) Builder**: Generates reference peak sets using multiple statistical approaches (CC, CCF, ML, HMM).
- **Utilities**:
  - **Tokenization**: Universe-based tokenization (hard/soft tokenization patterns).
  - **Evaluation**: Embedding quality metrics (e.g., silhouette, Davies–Bouldin).
  - **BEDshift**: Region randomization/null-model generation while preserving genomic context.
  - **BBClient / caching**: Faster repeated access to BED resources.
  - **Text2BedNN**: Neural search backend for genomic queries.

> Additional details are commonly documented in: `references/region2vec.md`, `references/bedspace.md`, `references/scembed.md`, `references/consensus_peaks.md`, `references/utilities.md`.

## Dependencies

- **Python**: 3.9+ (recommended)
- **geniml**: latest from PyPI (or GitHub main)
- **Optional ML extras**: `geniml[ml]` (typically pulls **PyTorch** and related ML dependencies)
- **Scanpy stack (for scEmbed workflows)**: `scanpy` (plus `anndata`, `numpy`, `scipy`)
- **StarSpace (for BEDspace training)**: external binary from https://github.com/facebookresearch/StarSpace
- **Universe coverage generation**: `uniwig` (used to generate coverage tracks in universe workflows)

## Example Usage

### 1) Install

```bash
# Base install
uv pip install geniml

# With ML extras (e.g., PyTorch and related dependencies)
uv pip install "geniml[ml]"

# Development version
uv pip install git+https://github.com/databio/geniml.git
```

### 2) End-to-end: Build a universe → tokenize BEDs → train Region2Vec → evaluate

```bash
# (A) Build coverage tracks (example pattern)
cat bed_files/*.bed > combined.bed
uniwig -m 25 combined.bed chrom.sizes coverage/

# (B) Build a universe (coverage cutoff method)
geniml universe build cc \
  --coverage-folder coverage/ \
  --output-file universe.bed \
  --cutoff 5 \
  --merge 100 \
  --filter-size 50
```

```python
# (C) Tokenize BED files, train Region2Vec, and evaluate embeddings
from geniml.tokenization import hard_tokenization
from geniml.region2vec import region2vec
from geniml.evaluation import evaluate_embeddings

# 1) Tokenize BED files against the universe
hard_tokenization(
    src_folder="bed_files/",
    dst_folder="tokens/",
    universe_file="universe.bed",
    p_value_threshold=1e-9,
)

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

# 3) Evaluate (requires labels/metadata aligned to embeddings)
metrics = evaluate_embeddings(
    embeddings_file="model/embeddings.npy",
    labels_file="metadata.csv",
)

print(metrics)
```

### 3) Single-cell ATAC-seq: tokenize cells → train scEmbed → cluster with Scanpy

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

# 1) Load AnnData
adata = sc.read_h5ad("scatac_data.h5ad")

# 2) Tokenize cells using a universe
tokenize_cells(
    adata="scatac_data.h5ad",
    universe_file="universe.bed",
    output="tokens.parquet",
)

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

# 4) Encode cells and attach embeddings to AnnData
embeddings = model.encode(adata)
adata.obsm["scembed_X"] = embeddings

# 5) Standard Scanpy neighborhood graph + clustering + UMAP
sc.pp.neighbors(adata, use_rep="scembed_X")
sc.tl.leiden(adata)
sc.tl.umap(adata)
```

## Implementation Details

### Tokenization (Universe-based)
- **Goal**: Convert genomic intervals into discrete “tokens” defined by a reference **universe** (consensus peak set).
- **Hard tokenization**: Assigns intervals to universe bins/peaks deterministically (commonly used for Region2Vec/scEmbed pipelines).
- **Key parameter**: `p_value_threshold` controls stringency of mapping/overlap significance (lower is stricter; overly strict thresholds can reduce coverage).

### Region2Vec (Region Embeddings)
- **Core idea**: Treat each BED file (or region set) like a “document” and each universe peak like a “word”; learn embeddings using a word2vec-style objective.
- **Important knobs**:
  - `embedding_dim`: dimensionality of learned vectors (e.g., 50–300).
  - `num_shufflings`: increases training signal by shuffling/co-occurrence augmentation; higher values increase runtime.

### BEDspace (Joint Region + Label Embeddings)
- **Core idea**: Learn a shared vector space for region sets and metadata labels using **StarSpace**, enabling:
  - **Region → Label** retrieval (predict likely labels for a query region set)
  - **Label → Region** retrieval (find region sets associated with a label)
- **Operational requirement**: StarSpace must be installed and its path provided/configured for training.

### scEmbed (Single-cell Embeddings)
- **Core idea**: Apply Region2Vec-like training on tokenized single-cell accessibility profiles to produce **cell embeddings**.
- **Best practice**: **Pre-tokenize** cells (e.g., to Parquet) to reduce repeated preprocessing and speed up training.
- **Downstream**: Use embeddings as `adata.obsm[...]` and run standard Scanpy steps (neighbors, Leiden, UMAP).

### Universe Construction (Consensus Peaks)
- **Purpose**: Create a stable reference peak set for tokenization and cross-dataset comparability.
- **Methods**:
  - **CC (Coverage Cutoff)**: threshold-based peak calling from coverage.
  - **CCF (Coverage Cutoff Flexible)**: cutoff with flexible boundaries/confidence intervals.
  - **ML (Maximum Likelihood)**: probabilistic modeling of peak positions.
  - **HMM (Hidden Markov Model)**: state-based segmentation; typically most computationally intensive.
- **Typical parameters**:
  - `--cutoff`: minimum coverage to call peaks (CC/CCF).
  - `--merge`: merge distance for nearby peaks.
  - `--filter-size`: minimum peak length to keep.

---
> Source: [aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。