single-cell-multi-omics-integration

単一細胞マルチオミクス統合

このスキルでは、scRNA-seq、scATAC-seq、その他のモダリティを組み合わせるためのOmicVerseのマルチオミクス統合ツールを扱います。各手法は異なるシナリオに対応しています。データ構造と解析目標に基づいて選択してください。

手法選択ガイド

コードを書く前に、適切なツールを選んでください。

シナリオ	手法	主要クラス
同じ細胞から得られたペアRNA＋ATAC	MOFAを直接使用	ov.single.pyMOFA
ペアではないRNA＋ATAC（異なる実験）	GLUEでペアリング → MOFA	ov.single.GLUE_pair → pyMOFA
マルチバッチの単一モダリティ統合	SIMBA	ov.single.pySIMBA
アノテーション済みリファレンスからラベルを転送	TOSICA	ov.single.pyTOSICA
前処理済みマルチオミクスデータでの軌跡解析	StaVIA	VIA.core.VIA

手順

1. ペアのマルチオミクスデータでMOFAを使用

ペア測定（同じ細胞から得られたRNA＋ATACデータ）がある場合は、MOFAを使用してください。MOFAは、オミクス層全体の分散を説明する、共有因子とモダリティ固有の因子を学習します。

1. 各モダリティを個別のAnnDataオブジェクトとして読み込みます
2. omicsとomics_nameのリストが対応するようにpyMOFAを初期化します
3. mofa_preprocess()を実行してHVGを選択し、続いてmofa_run(outfile=...)で学習します
4. pyMOFAART(model_path=...)で因子の相関、重み、分散プロットを確認します
5. 依存関係：mofapy2。CPUのみで動作します

2. GLUEでペアリングしてからMOFAを使用

RNAとATACが異なる実験（ペアではない）から得られた場合は、GLUEを使用してください。GLUEは共有埋め込みを学習してモダリティ間の細胞を位置合わせし、その後MOFAが共通因子を特定します。

1. GLUE由来の埋め込み（埋め込みが.obsmに含まれる.h5adファイル）から開始します
2. GLUE_pairを作成し、correlation()を呼び出してペアではない細胞を対応付けます
3. HVGに絞り込み、ペアのワークフローと同様にMOFAを実行します
4. 依存関係：mofapy2、scglue、scvi-tools。MDE埋め込みではGPUを任意で使用できます

3. SIMBAによるバッチ統合

マルチバッチの単一モダリティデータ（例：複数の膵臓研究）にはSIMBAを使用してください。SIMBAはビン化した特徴量からグラフを構築し、PyTorch-BigGraphを介してバッチ補正済み埋め込みを学習します。

1. .obsにbatch列を含む、結合済みのAnnDataを読み込みます
2. pySIMBA(adata, workdir)を初期化し、前処理パイプラインを実行します
3. gen_graph()を呼び出してからtrain(num_workers=...)を実行し、埋め込みを学習します
4. batch_correction()を適用して、X_simbaを含む調和済みAnnDataを取得します
5. 依存関係：simba、simba_pbg。GPUは任意で使用できますが、十分なCPUスレッドが必要です

4. TOSICAによるリファレンスからの転送

十分にアノテーションされたリファレンスからクエリデータセットへ細胞型ラベルを転送するには、TOSICAを使用してください。TOSICAは経路マスク付きトランスフォーマーを使用し、アテンションベースの解釈性も提供します。

1. ov.utils.download_tosica_gmt()で遺伝子セットのGMTファイルをダウンロードします
2. リファレンスAnnData、GMTパス、ラベルキー、プロジェクトパスを指定してpyTOSICAを初期化します
3. train(epochs=...)で学習し、保存してからクエリデータを予測します
4. 依存関係：TOSICA（PyTorchトランスフォーマー）。depth=1を推奨します（depth=2ではメモリ使用量が2倍になります）

5. StaVIAによる軌跡マッピング

速度情報を含む前処理済みデータで軌跡を推定するには、StaVIA／VIAを使用してください。VIAは擬似時間、クラスタグラフ、ストリームプロットを計算します。

1. OmicVerseで前処理します（HVG、スケーリング、PCA、近傍、UMAP）
2. ルート選択、コンポーネント、近傍、解像度を指定してVIAを設定します
3. v0.run_VIA()を実行し、single_cell_pt_markovから擬似時間を抽出します
4. 依存関係：scvelo、pyVIA。CPUで処理します

重要なAPIリファレンス

MOFA：omicsには個別のAnnDataオブジェクトのリストを指定する必要があります

# CORRECT — each modality is a separate AnnData
mofa = ov.single.pyMOFA(omics=[rna_adata, atac_adata], omics_name=['RNA', 'ATAC'])

# WRONG — do NOT pass a single concatenated AnnData
# mofa = ov.single.pyMOFA(omics=combined_adata, omics_name=['RNA', 'ATAC'])  # TypeError!

omicsリストとomics_nameリストの長さは同じでなければなりません。各AnnDataには、同じ実験から得られた細胞（ペア測定）を含める必要があります。

