single-cell-annotation-skills-with-omicverse

omicverse によるシングルセルアノテーションのスキル

概要

このスキルでは、omicverse のチュートリアルにまとめられたシングルセルアノテーションの手順を再現し、応用する方法を紹介します。対象は、SCSA t_cellanno.ipynb、MetaTiME t_metatime.ipynb、CellVote t_cellvote.md と t_cellvote_pbmc3k.ipynb、CellMatch t_cellmatch.ipynb、GPTAnno t_gptanno.ipynb、ラベル転送 t_anno_trans.ipynb です。以下の各セクションでは、必要な入力、学習／推論の手順、出力の読み取り方を説明します。

手順

1. SCSA による自動クラスタアノテーション

   • データ要件：10x Genomics の PBMC3k 生カウント（pbmc3k_filtered_gene_bc_matrices.tar.gz）または処理済みの sample/rna.h5ad を使用します。ダウンロード手順はノートブックに記載されています。data/filtered_gene_bc_matrices/hg19/ に展開してください。SCSA の SQLite データベース（チュートリアルに記載された Figshare／Drive のリンクから入手できる pySCSA_2024_v1_plus.db など）が利用可能であることを確認し、model_path に保存先を指定します。
   • 前処理とモデルの適合：ov.io.read_10x_mtx で読み込み、QC（ov.pp.qc）、正規化と高変動遺伝子（HVG）の選択（ov.pp.preprocess）、スケーリング（ov.pp.scale）、PCA（ov.pp.pca）、近傍探索、Leiden クラスタリングを実行し、マーカー遺伝子の順位を計算します（sc.tl.rank_genes_groups）。target='cellmarker' または 'panglaodb'、組織の範囲、閾値（foldchange、pvalue）を選択して、scsa = ov.single.pySCSA(...) をインスタンス化します。
   • 推論と解釈：scsa.cell_anno(clustertype='leiden', result_key='scsa_celltype_cellmarker') または scsa.cell_auto_anno を呼び出し、予測結果を adata.obs に追加します。ov.pl.embedding または sc.pl.dotplot を使って手動のマーカーベースのラベルと比較し、マーカー辞書（ov.single.get_celltype_marker）を確認して、対応している組織を scsa.get_model_tissue() で調べます。ROI／ROE ヘルパー（ov.utils.roe、ov.utils.plot_cellproportion）を使って、存在量の傾向を検証します。

2. MetaTiME による腫瘍微小環境の状態推定

   • データ要件：scVI 潜在埋め込みを含む、バッチ処理済みの TME AnnData を使用します。チュートリアルでは、Figshare の TiME_adata_scvi.h5ad（https://figshare.com/ndownloader/files/41440050）を使用します。カウントから始める場合は、まず scVI（scvi.model.SCVI）を実行して adata.obsm['X_scVI'] にデータを格納します。
   • 前処理とモデルの適合：必要に応じて、adata.obs['isTME'] を使い、悪性ではない細胞に絞り込みます。潜在表現を使って近傍を再構築し（sc.pp.neighbors(adata, use_rep="X_scVI")）、umap で埋め込みを生成します（adata.obsm['X_umap'] = ov.pp.umap(...)）。TiME_object = ov.single.MetaTiME(adata, mode='table') を初期化します。より細かな粒度が必要な場合は、TiME_object.overcluster(resolution=8, clustercol='overcluster') で過剰クラスタリングします。
   • 推論と解釈：TiME_object.predictTiME(save_obs_name='MetaTiME') を実行して、マイナー状態と Major_MetaTiME を割り当てます。TiME_object.plot または sc.pl.embedding を使って可視化します。クラスタレベルの分布を比較し、MetaTiME 列と Major_MetaTiME 列が想定されるニッチに対応していることを確認して、出力を解釈します。

3. CellVote コンセンサスラベリング

   • データ要件：クラスタリング済みの AnnData（たとえば、CELLVOTE_PBMC3K 環境変数または data/pbmc3k.h5ad に保存された PBMC3k）と、事前に計算したアノテーション列を少なくとも2つ用意します（チュートリアルでは scsa_annotation、gpt_celltype、gbi_celltype としてシミュレーションしています）。sc.tl.rank_genes_groups を使って、クラスターごとのマーカー遺伝子を準備します。
   • 前処理とモデルの適合：標準的な前処理（正規化、log1p、HVG、PCA、近傍探索、Leiden）の後、marker_dict = top_markers_from_rgg(adata, 'leiden', topn=10) または ov.single.get_celltype_marker を使ってマーカー辞書を作成します。cv = ov.single.CellVote(adata) をインスタンス化します。
   • 推論と解釈：cv.vote(clusters_key='leiden', cluster_markers=marker_dict, celltype_keys=[...], species='human', organization='PBMC', provider='openai', model='gpt-4o-mini') を呼び出します。オフラインの例では API 呼び出しを避けるために調停処理をモンキーパッチしています。オンライン投票には有効な認証情報が必要です。最終的なコンセンサスラベルは adata.obs['CellVote_celltype'] に格納されます。各クラスターの多数決結果を入力元（adata.obs[['leiden', 'scsa_annotation', ...]]）と比較し、判断の根拠を確認します。

