single-cell-downstream-analysis

単一細胞ダウンストリーム解析クイックリファレンス

このスキルシートでは、OmicVerse の単一細胞ダウンストリームチュートリアルを、実行可能なチェックリストにまとめています。各モジュールでは、前提条件、主要な API エントリーポイント、解釈時のチェックポイント、リソース計画に関する注意事項、およびノートブックに記載されている任意の検証またはエクスポート手順を取り上げます。

防御的な検証パターン

ダウンストリームモジュールを実行する前に、前提条件を確認してください。

# Before AUCell: verify embeddings exist
assert 'X_umap' in adata.obsm or 'X_pca' in adata.obsm, \
    "Embedding required. Run ov.pp.umap(adata) or ov.pp.pca(adata) first."

# Before metacell DEG: verify raw counts are preserved
assert adata.raw is not None, "adata.raw required. Set adata.raw = adata.copy() before HVG filtering."

# Before SCENIC: verify raw counts (not log-transformed) are available
if hasattr(adata.X, 'max') and adata.X.max() < 20:
    print("WARNING: SCENIC expects raw counts. Data may be log-transformed.")

# Before scDrug: verify tumor annotations
# assert 'cell_type' in adata.obs.columns, "Cell type annotation required for scDrug"

AUCell 経路スコアリング（t_aucell.ipynb）

• 前提条件
  • チュートリアルを実行する前に、解析対象の生物種に合った経路コレクション（GO、KEGG、またはカスタム）をダウンロードしてください。
  • クラスタリング／埋め込み（adata.obsm['X_umap']）を含む AnnData オブジェクトを準備してください。
• 主要な呼び出し
  • 1 つの経路には ov.single.geneset_aucell、複数の経路には ov.single.pathway_aucell を使用します。
  • ライブラリ内のすべての経路をスコアリングするには ov.single.pathway_aucell_enrichment を使用します（並列処理には num_workers を設定します）。
• 結果の確認
  • AUCell スコアは発現値に似た値（0～1）として解釈します。sc.pl.embedding を使用して経路活性のパターンを確認してください。
  • AUCell の AnnData に対して sc.tl.rank_genes_groups を実行し、クラスターで濃縮された経路を見つけて、sc.pl.rank_genes_groups_dotplot で可視化します。
• リソース
  • ライブラリ全体のスコアリングは CPU 負荷が高くなる場合があります。ワーカー（チュートリアルでは num_workers=8）を割り当て、密な AUCell 行列に十分なメモリを確保してください。
• 任意の検証／エクスポート
  • スコアを adata_aucs.write_h5ad('...') で保存して、再利用できるようにします。
  • ov.single.pathway_enrichment と ov.single.pathway_enrichment_plot のヒートマップで、濃縮された経路をプロットします。

scRNA-seq DEG（バルク形式のメタセル）（t_scdeg.ipynb）

• 前提条件
  • 品質管理と前処理（ov.pp.qc、ov.pp.preprocess、ov.pp.scale、ov.pp.pca）を実行します。
  • HVG フィルタリングの前に、raw カウントを adata.raw に保持します。
• 主要な呼び出し
  • 全細胞ビューおよびメタセルビュー向けに、ov.bulk.pyDEG(test_adata.to_df(...).T) で差次解析オブジェクトを構築します。
  • GPU を利用できる場合は、ov.single.MetaCell(..., use_gpu=True) でメタセルを構築し、処理を高速化します。
• 結果の確認
  • ボルケーノプロット（dds.plot_volcano）と対象を絞った箱ひげ図（dds.plot_boxplot）で、上位の DEG を確認します。
  • ov.pl.embedding を使用して DEG マーカーを UMAP 埋め込みに対応付け、局在を確認します。
• リソース
  • メタセルの構築は GPU によって高速化できますが、CPU に切り替えることもできます。pyDEG に渡す転置済みの密行列に十分なメモリを確保してください。
• 任意の検証／エクスポート
  • メタセルの埋め込みを matplotlib の図として保存します。出版向けのビジュアルにするには legend_* 設定を調整してください。

scRNA-seq DEG（細胞型と組成）（t_deg_single.ipynb）

• 前提条件
  • condition、cell_label、および任意の batch メタデータを含む、注釈済みの adata。
  • グラフベースの DA 手法を使用する場合は、CPU／GPU 混合リソースを初期化します（ov.settings.cpu_gpu_mixed_init()）。
