alterlab-geniml

Geniml：ゲノム区間の機械学習

概要

Geniml は、BED ファイルのゲノム区間データを用いた機械学習モデルを構築するための Python パッケージです。ゲノム領域、単一細胞、メタデータラベルの埋め込みを学習する教師なし手法を提供し、類似性検索、クラスタリング、後続の ML タスクを可能にします。

このスキルを使用する場面

ゲノム区間を対象とする ML に使用します。Region2Vec／scEmbed／BEDspace の埋め込みの学習や適用、トークン化用のコンセンサスユニバースの構築、領域トークンからの scATAC-seq 細胞のクラスタリング、BEDshift の帰無モデルや BBClient のキャッシュなどに利用できます。

対象外

シナリオ	代わりに使用
基本的な区間演算 — 重なり、jaccard、IGD、uniwig トラック、refget ダイジェスト	alterlab-gtars
標準的な scRNA-seq の QC → クラスタリング → マーカーパイプライン	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

細胞のトークン化は、gtars の Tokenizer を介して ScEmbed の内部で処理されます。geniml.io.tokenize_cells 関数はありません。

主な機能

Geniml は、主に 5 つの機能を提供します。それぞれの詳細は、専用のリファレンスファイルに記載されています。

1. Region2Vec：ゲノム領域の埋め込み

word2vec 形式の学習を用いて、ゲノム領域の教師なし埋め込みを学習します。

用途： BED ファイルの次元削減、領域の類似性分析、後続の ML に使用する特徴ベクトル。

ワークフロー：

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. Utilities：補助ツール

キャッシュ、ランダム化、評価、検索のための追加ツールです。

利用可能なユーティリティ：

• 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 との連携：リモート BED リポジトリにアクセスするには、BBClient を使用してください
• Hugging Face との連携：学習済みモデルをエクスポートして共有し、再現性を確保できます
• R との連携：R との統合には reticulate を使用してください（utilities のリファレンスを参照）

関連プロジェクト

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 組織）で入手できます

トラブルシューティング

from geniml.X import ... での ImportError： サブパッケージの __init__ から再エクスポートされていません。具体的なモジュールからインポートしてください（上記のインポートパスの表を参照）。

「トークン化のカバレッジが低すぎます」：

• ユニバースの品質と完全性を確認してください
• オーバーラップの fraction を緩和してください（例：1e-9 ではなく 1e-6）。これは p 値ではなく、オーバーラップ率です
• ユニバースがゲノムアセンブリと一致していることを確認してください

「トレーニングが収束しません」：

• 学習率を調整してください（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 から StarSpace を参照してください（注：geniml CLI フラグは「starsapce」という誤記のままです）

詳しいトラブルシューティングや手法固有の問題については、該当するリファレンスファイルを参照してください。

AlterLab Academic Skills スイートの一部です。