geniml

Geniml: ゲノムインターバル機械学習

概要

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

インストール

uv を使用して geniml をインストールします:

uv uv pip install geniml

ML 依存関係（PyTorch など）の場合:

uv uv pip install 'geniml[ml]'

GitHub からの開発版:

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

主要な機能

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. ユーティリティ: 補助ツール

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

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

• BBClient: 繰り返しアクセスのための BED ファイルキャッシュ
• BEDshift: ゲノムコンテキストを保持するランダム化
• Evaluation: 埋め込みの品質指標（silhouette、Davies-Bouldin など）
• Tokenization: 領域のトークン化ユーティリティ（hard、soft、ユニバースベース）
• 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)

ユニバースの構築と評価

# 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/

CLI リファレンス

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 Building を使う場合:

• トークン化のための参照ピークセットが必要なとき
• 複数の実験をコンセンサスにまとめるとき
• 統計的に厳密な領域定義が必要なとき
• プロジェクトの標準的なリファレンスを構築するとき

Utilities を使う場合:

• リモートの BED ファイルをキャッシュする必要があるとき（BBClient）
• 統計のためのヌルモデルを生成するとき（BEDshift）
• 埋め込みの品質を評価するとき（Evaluation）
• 検索インターフェースを構築するとき（Text2BedNN）

ベストプラクティス

一般的なガイドライン

• Universe の品質が極めて重要: 包括的で適切に構築された Universe の作成に時間をかけてください
• トークン化の検証: 学習の前にカバレッジ（80% 超が理想）を確認してください
• パラメータのチューニング: 埋め込み次元、学習率、学習エポック数を試してください
• 評価: 埋め込みは必ず複数の指標と可視化で検証してください
• ドキュメント化: 再現性のためにパラメータと乱数シードを記録してください

パフォーマンスに関する考慮事項

• 事前トークン化: scEmbed では、学習を高速化するために必ず細胞を事前トークン化してください
• メモリ管理: 大規模データセットでは、バッチ処理やダウンサンプリングが必要になる場合があります
• 計算リソース: ML/HMM の Universe 手法は計算負荷が高いです
• モデルのキャッシュ: 繰り返しのダウンロードを避けるために 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/
• GitHub: https://github.com/databio/geniml
• 学習済みモデル: Hugging Face（databio 組織）で公開されています
• 論文: 手法の詳細はドキュメント内で引用されています

トラブルシューティング

「Tokenization coverage too low」（トークン化カバレッジが低すぎます）:

• Universe の品質と網羅性を確認してください
• p 値の閾値を調整してください（1e-9 の代わりに 1e-6 を試してください）
• Universe がゲノムアセンブリと一致していることを確認してください

「Training not converging」（学習が収束しません）:

• 学習率を調整してください（0.01〜0.05 の範囲を試してください）
• 学習エポック数を増やしてください
• データの品質と前処理を確認してください

「Out of memory errors」（メモリ不足エラー）:

• scEmbed のバッチサイズを小さくしてください
• データをチャンクに分けて処理してください
• シングルセルデータには事前トークン化を使用してください

「StarSpace not found」（StarSpace が見つかりません）（BEDspace）:

• StarSpace を別途インストールしてください: https://github.com/facebookresearch/StarSpace
• --path-to-starspace パラメータを正しく設定してください

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