scanpy

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] エクストラをインストールすると、Leiden クラスタリングに必要な python-igraph と leidenalg がインストールされます。環境を再現可能にするには、バージョンを固定してください：uv pip install "scanpy[leiden]==1.12.1"。

大規模なデータセットやメモリ外データセットでは、多くの関数が Dask 配列をサポートしています（実験的）：

uv pip install "scanpy[leiden]" dask

Scanpy での dask の使用チュートリアルを参照してください。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、レイヤー、計算済みの項目、生データか正規化済みか）	python scripts/inspect_data.py data.h5ad
convert.py	任意の形式（10x dir/.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	1 つまたは複数の解像度で Leiden（または louvain）を実行	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

エンドツーエンドの一括実行

# Counts → clustered, marker-annotated object + figures + marker CSVs
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad \
    --resolution 0.5 --n-top-genes 2000 --scrublet
# With multi-sample integration:
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --batch-key sample --batch-method harmony
# Reproducible parameters via JSON (keys mirror flag names with underscores):
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
# inspect results/markers/*.csv, decide labels, write a mapping JSON, then:
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

# Configure settings
sc.settings.verbosity = 3
sc.settings.set_figure_params(dpi=80, facecolor='white')
sc.settings.figdir = './figures/'
sc.settings.autosave = True  # Preferred over per-plot save= (deprecated in scanpy 1.12)

データの読み込み

# From 10X Genomics
adata = sc.read_10x_mtx('path/to/data/')
adata = sc.read_10x_h5('path/to/data.h5')

# From h5ad (AnnData format)
adata = sc.read_h5ad('path/to/data.h5ad')

# From CSV
adata = sc.read_csv('path/to/data.csv')

R ネイティブ形式のファイルについては、Seurat の .rds を Python で直接解析しようとしないでください。先に変換してください。

# See references/r_interop.md for installing R and conversion packages.
Rscript convert_rds_to_h5ad.R input.rds output.h5ad

adata = sc.read_h5ad('output.h5ad')

AnnData の構造を理解する

AnnData オブジェクトは、scanpy の中核となるデータ構造です。

adata.X          # Expression matrix (cells × genes)
adata.obs        # Cell metadata (DataFrame)
adata.var        # Gene metadata (DataFrame)
adata.uns        # Unstructured annotations (dict)
adata.obsm       # Multi-dimensional cell data (PCA, UMAP)
adata.raw        # Raw data backup

# Access cell and gene names
adata.obs_names  # Cell barcodes
adata.var_names  # Gene names

標準的な解析ワークフロー

各ステップで使用するコードと重要なパラメーターを含む7つのステップについては、 references/analysis_workflow.md を参照してください。

1. 品質管理 — 細胞と遺伝子をフィルタリングします。デフォルト値をそのまま使うのではなく、しきい値を決める前にミトコンドリア比率とカウント数を確認します。
2. 正規化と前処理 — 正規化と対数変換を行い、高変動遺伝子を選択して、後でプロットに使えるよう .raw を保持します。
3. 次元削減 — PCA、近傍グラフ、UMAP の順に実行します。
4. クラスタリング — デフォルトではなく、解析の目的に応じた解像度で Leiden を実行します。
5. マーカー遺伝子の特定 — クラスターごとに遺伝子を順位付けします。
6. 細胞型のアノテーション — マーカーに基づいてクラスターを細胞型に対応付けます。
7. 結果の保存 — アノテーション済みの 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。値が高いほどクラスター数が増えます）

よくある落とし穴とベストプラクティス

1. 生カウントは必ず保存します：遺伝子をフィルタリングする前に adata.raw = adata を設定します。
2. QC プロットを注意深く確認します：データセットの品質に基づいてしきい値を調整します。
3. Leiden クラスタリングを使用します：sc.tl.louvain は scanpy 1.12 で非推奨になりました。
4. 複数のクラスタリング解像度を試します：最適な粒度を見つけます。
5. 細胞型のアノテーションを検証します：複数のマーカー遺伝子を使用します。
6. 遺伝子発現プロットでは use_raw=True を使用します：.raw に保存された正規化済みカウントが表示されます。
7. PCA の分散比を確認します：最適な PC 数を決定します。
8. 中間結果を保存します：長いワークフローは途中で失敗する可能性があります。
9. DE には疑似バルクを使用します：rank_genes_groups の p 値を条件間の厳密な DE として扱わないでください。
10. 設定を使ってプロットを保存します：プロット関数の非推奨な save= の代わりに sc.settings.autosave を使用します。
11. Scanpy を使う前に R オブジェクトを変換します：R パッケージを使って Seurat または SingleCellExperiment の .rds ファイルを .h5ad に変換し、カウント、メタデータ、遺伝子識別子を保持します。

同梱リソース

scripts/（CLI ツールキット）

ワークフロー全体をカバーする、.h5ad を入力し .h5ad を出力する組み合わせ可能なスクリプト一式と、1つのコマンドで実行できるエンドツーエンドのパイプラインです。全スクリプトの表と連結例については、上記の スクリプトツールキット セクションを参照してください。各スクリプトで --help を使用できます。ファイル：

• _common.py — 他のスクリプトからインポートされる共通の読み込み、保存、図作成ヘルパー（CLI ではありません）
• run_pipeline.py — 1つのコマンドでパイプライン全体を実行します（フラグまたは --config JSON）
• 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
# Edit parameters and run
python my_analysis.py

このテンプレートには、設定可能なパラメーターと役立つコメントを含む、標準的な手順がすべて含まれています。

assets/ JSON templates

設定やマッピングを一から作成する必要がない、編集して渡せるテンプレートです。

• 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/index.html
• リリースノート: https://scanpy.scverse.org/en/stable/release-notes/index.html
• scverse エコシステム: https://scverse.org/（関連ツール：squidpy、scvi-tools、cellrank）
• R 相互運用性: https://www.bioconductor.org/packages/release/bioc/html/zellkonverter.html および https://mojaveazure.github.io/seurat-disk/
• ベストプラクティス: Luecken & Theis（2019）「Current best practices in single-cell RNA-seq」

効果的な分析のヒント

1. テンプレートから始める：assets/analysis_template.py を出発点として使用します
2. 最初に QC スクリプトを実行する：初期フィルタリングには scripts/qc_analysis.py を使用します
3. 必要に応じてリファレンスを参照する：ワークフローと API のリファレンスをコンテキストに読み込みます
4. クラスタリングを繰り返し試す：複数の解像度と可視化方法を試します
5. 生物学的に検証する：マーカー遺伝子が想定される細胞タイプと一致するか確認します
6. パラメーターを記録する：QC のしきい値と分析設定を記録します
7. チェックポイントを保存する：重要な手順で中間結果を書き出します

関連スキル

• anndata：単一細胞解析で使用するアノテーション付き行列のデータ構造です。
• scvi-tools：確率的な深層生成モデル（scVI、scANVI、totalVI、MultiVI、PeakVI、DestVI、Solo、CellAssign、MrVI…）を scvi-tools でトレーニングして適用します。
• pydeseq2：DESeq2 の Python 移植版である PyDESeq2 を使用して、バルク RNA-seq カウントデータの差次的発現解析を実行します。