4. CellMatch オントロジーマッピング

   • データ要件：adata.obs['cell_label'] を含む、pertpy.dt.haber_2017_regions() などのアノテーション済み AnnData を用意します。ov.single.download_cl(...) または手動のリンクから Cell Ontology の JSON（cl.json）をダウンロードします。任意で Cell Taxonomy リソース（Cell_Taxonomy_resource.txt）も用意できます。SentenceTransformer モデル（sentence-transformers/all-MiniLM-L6-v2、BAAI/bge-base-en-v1.5 など）を利用できるようにし、オフラインの場合は local_model_dir にダウンロードします。
   • 前処理とモデルの適合：ov.single.CellOntologyMapper(cl_obo_file='new_ontology/cl.json', model_name='sentence-transformers/all-MiniLM-L6-v2', local_model_dir='./my_models') でマッパーを作成します。mapper.map_adata(...) を実行して、オントロジー由来のラベル／IDを割り当てます。必要に応じて、load_cell_taxonomy_resource の呼び出し後に use_taxonomy=True を設定し、タクソノミーマッチングを有効にできます。
   • 推論と解釈：マッピングの概要（mapper.print_mapping_summary_taxonomy）を確認し、cell_ontology、cell_ontology_cl_id、enhanced_cell_ontology で色分けした埋め込みを調べます。mapper.find_similar_cells('T helper cell')、mapper.get_cell_info(...) などのヘルパークエリやカテゴリの閲覧を使って、オントロジーの網羅性を検証します。

5. GPTAnno による LLM 活用アノテーション

   • データ要件：同じ PBMC3k データセット（生の行列または .h5ad）とクラスター割り当てを用意します。LLM エンドポイントにアクセスできるようにします。OpenAI 互換プロバイダー（provider='openai'、'qwen'、'kimi' など）では AGI_API_KEY を設定するか、ov.single.gptcelltype_local 用のローカルモデルパスを指定します。
   • 前処理とモデルの適合：前述の SCSA ワークフローで説明した QC、正規化、HVG、スケーリング、PCA、近傍探索、Leiden、マーカー検出の手順に従います（SCSA ワークフローの出力を再利用できます）。ov.single.get_celltype_marker(adata, clustertype='leiden', rank=True, key='rank_genes_groups', foldchange=2, topgenenumber=5) を使って、マーカー辞書を自動的に作成します。
   • 推論と解釈：組織／種のコンテキストと希望するプロバイダー／モデルを指定して、ov.single.gptcelltype(...) を呼び出します。応答を後処理してラベルを整え（result[key].split(': ')[-1]...）、adata.obs['gpt_celltype'] に書き込みます。埋め込み（ov.pl.embedding(..., color=['leiden','gpt_celltype'])）を比較し、クラスターの識別を検証します。オフラインで実行する場合は、ダウンロード済みの指示チューニング済みチェックポイントを使って ov.single.gptcelltype_local を呼び出します。

6. 重み付き KNN によるアノテーション転送

   • データ要件: 埋め込みが整列されたクロスモーダル GLUE 出力。例: data/analysis_lymph/rna-emb.h5ad（アノテーション済み RNA）と data/analysis_lymph/atac-emb.h5ad（クエリ ATAC）。両方に obsm['X_glue'] が含まれます。
   • 前処理とモデル fitting: 両方のモダリティを読み込み、必要に応じて QC プロット用に連結し、ov.utils.mde で共通の低次元埋め込みを計算します。ov.utils.weighted_knn_trainer(train_adata=rna, train_adata_emb='X_glue', n_neighbors=15) を使用して近傍モデルを学習します。
   • 推論と解釈: labels, uncert = ov.utils.weighted_knn_transfer(query_adata=atac, query_adata_emb='X_glue', label_keys='major_celltype', knn_model=knn_transformer, ref_adata_obs=rna.obs) を介してラベルを転送します。予測を atac.obs['transf_celltype'] に、不確実性を atac.obs['transf_celltype_unc'] に保存します。命名を統一したい場合は major_celltype にコピーしてください。可視化（ov.pl.embedding）し、不確実性を確認して曖昧な細胞にフラグを立てます。

防御的バリデーションパターン

# Before SCSA: verify rank_genes_groups has been computed
assert 'rank_genes_groups' in adata.uns, \
    "Marker genes required. Run sc.tl.rank_genes_groups(adata, groupby='leiden') first."

