single-cell-cellphonedb-communication-mapping

単一細胞 CellPhoneDB 通信マッピング

概要

アノテーション済みの単一細胞集団間のリガンド・受容体間の通信を定量化し、OmicVerse の CellPhoneDB プロットスタックで結果を可視化する場合に、このスキルを適用します。このスキルでは、従来の低レベルな ov.pl.CellChatViz ワークフローと、新しい公開プロット API の両方を扱います。

• ov.pl.ccc_heatmap(...)
• ov.pl.ccc_network_plot(...)
• ov.pl.ccc_stat_plot(...)

安定した公開 API を使って、論文掲載に適したプロットをすばやく作成する場合は、デフォルトで ccc_* 関数を使用してください。メソッドレベルでの制御が必要な場合や、1 つのノートブック内で複数のカスタム可視化を組み合わせる場合は、CellChatViz を使用してください。

手順

1. 環境を準備する
   • omicverse>=0.2、scanpy、anndata、pandas、matplotlib、seaborn、および CellPhoneDB のリソースを利用できる環境を使用します。
   • 新しい可視化を使用する場合は、必要に応じて次のオプションのプロット用依存関係も利用できることを確認します。
     • ヒートマップとバブル行列プロッターには marsilea。
     • コード図には mpl-chord-diagram。
     • 拡散プロットおよびネットワーク形式のプロットには networkx。
     • ラベルの自動反発を改善したい場合は adjustText。
   • ov.plot_set() を使用して OmicVerse のプロット設定を有効にします。
2. アノテーション済み AnnData を読み込み、検証する
   • 正規化済み発現行列を ov.read(...) で読み込みます。
   • 通信グループ列をクリーンなカテゴリ列にし、意図した識別子と一致させます。
   • 推奨する確認事項：

     celltype_key = "cell_labels"
     assert celltype_key in adata.obs.columns, f"{celltype_key} missing from adata.obs"
     adata.obs[celltype_key] = adata.obs[celltype_key].astype("category").cat.remove_unused_categories()
     assert not adata.obs[celltype_key].isna().any(), f"NaN values found in {celltype_key}"
     min_per_group = adata.obs[celltype_key].value_counts().min()
     if min_per_group < 10:
         print(f"WARNING: smallest group has {min_per_group} cells; sparse groups may destabilize permutations")
     

   • CellPhoneDB を実行する前に、行列がログ正規化済みであることを確認します。生のカウントは、置換ベースの有意性を歪める可能性があります。
3. OmicVerse 経由で CellPhoneDB を実行する
   • ov.single.run_cellphonedb_v5(...) を使用し、出力を保存します。

     cpdb_results, adata_cpdb = ov.single.run_cellphonedb_v5(
         adata,
         cpdb_file_path="./cellphonedb.zip",
         celltype_key="cell_labels",
         min_cell_fraction=0.005,
         min_genes=200,
         min_cells=3,
         iterations=1000,
         threshold=0.1,
         pvalue=0.05,
         threads=10,
         output_dir="./cpdb_results",
         cleanup_temp=True,
     )
     

   • 置換を再実行せずに後続のプロットを繰り返せるよう、cpdb_results と adata_cpdb を保存します。
   • CellChat の代替手段（R 不要、PyTorch 以外の追加インストール不要）：ov.single.run_cellchat は R CellChat 2.2 を再現し（過剰発現遺伝子／LR ペアは同一、確率は約 1e-15 まで一致）、adata.uns['cellchat_res'] に結果を格納します。すべての ov.pl.ccc_* 呼び出しはこの結果を直接読み込みます。

     ov.single.run_cellchat(adata, groupby="cell_labels", species="human")  # log-normalised X
     comm = ov.single.format_cellchat_results(adata)                         # optional explicit comm AnnData
     df = ov.single.cellchat_subset_communication(adata, signaling=["TGFb"])  # significant LR table
     centr = ov.single.cellchat_centrality(adata)                             # sender/receiver/mediator/influencer
     

     CellChat スコアは発現量ではなく確率（約 1e-3）です。パスウェイの要約では、スケールに応じたしきい値が自動的に選ばれます。細胞数が min_cells（デフォルトは 10）以下のグループは、R の filterCommunication と同様に除外されます。
