alterlab-scanpy

Scanpy：シングルセル解析

概要

Scanpy は AnnData を基盤とする、シングルセル RNA-seq データ解析用のスケーラブルな Python ツールキットです。品質管理、正規化、次元削減、クラスタリング、マーカー遺伝子の特定、可視化、軌跡解析を含む、シングルセル解析の一連のワークフローにこのスキルを使用してください。

このスキルを使用する場面

次の場合にこのスキルを使用してください：

• シングルセル RNA-seq データ（.h5ad、10X、CSV 形式）を解析する場合
• scRNA-seq データセットの品質管理を行う場合
• UMAP、t-SNE、または PCA の可視化を作成する場合
• 細胞クラスターを特定し、マーカー遺伝子を探す場合
• 遺伝子発現に基づいて細胞型をアノテーションする場合
• 軌跡推定または疑似時間解析を行う場合
• 論文掲載品質のシングルセルプロットを作成する場合

対象外

状況	代わりに使用
.h5ad オブジェクト自体の構築、読み込み、または再構成（layers、obs/var、連結、backed/Dask モード）	alterlab-anndata
スプライス済み／未スプライスカウントからの RNA ベロシティ解析	alterlab-scvelo
確率的潜在モデル — scVI/scANVI による統合、モデルベースの DE	alterlab-scvi-tools
空間トランスクリプトーム解析 — Visium/Xenium/MERFISH の近傍解析および画像解析	alterlab-squidpy-spatial
カウント行列からのバルク RNA-seq 差次的発現解析	alterlab-pydeseq2

クイックスタート

基本的なインポートとセットアップ

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/'

データの読み込み

# 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')

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

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

1. 品質管理

品質の低い細胞や遺伝子を特定してフィルタリングします：

# Identify mitochondrial genes
adata.var['mt'] = adata.var_names.str.startswith('MT-')

# Calculate QC metrics
sc.pp.calculate_qc_metrics(adata, qc_vars=['mt'], inplace=True)

# Visualize QC metrics
sc.pl.violin(adata, ['n_genes_by_counts', 'total_counts', 'pct_counts_mt'],
             jitter=0.4, multi_panel=True)

# Filter cells and genes
sc.pp.filter_cells(adata, min_genes=200)
sc.pp.filter_genes(adata, min_cells=3)
adata = adata[adata.obs.pct_counts_mt < 5, :]  # Remove high MT% cells

自動解析には QC スクリプトを使用してください：

python scripts/qc_analysis.py input_file.h5ad --output filtered.h5ad

2. 正規化と前処理

# Normalize to 10,000 counts per cell
sc.pp.normalize_total(adata, target_sum=1e4)

# Log-transform
sc.pp.log1p(adata)

# Save raw counts for later
adata.raw = adata

# Identify highly variable genes
sc.pp.highly_variable_genes(adata, n_top_genes=2000)
sc.pl.highly_variable_genes(adata)

# Subset to highly variable genes
adata = adata[:, adata.var.highly_variable]

# Regress out unwanted variation
sc.pp.regress_out(adata, ['total_counts', 'pct_counts_mt'])

# Scale data
sc.pp.scale(adata, max_value=10)

3. 次元削減

# PCA
sc.tl.pca(adata, svd_solver='arpack')
sc.pl.pca_variance_ratio(adata, log=True)  # Check elbow plot

# Compute neighborhood graph
sc.pp.neighbors(adata, n_neighbors=10, n_pcs=40)

# UMAP for visualization
sc.tl.umap(adata)
sc.pl.umap(adata, color='leiden')

# Alternative: t-SNE
sc.tl.tsne(adata)

4. クラスタリング

# Leiden clustering (recommended). Pass flavor='igraph' (the future default) +
# n_iterations=2 — the bare call emits a FutureWarning and uses the slow backend.
sc.tl.leiden(adata, resolution=0.5, flavor='igraph', n_iterations=2)
sc.pl.umap(adata, color='leiden', legend_loc='on data')

# Try multiple resolutions to find optimal granularity
for res in [0.3, 0.5, 0.8, 1.0]:
    sc.tl.leiden(adata, resolution=res, flavor='igraph', n_iterations=2,
                 key_added=f'leiden_{res}')

5. マーカー遺伝子の特定

# Find marker genes for each cluster
sc.tl.rank_genes_groups(adata, 'leiden', method='wilcoxon')
# Scanpy >=1.12 warns here on purpose: the clusters were derived from the same
# counts being tested, so the p-values are anti-conservative ("double dipping").
# Treat the ranking as a marker-discovery heuristic, and get real p-values from an
# independent grouping (condition, donor, genotype) or a pseudobulk test
# (`alterlab-pydeseq2`) before reporting significance.

# Visualize results
sc.pl.rank_genes_groups(adata, n_genes=25, sharey=False)
sc.pl.rank_genes_groups_heatmap(adata, n_genes=10)
sc.pl.rank_genes_groups_dotplot(adata, n_genes=5)

# Get results as DataFrame
markers = sc.get.rank_genes_groups_df(adata, group='0')

6. 細胞型のアノテーション

# Define marker genes for known cell types
marker_genes = ['CD3D', 'CD14', 'MS4A1', 'NKG7', 'FCGR3A']

# Visualize markers
sc.pl.umap(adata, color=marker_genes, use_raw=True)
sc.pl.dotplot(adata, var_names=marker_genes, groupby='leiden')

# Manual annotation
cluster_to_celltype = {
    '0': 'CD4 T cells',
    '1': 'CD14+ Monocytes',
    '2': 'B cells',
    '3': 'CD8 T cells',
}
adata.obs['cell_type'] = adata.obs['leiden'].map(cluster_to_celltype)