# Before any annotation: verify clustering exists
assert 'leiden' in adata.obs.columns or 'louvain' in adata.obs.columns, \
    "Clustering required. Run ov.pp.leiden(adata) or sc.tl.leiden(adata) first."

# Before CellVote: verify multiple annotation columns exist
annotation_keys = ['scsa_annotation', 'gpt_celltype']  # adjust to actual keys
for key in annotation_keys:
    assert key in adata.obs.columns, f"Annotation column '{key}' not found — run annotators first"

重要な API リファレンス - 正確な関数シグネチャ

pySCSA - 重要: パラメータは clustertype であり、cluster ではありません

正しい使用法:

# Step 1: Initialize pySCSA
scsa = ov.single.pySCSA(
    adata,
    foldchange=1.5,
    pvalue=0.01,
    species='Human',
    tissue='All',
    target='cellmarker'  # or 'panglaodb'
)

# Step 2: Run annotation - NOTE: use clustertype='leiden', NOT cluster='leiden'!
anno_result = scsa.cell_anno(clustertype='leiden', cluster='all')

# Step 3: Add cell type labels to adata.obs
scsa.cell_auto_anno(adata, clustertype='leiden', key='scsa_celltype')
# Results are stored in adata.obs['scsa_celltype']

誤り - 使用しないでください:

# WRONG! 'cluster' is NOT a valid parameter for cell_auto_anno!
# scsa.cell_auto_anno(adata, cluster='leiden')  # ERROR!

COSG マーカー遺伝子 - 結果は adata.uns に保存され、adata.obs ではありません

正しい使用法:

# Step 1: Run COSG marker gene identification
ov.single.cosg(adata, groupby='leiden', n_genes_user=50)

# Step 2: Access results from adata.uns (NOT adata.obs!)
marker_names = adata.uns['rank_genes_groups']['names']  # DataFrame with cluster columns
marker_scores = adata.uns['rank_genes_groups']['scores']

# Step 3: Get top markers for specific cluster
cluster_0_markers = adata.uns['rank_genes_groups']['names']['0'][:10].tolist()

# Step 4: To create celltype column, manually map clusters to cell types
cluster_to_celltype = {
    '0': 'T cells',
    '1': 'B cells',
    '2': 'Monocytes',
}
adata.obs['cosg_celltype'] = adata.obs['leiden'].map(cluster_to_celltype)

誤り - 使用しないでください:

# WRONG! COSG does NOT create adata.obs columns directly!
# adata.obs['cosg_celltype']  # This key does NOT exist after running COSG!
# adata.uns['cosg_celltype']  # This key also does NOT exist!

避けるべき一般的な落とし穴

1. pySCSA のパラメータの混同:

   • clustertype = クラスタラベルを含む obs 列（例: 'leiden'）
   • cluster = アノテーションする特定のクラスタ（'all' または特定のクラスタ ID）
   • これらは異なるパラメータです！

2. COSG の結果へのアクセス:

   • COSG はマーカー遺伝子の検出ツールであり、細胞型アノテーターではありません
   • 結果はクラスタごとの遺伝子ランキングとして adata.uns['rank_genes_groups'] に保存されます
   • 細胞型を割り当てるには、マーカーに基づいてクラスタを手動で細胞型にマッピングする必要があります

3. OmicVerse における結果の保存パターン:

   • 細胞型アノテーション → adata.obs['<key>']
   • マーカー遺伝子の結果 → adata.uns['<key>']（'names'、'scores'、'logfoldchanges' を含む）
   • differential expression → adata.uns['rank_genes_groups']

例

• 「PBMC3k で CellMarker と PanglaoDB の両方のリファレンスを使用して SCSA を実行し、結果を CellVote に渡す前に手動のマーカー割り当てとベンチマーク比較してください。」
• 「MetaTiME Figshare データセットの腫瘍微小環境状態をアノテーションし、Major_MetaTiME クラスをハイライトし、患者ごとのラベル分布をエクスポートしてください。」
• 「Cell Ontology リソースをダウンロードし、haber_2017_regions クラスタをオントロジー用語にマッピングし、Cell Taxonomy のヒントを使用して曖昧なクラスタを補強してください。」
• 「RNA 由来の major_celltype ラベルを GLUE 統合された ATAC 細胞に伝播させ、転送の不確実性が高いクラスタを報告してください。」

リファレンス

• チュートリアルとノートブック: t_cellanno.ipynb、t_metatime.ipynb、t_cellvote.md、t_cellvote_pbmc3k.ipynb、t_cellmatch.ipynb、t_gptanno.ipynb、t_anno_trans.ipynb。
• サンプルデータとアセット: 10x Genomics の PBMC3k マトリクス、MetaTiME TiME_adata_scvi.h5ad（Figshare）、SCSA データベースのダウンロード、data/analysis_lymph/ 配下の GLUE 埋め込み、Cell Ontology cl.json、Cell Taxonomy リソース。
• クイックコピーコマンド: reference.md。