4. 標準的な可視化の依頼には、新しい公開プロット API を優先する
   • 行列形式のプロットには ov.pl.ccc_heatmap(...) を使用します。
     • plot_type="heatmap" は、集約したパスウェイレベルの通信に使用します。
     • plot_type="focused_heatmap" は、弱い項目をしきい値で除外して、より強い相互作用を強調する場合に使用します。
     • plot_type="dot" または "bubble" は、相互作用レベルの要約に使用します。
     • plot_type="pathway_bubble" は、Marsilea によるパスウェイに焦点を当てたバブル要約に使用します。
     • plot_type="bubble_lr" は、リガンド・受容体ペアごとのバブル行列に使用します。
     • plot_type="role_heatmap"、"role_network"、または "role_network_marsilea" は、シグナル伝達の役割の要約に使用します。
     • plot_type="diff_heatmap" は、2 つの通信 AnnData オブジェクトを比較する場合に使用します。
   • グラフ形式のプロットには ov.pl.ccc_network_plot(...) を使用します。
     • plot_type="circle" または "circle_focused" は、全体的な通信ネットワークに使用します。
     • plot_type="individual_outgoing"／"individual_incoming" は、送信側または受信側を中心とする円形パネルに使用します。
     • plot_type="individual" は、単一のパスウェイと、必要に応じて選択した L-R ペアに使用します。
     • plot_type="chord" は、細胞タイプレベルのパスウェイコードに使用します。
     • plot_type="gene_chord" は、パスウェイ固有のリガンドノードと受容体ノードを横断する遺伝子レベルのコード図に使用します。
     • plot_type="lr_chord" は、指定したリガンド・受容体ペアに使用します。
     • plot_type="diffusion" は、パスウェイの類似性と拡散形式のネットワーク構造に使用します。
     • plot_type="diff_network" は、2 つの通信オブジェクトを比較する場合に使用します。
     • plot_type="bipartite"、"arrow"、"sigmoid"、または "embedding_network" は、別のレイアウトに使用します。
   • 統計情報や要約パネルには ov.pl.ccc_stat_plot(...) を使用します。
     • plot_type="pathway_summary" は、通信強度と有意性に基づくパスウェイの順位付けに使用します。
     • plot_type="lr_contribution" は、パスウェイ内で優勢なリガンド・受容体ペアを表示する場合に使用します。
     • plot_type="scatter" または "role_scatter" は、送信側と受信側のシグナル伝達の役割を比較する場合に使用します。
     • plot_type="role_network" または "role_network_marsilea" は、行列形式の役割の要約に使用します。
     • plot_type="sankey" は、通信フローの要約に使用します。
5. 手法レベルの制御が必要な場合は CellChatViz を直接使用する
   • 細胞ラベルから安定したパレットの対応付けを作成します。

     color_dict = dict(zip(
         adata.obs["cell_labels"].cat.categories,
         adata.uns["cell_labels_colors"]
     ))
     viz = ov.pl.CellChatViz(adata_cpdb, palette=color_dict)
     

   • 推奨する直接的なワークフロー：
     • viz.compute_aggregated_network(...) の後に viz.netVisual_circle(...) を実行します。
     • viz.compute_pathway_communication(...) の後に viz.get_significant_pathways_v2(...) を実行します。
     • viz.netVisual_heatmap_marsilea(...) または viz.netVisual_heatmap_marsilea_focused(...) を使用します。
     • パスウェイのバブル表示には viz.netVisual_bubble_marsilea(...) を使用します。
     • 選択したリガンド・受容体ペアには viz.netVisual_bubble_lr(...) を使用します。
     • viz.netVisual_chord_cell(...)、viz.netVisual_chord_gene(...)、および viz.netVisual_chord_LR(...) を使用します。
     • 1 つのパスウェイ／濃縮された 1 つのペアには viz.netVisual_individual(...) を使用します。
     • viz.netAnalysis_computeCentrality() の後に、役割のヒートマップ、散布図、ネットワークプロットを作成します。
     • パスウェイレベルのペア寄与分析には viz.netAnalysis_contribution(pathway) を使用します。
     • パスウェイの類似性構造には viz.netVisual_diffusion(...) を使用します。