# Visualize annotated types
sc.pl.umap(adata, color='cell_type', legend_loc='on data')

7. 結果の保存

# Save processed data
adata.write('results/processed_data.h5ad')

# Export metadata
adata.obs.to_csv('results/cell_metadata.csv')
adata.var.to_csv('results/gene_metadata.csv')

よくあるタスク

論文掲載品質のプロットを作成する

import matplotlib.pyplot as plt

# Set high-quality defaults
sc.settings.set_figure_params(dpi=300, frameon=False, figsize=(5, 5))

# The `save=` parameter of every sc.pl.* function is deprecated as of Scanpy 1.12.
# Pass show=False and save the current figure yourself — this also gives you control
# over bbox/dpi and lets you compose panels.
sc.pl.umap(adata, color='cell_type',
           palette='Set2',
           legend_loc='on data',
           legend_fontsize=12,
           legend_fontoutline=2,
           frameon=False,
           show=False)
plt.savefig('figures/umap_publication.pdf', bbox_inches='tight')
plt.close()

# Heatmap of marker genes
sc.pl.heatmap(adata, var_names=genes, groupby='cell_type',
              swap_axes=True, show_gene_labels=True, show=False)
plt.savefig('figures/markers_heatmap.pdf', bbox_inches='tight')
plt.close()

包括的な可視化例については、references/plotting_guide.md を参照してください。

軌跡推定

# PAGA (Partition-based graph abstraction)
sc.tl.paga(adata, groups='leiden')
sc.pl.paga(adata, color='leiden')

# Diffusion pseudotime
adata.uns['iroot'] = np.flatnonzero(adata.obs['leiden'] == '0')[0]
sc.tl.dpt(adata)
sc.pl.umap(adata, color='dpt_pseudotime')

条件間の差次的発現解析

# Compare treated vs control within cell types
adata_subset = adata[adata.obs['cell_type'] == 'T cells']
sc.tl.rank_genes_groups(adata_subset, groupby='condition',
                         groups=['treated'], reference='control')
sc.pl.rank_genes_groups(adata_subset, groups=['treated'])

遺伝子セットスコアリング

# Score cells for gene set expression
gene_set = ['CD3D', 'CD3E', 'CD3G']
sc.tl.score_genes(adata, gene_set, score_name='T_cell_score')
sc.pl.umap(adata, color='T_cell_score')

バッチ補正

# ComBat batch correction
sc.pp.combat(adata, key='batch')

# Alternative: use Harmony or scVI (separate packages)

調整する主なパラメーター

品質管理

• 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. flavor='igraph' を指定して Leiden を使用してください：従来の leidenalg バックエンドより大幅に高速です。また、sc.tl.louvain() は Scanpy 1.12 以降で非推奨です — uv pip install igraph（scanpy には同梱されていません）
4. 複数のクラスタリング解像度を試してください：最適な粒度を見つけます
5. 細胞型のアノテーションを検証してください：複数のマーカー遺伝子を使用します
6. 遺伝子発現プロットには use_raw=True を使用してください：元のカウントが表示されます
7. PCA の分散比を確認してください：最適な PC 数を決定します
8. 中間結果を保存してください：長いワークフローは途中で失敗することがあります

同梱リソース

scripts/qc_analysis.py

メトリクスの計算、プロットの生成、データのフィルタリングを行う自動品質管理スクリプト：

python scripts/qc_analysis.py input.h5ad --output filtered.h5ad \
    --mt-threshold 5 --min-genes 200 --min-cells 3

references/standard_workflow.md

詳しい説明とコード例を含む、完全なステップごとのワークフロー：

• データの読み込みとセットアップ
• 可視化による品質管理
• 正規化とスケーリング
• 特徴量選択
• 次元削減（PCA、UMAP、t-SNE）
• クラスタリング（Leiden、Louvain）
• マーカー遺伝子の特定
• 細胞型のアノテーション
• 軌跡推定
• 差次的発現

一から完全な解析を行う際に、このリファレンスを参照してください。

references/api_reference.md

モジュール別に整理された、scanpy 関数のクイックリファレンスガイド：

• データの読み込み／書き込み（sc.read_*、adata.write_*）
• 前処理（sc.pp.*）
• ツール（sc.tl.*）
• プロット（sc.pl.*）
• AnnData の構造と操作
• 設定とユーティリティ

関数のシグネチャや一般的なパラメーターをすばやく確認する際に使用してください。

references/plotting_guide.md

以下を含む、包括的な可視化ガイド：

• 品質管理プロット
• 次元削減の可視化
• クラスタリングの可視化
• マーカー遺伝子のプロット（ヒートマップ、ドットプロット、バイオリンプロット）
• 軌跡と擬似時間のプロット
• 出版物向けのカスタマイズ
• 複数パネルの図
• カラーパレットとスタイル設定

出版物向けの図を作成する際に参照してください。

assets/analysis_template.py

データの読み込みから細胞型のアノテーションまでの完全なワークフローを提供する、解析テンプレートです。新しい解析を始める際は、このテンプレートをコピーしてカスタマイズしてください：

cp assets/analysis_template.py my_analysis.py
# Edit parameters and run
python my_analysis.py

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

追加リソース

• scanpy 公式ドキュメント：https://scanpy.readthedocs.io/
• Scanpy チュートリアル：https://scanpy-tutorials.readthedocs.io/
• scverse エコシステム：https://scverse.org/（関連ツール：squidpy、scvi-tools、cellrank）
• ベストプラクティス：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. チェックポイントを保存する：主要なステップで中間結果を書き込みます