Scanpy: 一細胞解析
概要
Scanpyは、AnnData上に構築された、一細胞RNA-seqデータを解析するためのスケーラブルなPythonツールキットです。このスキルは、品質管理、正規化、次元削減、クラスタリング、マーカー遺伝子同定、可視化、軌跡解析を含む完全な一細胞ワークフローに適用します。現在の安定リリース: scanpy 1.12.x (2026年1月)。
インストール
Python 3.12+ (scanpy 1.12はPython ≤3.11をサポート終了) および anndata ≥0.10 が必要です。
uv pip install "scanpy[leiden]"
[leiden] extraは、Leidenクラスタリングに必要なpython-igraphとleidenalgをインストールします。再現可能な環境のためには、バージョンを固定してください: uv pip install "scanpy[leiden]==1.12.1"。
大規模またはアウトオブコアのデータセットの場合、多くの関数がDask配列をサポートしています (実験的):
uv pip install "scanpy[leiden]" dask
DaskとScanpyの使用チュートリアルを参照してください。GPUアクセラレーションによるscanpy類似の操作には、別パッケージとしてrapids-singlecellを使用してください。
入力がRネイティブの一細胞オブジェクト (.rds, .RData, Seurat, または SingleCellExperiment) の場合、最初にRツールを使用して.h5adに変換し、その後Scanpyで読み込みます。エージェントがmacOS、Linux、Windowsでインストールと変換を実行する手順については、references/r_interop.mdを参照してください。
AnnDataの構造とI/Oの詳細については、anndataスキルを使用してください。確率的モデルとバッチ補正には、scvi-toolsを使用してください。
このスキルを使用するタイミング
このスキルは以下の場合に使用します:
- 一細胞RNA-seqデータ (.h5ad, 10X, CSV形式) の解析
.h5adに変換する必要があるR向け一細胞データセット (.rds,.RData, Seurat, SingleCellExperiment) の操作- scRNA-seqデータセットの品質管理の実行
- UMAP、t-SNE、またはPCA可視化の作成
- 細胞クラスターの同定とマーカー遺伝子の発見
- 遺伝子発現に基づく細胞型のアノテーション
- 軌跡推定または疑似時間解析の実施
- 出版品質の一細胞プロットの生成
スクリプトツールキット (ゼロからコードを書くよりもこれらを優先)
このスキルには、一般的な各ステップのための、すぐに実行可能なCLIスクリプトがscripts/にバンドルされています。scanpyコードを手書きする代わりにこれらを実行してください — 拡張子によるファイル読み込み、図の設定、適切なデフォルト値、生カウントの保存、進行状況のログ処理を行います。各スクリプトは.h5adを読み書きするため、連鎖させることができ、それぞれに--helpがあります。タスクがスクリプトでカバーされていない場合や、特殊なカスタマイズが必要な場合にのみ、scanpyコードを書くようにしてください。
すべてのスクリプトは共有のscripts/_common.pyヘルパー (読み込み、保存、図の設定) を使用します — これを他のスクリプトと一緒に配置してください。スキルディレクトリから実行するか、フルパスを渡してください。図はデフォルトで./figures/に出力されます。
| スクリプト | 目的 | 典型的な呼び出し |
|---|---|---|
run_pipeline.py | 1コマンドでの完全ワークフロー: 読み込み → QC → 正規化 → HVG → PCA → (バッチ) → UMAP → Leiden → マーカー | python scripts/run_pipeline.py raw.h5ad -o processed.h5ad |
inspect_data.py | 未知のデータセットの要約 (形状、obs/var、レイヤー、計算済みのもの、生 vs 正規化) | python scripts/inspect_data.py data.h5ad |
convert.py | 任意の形式 (10x ディレクトリ/.h5, csv, loom, mtx) を読み込み、.h5adを書き出す | python scripts/convert.py 10x_dir/ -o data.h5ad |
qc_analysis.py | QCメトリクス、前後プロット、フィルタリング、オプションでScrubletダブレット検出 | python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet |
preprocess.py | 正規化、log1p、HVG、オプションでスケーリング/回帰 (countsレイヤーとrawを保持) | python scripts/preprocess.py qc.h5ad -o norm.h5ad |
reduce_dimensions.py | PCA + 分散プロット、近傍、UMAP、オプションでt-SNE | python scripts/reduce_dimensions.py norm.h5ad -o red.h5ad |
batch_correct.py | 統合: harmony / bbknn / combat | python scripts/batch_correct.py red.h5ad -o int.h5ad --method harmony --batch-key sample |
cluster.py | Leiden (または louvain) を1つまたは複数の解像度で実行 | python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.6 1.0 |
find_markers.py | rank_genes_groups + グループごとのCSV + マーカープロット | python scripts/find_markers.py clu.h5ad --groupby leiden -o clu.h5ad |
annotate.py | JSON/CSVからクラスター → 細胞型をマッピング; オプションでマーカーリファレンスのドットプロット | python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping map.json |
score_genes.py | 遺伝子シグネチャ (JSON) および/または細胞周期フェーズのスコアリング | python scripts/score_genes.py ann.h5ad -o scored.h5ad --gene-sets sigs.json |
pseudobulk.py | サンプル × 細胞型でカウントを集約 → pydeseq2用の行列 | python scripts/pseudobulk.py ann.h5ad --by sample cell_type --out-prefix pb |
subset.py | obs値または遺伝子リストでサブセット化 (オプションで古い埋め込みをクリア) | python scripts/subset.py ann.h5ad -o tcells.h5ad --obs cell_type --keep "T cells" |
plot.py | 処理済みオブジェクトからumap/tsne/pca/violin/dotplot/heatmapなどを生成 | python scripts/plot.py ann.h5ad --kind dotplot --genes CD3D CD14 --groupby cell_type |
ワンショットのエンドツーエンド実行
# カウント → クラスタリング、マーカーアノテーションされたオブジェクト + 図 + マーカーCSV
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad \
--resolution 0.5 --n-top-genes 2000 --scrublet
# マルチサンプル統合の場合:
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --batch-key sample --batch-method harmony
# JSONによる再現可能なパラメータ (キーはアンダースコア付きのフラグ名に対応):
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --config params.json
ステップバイステップのチェーン (各段階間で検査/反復が必要な場合)
python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet
python scripts/preprocess.py qc.h5ad -o norm.h5ad --n-top-genes 2000
python scripts/reduce_dimensions.py norm.h5ad -o red.h5ad --n-pcs 40
python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.5 0.8
python scripts/find_markers.py clu.h5ad -o clu.h5ad --groupby leiden --use-raw
# 結果/マーカー/*.csvを検査し、ラベルを決定し、マッピングJSONを作成し、次に:
python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping celltypes.json
以下のセクションでは、各スクリプトが実行する基礎となるscanpy呼び出しを文書化しています — スクリプトのフラグを超えたカスタマイズが必要な場合にこれらを参照してください。
クイックスタート
基本的なインポートと設定
import scanpy as sc
import pandas as pd
import numpy as np
# 設定
sc.settings.verbosity = 3
sc.settings.set_figure_params(dpi=80, facecolor='white')
sc.settings.figdir = './figures/'
sc.settings.autosave = True # プロットごとのsave=よりも推奨 (scanpy 1.12で非推奨)
データの読み込み
# 10X Genomicsから
adata = sc.read_10x_mtx('path/to/data/')
adata = sc.read_10x_h5('path/to/data.h5')
# h5ad (AnnData形式) から
adata = sc.read_h5ad('path/to/data.h5ad')
# CSVから
adata = sc.read_csv('path/to/data.csv')
Rネイティブファイルの場合、PythonでSeuratの.rdsを直接解析しようとしないでください。最初に変換します:
# Rのインストールと変換パッケージについては references/r_interop.md を参照。
Rscript convert_rds_to_h5ad.R input.rds output.h5ad
adata = sc.read_h5ad('output.h5ad')
AnnData構造の理解
AnnDataオブジェクトはscanpyの中核となるデータ構造です:
adata.X # 発現行列 (細胞 × 遺伝子)
adata.obs # 細胞メタデータ (DataFrame)
adata.var # 遺伝子メタデータ (DataFrame)
adata.uns # 非構造化アノテーション (dict)
adata.obsm # 多次元細胞データ (PCA, UMAP)
adata.raw # 生データのバックアップ
# 細胞名と遺伝子名へのアクセス
adata.obs_names # 細胞バーコード
adata.var_names # 遺伝子名
標準解析ワークフロー
コードと各段階で重要なパラメータを含む7つのステップについては、 references/analysis_workflow.mdを参照してください:
- 品質管理 — 細胞と遺伝子をフィルタリング; デフォルトをコピーするのではなく、しきい値を選択する前にミトコンドリア分画とカウントを検査。
- 正規化と前処理 — 正規化、対数変換、高可変遺伝子の選択、後でプロットするために
.rawを保持。 - 次元削減 — PCA、次に近傍グラフ、そしてUMAP。
- クラスタリング — デフォルトではなく、問題に合わせて選択した解像度でLeiden。
- マーカー遺伝子同定 — クラスターごとにランク付けされた遺伝子。
- 細胞型アノテーション — マーカーからクラスターを型にマッピング。
- 結果の保存 — アノテーションされた
AnnDataを書き出し。
一般的な後続タスク — 出版プロット、軌跡推定、条件間の疑似バルク差次的発現、遺伝子セットスコアリング、バッチ補正 — は同じファイルにあります。references/standard_workflow.mdとreferences/plotting_guide.mdも参照してください。
調整すべき主要パラメータ
品質管理
min_genes: 細胞あたりの最小遺伝子数 (通常200-500)min_cells: 遺伝子あたりの最小細胞数 (通常3-10)pct_counts_mt: ミトコンドリアしきい値 (通常5-20%)
正規化
target_sum: 細胞あたりの目標カウント数 (デフォルト1e4)
特徴選択
n_top_genes: HVGの数 (通常2000-3000)min_mean,max_mean,min_disp: HVG選択パラメータ
次元削減
n_pcs: 主成分の数 (分散比プロットを確認)n_neighbors: 近傍の数 (通常10-30)
クラスタリング
resolution: クラスタリングの粒度 (0.4-1.2、高いほど多くのクラスター)
よくある落とし穴とベストプラクティス
- 常に生カウントを保存: 遺伝子をフィルタリングする前に
adata.raw = adata - QCプロットを注意深く確認: データセットの品質に基づいてしきい値を調整
- Leidenクラスタリングを使用:
sc.tl.louvainはscanpy 1.12で非推奨 - 複数のクラスタリング解像度を試す: 最適な粒度を見つける
- 細胞型アノテーションを検証: 複数のマーカー遺伝子を使用
- 遺伝子発現プロットには
use_raw=Trueを使用:.rawからの正規化カウントを表示 - PCA分散比を確認: 最適なPC数を決定
- 中間結果を保存: 長時間のワークフローは途中で失敗する可能性がある
- DEには疑似バルクを使用:
rank_genes_groupsのp値を条件間の厳密なDEとして扱わない - 設定を介してプロットを保存: プロット関数の非推奨の
save=の代わりにsc.settings.autosaveを使用 - Scanpyの前にRオブジェクトを変換: Rパッケージを使用してSeuratまたはSingleCellExperimentの
.rdsファイルを.h5adに変換し、カウント、メタデータ、遺伝子識別子を保持
バンドルリソース
scripts/ (CLIツールキット)
ワークフロー全体をカバーする、.h5ad入力/.h5ad出力のスクリプトの構成可能なセットと、1コマンドのエンドツーエンドパイプライン。完全なテーブルと連鎖の例については、上記のスクリプトツールキットセクションを参照してください。各スクリプトには--helpがあります。ファイル:
_common.py— 他のスクリプトがインポートする共有の読み込み/保存/図ヘルパー (CLIではない)run_pipeline.py— 1コマンドでの完全パイプライン (フラグまたは--configJSON)inspect_data.py,convert.py— 任意の入力形式の探索と読み込み/変換qc_analysis.py,preprocess.py,reduce_dimensions.py,batch_correct.py,cluster.py— パイプラインステップfind_markers.py,annotate.py,score_genes.py,pseudobulk.py— マーカー、アノテーション、スコアリング、DE準備subset.py,plot.py— メタデータ/遺伝子によるサブセット化; 任意の標準プロットを生成
scanpyコードをゼロから書く前に、これらのスクリプトをデフォルトで使用してください。
references/standard_workflow.md
詳細な説明とコード例を含む、ステップバイステップの完全なワークフロー:
- データの読み込みと設定
- 可視化付きの品質管理
- 正規化とスケーリング
- 特徴選択
- 次元削減 (PCA, UMAP, t-SNE)
- クラスタリング (Leiden)
- ダブレット検出 (scrublet) と疑似バルク集約
- マーカー遺伝子同定
- 細胞型アノテーション
- 軌跡推定
- 差次的発現
ゼロから完全な解析を実行する場合は、このリファレンスを読んでください。
references/api_reference.md
モジュール別に整理されたscanpy関数のクイックリファレンス:
- データの読み書き (
sc.read_*,adata.write_*) - 前処理 (
sc.pp.*) - ツール (
sc.tl.*) - プロット (
sc.pl.*) - AnnDataの構造と操作
- 設定とユーティリティ
関数シグネチャと一般的なパラメータのクイックルックアップに使用します。
references/plotting_guide.md
包括的な可視化ガイド:
- 品質管理プロット
- 次元削減の可視化
- クラスタリングの可視化
- マーカー遺伝子プロット (ヒートマップ、ドットプロット、バイオリンプロット)
- 軌跡と疑似時間プロット
- 出版品質のカスタマイズ
- マルチパネル図
- カラーパレットとスタイリング
出版可能な図を作成する際に参照してください。
references/r_interop.md
macOS、Linux、WindowsにRをインストールし、CRAN/Bioconductorの変換パッケージをインストールし、.rds/.RData入力を検査し、SeuratまたはSingleCellExperimentオブジェクトを.h5adに変換し、Scanpyで結果を検証するためのエージェント実行手順書。
assets/analysis_template.py
データの読み込みから細胞型アノテーションまでの完全なワークフローを提供する完全な解析テンプレート。新しい解析のためにこのテンプレートをコピーしてカスタマイズしてください:
cp assets/analysis_template.py my_analysis.py
# パラメータを編集して実行
python my_analysis.py
このテンプレートには、設定可能なパラメータと役立つコメントが付いたすべての標準ステップが含まれています。
assets/ JSONテンプレート
設定やマッピングをゼロから作成する代わりに編集して渡すテンプレート:
assets/pipeline_config.json—run_pipeline.py --config用のパラメータセットassets/celltype_mapping.json—annotate.py --mapping用のクラスター → 細胞型マップassets/gene_signatures.json—score_genes.py --gene-sets用の遺伝子セットシグネチャ
追加リソース
- 公式scanpyドキュメント: https://scanpy.scverse.org/en/stable/
- Scanpyチュートリアル: https://scanpy.scverse.org/en/stable/tutorials/
- AnnDataドキュメント: https://anndata.scverse.org/en/stable/
- scverseエコシステム: https://scverse.org/
関連スキル
- anndata: AnnDataオブジェクトの構造、I/O、操作の詳細
- scvi-tools: 深層確率モデル、バッチ補正、データセット統合
- pydeseq2: 疑似バルク差次的発現解析