• 主要な呼び出し
  • 細胞型を対象とするには、ov.single.DEG(..., method='wilcoxon'|'t-test'|'memento-de') を使用し、deg_obj.run(...) を実行します。
  • 差次組成検定には ov.single.DCT(..., method='sccoda'|'milo') を使用します。
  • Milo のグラフ設定には ov.pp.preprocess、ov.single.batch_correction、ov.pp.neighbors、ov.pp.umap を使用します。
• 結果の確認
  • deg_obj の DEG テーブル（Wilcoxon／memento）を確認し、安定性を高めるためにキャプチャ率／ブートストラップ数を調整します。
  • scCODA では sim_results.set_fdr() で FDR を調整し、条件ごとの変化を踏まえて箱ひげ図を解釈します。
  • Milo の診断には、P 値のヒストグラム、logFC と –log10 FDR の散布図、差次的存在量のビースウォームプロットを使用します。
• リソース
  • Memento と Milo では複数の CPU が必要です（num_cpus、num_boot、大きな k）。十分な計算時間を確保してください。
  • Harmony／scVI によるバッチ補正を有効にする場合は GPU メモリが必要です。VRAM の使用量を見込んでください。
• 任意の検証／エクスポート
  • 視覚的な診断には、UMAP オーバーレイ（ov.pl.embedding）、Milo のビースウォームプロット、カスタムカラーパレットが含まれます。

scDrug 応答予測（t_scdrug.ipynb）

• 前提条件
  • 腫瘍に焦点を当てたデータセット（例：infercnvpy.datasets.maynard2020_3k）を取得します。
  • 予測を実行する前に、参照アセットをダウンロードします。
    • ov.utils.get_gene_annotation を使用して遺伝子アノテーションを取得します（GENCODE または T2T-CHM13 の GTF が必要です）。
    • 薬剤応答モデル用に ov.utils.download_GDSC_data() と ov.utils.download_CaDRReS_model() を実行します。
    • CaDRReS-Sc リポジトリをクローンします（git clone https://github.com/CSB5/CaDRReS-Sc）。
• 主な呼び出し
  • 腫瘍解像度の検出：ov.single.autoResolution(adata, cpus=4)。
  • 薬剤応答の実行：ov.single.Drug_Response(adata, scriptpath='CaDRReS-Sc', modelpath='models/', output='result')。
• 結果の確認
  • output に保存されたクラスタリングと IC50 の出力を確認し、推定された CNV 状態と照合します。
• リソース
  • 外部の CaDRReS-Sc 環境（Python/R の依存関係）と、モデルのダウンロード用ストレージが必要です。
  • inferCNV の前処理には、複数の CPU と大量の RAM が必要になる場合があります。
• 任意の検証／エクスポート
  • 中間の AnnData（adata.write('scanpyobj.h5ad')）を保存し、後続の解析や再実行に再利用できます。

SCENIC レギュロンの発見（t_scenic.ipynb）

SCENIC の包括的なガイダンス（データベースのダウンロード、RegDiffusion の調整、RSS の解釈、GRN の可視化）については、search_skills('SCENIC regulon GRN') を使用して、専用の SCENIC スキルを読み込んでください。

• 前提条件
  • ov.single.mouse_hsc_nestorowa16() を使用してマウスの造血データセットを読み込みます（または、raw counts を含む前処理済みデータを指定します）。
  • 対象種の cisTarget ランキングデータベース（*.feather）とモチーフアノテーション（motifs-*.tbl）をダウンロードします。ディスク容量を

    3 GB 確保し、パス（db_glob、motif_path）を確認してください。

• 主な呼び出し
  • 解析を初期化します：ov.single.SCENIC(adata, db_glob=..., motif_path=..., n_jobs=12)。
  • SCENIC オブジェクトのメソッドを使用して、RegDiffusion ベースの GRN 推論、レギュロンのプルーニング、AUCell スコアリングを実行します。
• 結果の確認
  • レギュロン活性行列（scenic_obj.auc_mtx.head()）、RSS スコア、レギュロン活性で色分けした埋め込みを確認します。
  • RSS プロット、デンドログラム、AUCell 分布を使用して、TF の特異性と活性のしきい値を解釈します。
• リソース
  • マルチコア CPU を推奨します（n_jobs は利用可能なコア数に合わせます）。モチーフエンリッチメントに十分な RAM を確保してください。
  • 大容量のダウンロードと中間オブジェクト（pickle/h5ad）にはディスク容量が必要です。