SIMBA：gen_graph()の前にpreprocess()を実行する必要があります

# CORRECT — preprocess first, then build graph
simba = ov.single.pySIMBA(adata, workdir)
simba.preprocess(batch_key='batch', min_n_cells=3, method='lib_size', n_top_genes=3000, n_bins=5)
simba.gen_graph()
simba.train(num_workers=6)

# WRONG — skipping preprocess causes gen_graph to fail
# simba.gen_graph()  # KeyError: missing binned features

TOSICA：gmt_pathには実在するファイルパスを指定する必要があります

# CORRECT — download GMT files first, then pass the file path
ov.utils.download_tosica_gmt()
tosica = ov.single.pyTOSICA(adata=ref, gmt_path='genesets/GO_bp.gmt', ...)

# WRONG — passing a database name string instead of file path
# tosica = ov.single.pyTOSICA(adata=ref, gmt_path='GO_Biological_Process', ...)  # FileNotFoundError!

MOFA HDF5：outfileのディレクトリが存在している必要があります

import os
os.makedirs('models', exist_ok=True)  # Create output directory first
mofa.mofa_run(outfile='models/rna_atac.hdf5')

入力を安全に検証するパターン

統合手法を実行する前に、必ず入力を検証してください。

# Before MOFA: verify inputs are compatible
assert isinstance(omics, list), "omics must be a list of AnnData objects"
assert len(omics) == len(omics_name), f"omics ({len(omics)}) and omics_name ({len(omics_name)}) must match in length"
for i, a in enumerate(omics):
    assert a.n_obs > 0, f"AnnData '{omics_name[i]}' has 0 cells"
    assert a.n_vars > 0, f"AnnData '{omics_name[i]}' has 0 genes/features"

# Before SIMBA: verify batch column exists
assert 'batch' in adata.obs.columns, "adata.obs must contain a 'batch' column for SIMBA"
assert adata.obs['batch'].nunique() > 1, "Need >1 batch for batch integration"

# Before TOSICA: verify GMT file exists and reference has labels
import os
assert os.path.isfile(gmt_path), f"GMT file not found: {gmt_path}. Run ov.utils.download_tosica_gmt() first."
assert label_name in ref_adata.obs.columns, f"Label column '{label_name}' not found in reference AnnData"

# Before StaVIA: verify PCA and neighbors are computed
assert 'X_pca' in adata.obsm, "PCA required. Run ov.pp.pca(adata) first."
assert 'neighbors' in adata.uns, "Neighbor graph required. Run ov.pp.neighbors(adata) first."

トラブルシューティング

• MOFA の HDF5 書き込み時の PermissionError または OSError：mofa_run(outfile=...) の出力ディレクトリは、すでに存在し、書き込み可能である必要があります。トレーニング前に os.makedirs() で作成してください。
• GLUE の correlation() が空の DataFrame を返す：RNA と ATAC の埋め込みに、共通する特徴量がありません。両方の AnnData オブジェクトに GLUE の前処理を行い、.obsm に埋め込みが含まれていることを確認してください。
• SIMBA の gen_graph() でメモリ不足が発生する：n_top_genes を減らす（2000 を試してください）か、n_bins を増やして特徴空間を圧縮してください。SIMBA のグラフ構築に必要なリソースは、遺伝子数に応じて増加します。
• download_tosica_gmt() の実行後に TOSICA で FileNotFoundError が発生する：ダウンロードしたファイルは、現在の作業ディレクトリにある genesets/ に保存されます。ファイルが想定したパスに存在することを確認するか、絶対パスを指定してください。
• StaVIA の root_user が一致しない：ルートには、true_label 配列に含まれる値を指定する必要があります。有効なルート名を見つけるには、adata.obs['clusters'].unique() を確認してください。
• ImportError: No module named 'mofapy2'：pip install mofapy2 でインストールしてください。同様に、SIMBA には pip install simba simba_pbg が必要です。
• MOFA のファクターがすべてゼロ、または NaN になる：入力の AnnData に、値が一定またはすべてゼロの特徴量が含まれている可能性があります。MOFA を実行する前に、sc.pp.filter_genes(adata, min_cells=10) で遺伝子をフィルタリングしてください。

例

• 「ペアになった scRNA と scATAC の h5ad ファイルがあるので、MOFA を実行して共通のファクターを見つけ、ファクターごとの説明分散をプロットしてください。」
• 「SIMBA を使って、膵臓の 3 つのバッチを統合し、バッチと細胞タイプで色分けした補正済み埋め込みを可視化してください。」
• 「GO biological process のパスウェイを使って TOSICA で、新しいクエリデータセットに、アノテーション済みの参照データセットから細胞タイプのラベルを転送してください。」

参考資料

• MOFA チュートリアル：t_mofa.ipynb
• GLUE+MOFA チュートリアル：t_mofa_glue.ipynb
• SIMBA チュートリアル：t_simba.ipynb
• TOSICA チュートリアル：t_tosica.ipynb
• StaVIA チュートリアル：t_stavia.ipynb
• コピー＆ペースト用のコマンド：reference.md