6. 新しい可視化機能を明確に紹介する
   • 回答で紹介する価値のある新しい追加機能：
     • gene_chord：細胞タイプレベルのコードだけでなく、遺伝子レベルのコード図も作成できます。
     • bubble_lr：明示的なリガンド・受容体ペアを中心とした Marsilea のバブル要約を作成できます。
     • focused_heatmap：弱い相互作用を抑制する、しきい値適用済みのパスウェイヒートマップです。
     • role_network_marsilea：デンドログラム、カラーバー、重要度バーを備えた、より詳細な役割の要約を作成できます。
     • diffusion：通信パターンに基づくパスウェイ類似性ネットワークを作成できます。
     • pathway_summary と lr_contribution：優先順位付けに役立つ、より高次の要約／統計表示です。
   • ユーザーが「新しい可視化」と言った場合は、従来の円形プロットだけでなく、これらの機能のいずれかを優先して紹介します。
7. 新しいプロットのパラメーターに関するヒント
   • パスウェイバブルの場合：
     • group_pathways=True は、個々の L-R ペアではなくパスウェイごとにまとめます。
     • セルペアの行が多すぎてラベルが読みにくい場合は、transpose=True が便利です。
     • add_violin=True を指定するとスコア分布を確認できますが、図はより密になります。
   • リガンド・受容体のバブルの場合：
     • 一部のペアが弱い場合や存在しない場合でも、固定したペアの一覧を比較したいときは show_all_pairs=True が便利です。
     • pair_lr_use または interaction_use は、adata.var 内のペア名と一致させる必要があります。
   • 遺伝子コード図の場合：
     • adata.var["gene_a"] と adata.var["gene_b"] が必要です。
     • 遺伝子名や細胞タイプのラベルが長い場合は、rotate_names=True を使用します。
   • フォーカス付きヒートマップとフォーカス付き円形プロットの場合：
     • プロット前に弱いエッジを除外するには、min_interaction_threshold を調整します。
   • 役割プロットの場合：
     • 低レベル API を使用する場合は、最初に viz.netAnalysis_computeCentrality() を実行します。
     • 解釈しやすい送信側プログラムと受信側プログラムを表示するには、pattern="incoming" と pattern="outgoing" を別々に使用します。
8. トラブルシューティング
   • メタデータの整合性：通信グループ列はカテゴリ型で、欠損値がない必要があります。
   • データベースバンドル：cpdb_file_path は、有効な CellPhoneDB v5 の SQLite zip を指している必要があります。
   • 疎なグループ：送信側または受信側のグループが非常に小さいと、結果が不安定になったり空になったりすることがあります。
   • adata.var 内の列の欠落：
     • パスウェイで絞り込むプロットには classification が必要です。
     • 遺伝子レベルまたはリガンド・受容体ペア固有のプロットには gene_a と gene_b が必要です。
   • オプションの依存関係に関するエラー：
     • pathway_bubble、bubble_lr、フォーカス付きヒートマップ、および Marsilea による役割ネットワーク表示には marsilea をインストールします。
     • コード図には mpl-chord-diagram をインストールします。
     • ラベルの重なりがひどい場合は adjustText をインストールします。
   • パレットの不一致：adata.obs[celltype_key].cat.categories のソート済みカテゴリと、対応する adata.uns[f"{celltype_key}_colors"] からパレットを再構築します。

例

• 「CellPhoneDBを実行してから、ov.pl.ccc_heatmap(..., plot_type='focused_heatmap')を使用して、最も強い経路を表示します。」
• 「ov.pl.ccc_network_plot(..., plot_type='gene_chord')を使用して、FGFシグナル伝達の遺伝子レベルのコード図を作成します。」
• 「plot_type='bubble_lr'を使用して、選択したリガンド・受容体ペアを送信側と受信側の組み合わせごとに比較します。」
• 「ccc_stat_plot(..., plot_type='pathway_summary')で上位の経路を要約し、plot_type='lr_contribution'で経路内のリガンド・受容体の寄与を順位付けします。」
• 「CellChatVizを直接使用して、中心性を計算し、Marsileaの役割ネットワーク図を描画します。」

参考資料

• チュートリアルノートブック：t_cellphonedb.ipynb
• サンプルデータ：omicverse_guide/docs/Tutorials-single/data/cpdb/
• コピー＆ペースト用のクイックコマンド：reference.md