• 任意の検証／エクスポート
  • scenic_obj（ov.utils.save）とレギュロン AnnData（regulon_ad.write）を保存します。
  • 任意のプロット：細胞型ごとの RSS、レギュロンの埋め込み、しきい値の線を示した AUC ヒストグラム、GRN ネットワークの可視化。

cNMF プログラムの発見（t_cnmf.ipynb）

• 前提条件
  • HVG の選択（ov.pp.preprocess）、スケーリング（ov.pp.scale）、PCA で前処理し、確認用の UMAP 埋め込みを用意します。
  • 成分の範囲（例：np.arange(5, 11)）と反復回数を選択し、出力ディレクトリが存在することを確認します。
• 主な呼び出し
  • 解析をインスタンス化します：ov.single.cNMF(..., output_dir='...', name='...')。
  • 因子分解のワークフロー：cnmf_obj.factorize(...)、cnmf_obj.combine(...)、cnmf_obj.k_selection_plot()、 cnmf_obj.consensus(...)。
  • 結果を抽出します：cnmf_obj.load_results(...)、cnmf_obj.get_results(...)、および任意の RF 分類器（get_results_rfc）。
• 結果の確認
  • K 選択プロットと局所密度ヒストグラムで安定性を評価し、コンセンサスヒートマップで選択した K を確認します。
  • トピック使用量の埋め込み（ov.pl.embedding）、クラスタラベル、上位遺伝子のドットプロットを確認します。
• リソース
  • 複数の反復と成分の処理には多くの CPU が必要です。ワーカー（total_workers）の分散を検討し、中間の因子分解ファイル用のディスク 容量を確認してください。
• 任意の検証／エクスポート
  • ユークリッド距離のヒートマップ、密度ヒストグラム、トピック／クラスタの UMAP オーバーレイ、ドットプロットなどで可視化できます。

NOCD の重複コミュニティ（t_nocd.ipynb）

• 前提条件
  • NOCD を実行する前に、ov.single.scanpy_lazy（自動前処理）で AnnData を準備します。
  • 注：チュートリアルでは、NOCD の実装は現在も開発中のため、結果にばらつきが生じる可能性があると警告しています。
• 主な呼び出し
  • パイプラインのラッパー：scbrca = ov.single.scnocd(adata) を実行し、その後メソッドを連結します（matrix_transform、matrix_normalize、 GNN_configure、GNN_preprocess、GNN_model、GNN_result、GNN_plot、cal_nocd、calculate_nocd）。
• 結果の確認
  • UMAP 埋め込み上で標準の Leiden クラスタリングと NOCD の出力を比較し、複数の運命を持つ細胞を特定します。
• リソース
  • グラフニューラルネットワークの各段階は GPU で高速化できます。CUDA が利用可能であることを確認するか、CPU では実行時間が長くなる可能性に備えてください。
  • 大規模な隣接行列を作成する際は、メモリ使用量を監視してください。
• 任意の検証／エクスポート
  • 共通のカラーマップを使い、nocd、nocd_n、Leiden ラベルの UMAP オーバーレイを複数生成します（sc.pl.umap）。

遅延パイプラインとレポート（t_lazy.ipynb）

• 前提条件
  • 遅延ユーティリティに対応した OmicVerse ≥1.7.0 をインストールします。現在サポートされている生物種はヒトとマウスです。
  • バッチメタデータ（sample_key）を準備し、必要に応じてハイブリッド計算を初期化します（ov.settings.cpu_gpu_mixed_init()）。
• 主な呼び出し
  • 一括前処理：ov.single.lazy(adata, species='mouse', sample_key='batch', ...) を使用し、必要に応じて reforce_steps やモジュール固有の kwargs を指定します。
  • レポート：ov.single.generate_scRNA_report(...) で HTML サマリーを作成し、ov.generate_reference_table(adata) で 引用情報を管理します。
• 結果の確認
  • 生成された埋め込み（ov.pl.embedding）で、品質とアノテーションとの整合性を確認します。
  • HTML レポートで QC 指標、正規化、バッチ補正、埋め込みを確認します。
• リソース
  • Harmony や scVI などのステップでは GPU が使われる場合があります。ハードウェアが利用可能であることを確認するか、それに応じて reforce_steps を調整してください。
  • レポートの生成時にはディスクに書き込みます。出力先のパスに書き込み権限があることを確認してください。
• 任意の検証／エクスポート
  • 色分けキーを指定して埋め込みをカスタマイズします。HTML レポートと参照テーブルは、プロジェクトのドキュメントと併せて保存します。