シングルセル RNA-seq クオリティコントロール

scverse ベストプラクティスに従ったシングルセル RNA-seq データの自動 QC ワークフロー。

スキルの使用時期

以下の場合に使用してください：

• シングルセル RNA-seq データのクオリティコントロール (QC) をリクエストする
• 低品質なセルをフィルタリングしたいまたはデータ品質を評価したい
• QC ビジュアライゼーションやメトリクスが必要
• scverse/scanpy ベストプラクティスに従うようリクエストする
• MAD ベースのフィルタリングまたは外れ値検出をリクエストする

サポートされた入力形式：

• .h5ad ファイル（scanpy/Python ワークフローの AnnData 形式）
• .h5 ファイル（10X Genomics Cell Ranger 出力）

**デフォルトの推奨：**ユーザーが特定のカスタム要件を持つまたは明確に非標準フィルタリング ロジックをリクエストしていない限り、Approach 1（完全なパイプライン）を使用してください。

Approach 1: 完全な QC パイプライン（標準ワークフロー向けの推奨）

scverse ベストプラクティスに従った標準 QC の場合、便利なスクリプト scripts/qc_analysis.py を使用します：

python3 scripts/qc_analysis.py input.h5ad
# または 10X Genomics .h5 ファイルの場合：
python3 scripts/qc_analysis.py raw_feature_bc_matrix.h5

このスクリプトは自動的にファイル形式を検出し、適切に読み込みます。

このアプローチを使用する場合：

• 調整可能なしきい値を持つ標準 QC ワークフロー（すべてのセルが同じようにフィルタリングされる）
• 複数のデータセットのバッチ処理
• 迅速な探索的分析
• ユーザーが「動作確認済み」のソリューションを望む場合

要件： anndata、scanpy、scipy、matplotlib、seaborn、numpy

パラメータ：

コマンドラインパラメータを使用してフィルタリングしきい値とジーンパターンをカスタマイズします：

• --output-dir - 出力ディレクトリ
• --mad-counts、--mad-genes、--mad-mt - カウント数/ジーン数/MT% の MAD しきい値
• --mt-threshold - ミトコンドリア % の硬いしきい値
• --min-cells - ジーンフィルタリングしきい値
• --mt-pattern、--ribo-pattern、--hb-pattern - 異なる種用のジーン名パターン

--help を使用して現在のデフォルト値を確認してください。

出力：

すべてのファイルはデフォルトでは <input_basename>_qc_results/ ディレクトリに保存されます（または --output-dir で指定されたディレクトリ）：

• qc_metrics_before_filtering.png - フィルタリング前のビジュアライゼーション
• qc_filtering_thresholds.png - MAD ベースのしきい値オーバーレイ
• qc_metrics_after_filtering.png - フィルタリング後のクオリティメトリクス
• <input_basename>_filtered.h5ad - ダウンストリーム解析用のクリーンでフィルタリングされたデータセット
• <input_basename>_with_qc.h5ad - QC アノテーション付きの元のデータ

ユーザーアクセス用に出力をコピーする場合は、ディレクトリ全体ではなく個別のファイルをコピーして、ユーザーが直接プレビューできるようにしてください。

ワークフローの手順

スクリプトは以下の手順を実行します：

1. QC メトリクスを計算 - カウント深度、ジーン検出、ミトコンドリア/リボソーマル/ヘモグロビン含有量
2. MAD ベースのフィルタリングを適用 - カウント数/ジーン数/MT% の MAD しきい値を使用した寛容な外れ値検出
3. ジーンをフィルタリング - 少数のセルで検出されるジーンを除去
4. ビジュアライゼーションを生成 - しきい値オーバーレイ付きの包括的な前後のプロット

Approach 2: モジュール式ビルディングブロック（カスタムワークフロー用）

カスタム分析ワークフローまたは非標準要件の場合、scripts/qc_core.py と scripts/qc_plotting.py のモジュール式ユーティリティ関数を使用します：

# scripts/ ディレクトリから実行するか、必要に応じて sys.path に scripts/ を追加してください
import anndata as ad
from qc_core import calculate_qc_metrics, detect_outliers_mad, filter_cells
from qc_plotting import plot_qc_distributions  # ビジュアライゼーションが必要な場合のみ

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)
# ... カスタム分析ロジックをここに挿入

このアプローチを使用する場合：

• 異なるワークフローが必要（ステップをスキップ、順序を変更、サブセットに異なるしきい値を適用）
• 条件付きロジック（例：ニューロンを他のセルと異なるようにフィルタリング）
• 部分的な実行（メトリクス/ビジュアライゼーションのみ、フィルタリングなし）
• より大きなパイプラインの他の分析ステップとの統合
• コマンドラインパラメータでサポートされていないカスタムフィルタリング基準

利用可能なユーティリティ関数：

qc_core.py から（コア QC 操作）：

• calculate_qc_metrics(adata, mt_pattern, ribo_pattern, hb_pattern, inplace=True) - QC メトリクスを計算して adata に注釈を付ける
• detect_outliers_mad(adata, metric, n_mads, verbose=True) - MAD ベースの外れ値検出、ブール値マスクを返す
• apply_hard_threshold(adata, metric, threshold, operator='>', verbose=True) - 硬いカットオフを適用、ブール値マスクを返す
• filter_cells(adata, mask, inplace=False) - ブール値マスクを適用してセルをフィルタリング
• filter_genes(adata, min_cells=20, min_counts=None, inplace=True) - 検出によるジーンをフィルタリング
• print_qc_summary(adata, label='') - サマリー統計情報を出力

qc_plotting.py から（ビジュアライゼーション）：

• plot_qc_distributions(adata, output_path, title) - 包括的な QC プロットを生成
• plot_filtering_thresholds(adata, outlier_masks, thresholds, output_path) - フィルタリングしきい値をビジュアライズ
• plot_qc_after_filtering(adata, output_path) - フィルタリング後のプロットを生成

カスタムワークフロー例：

例 1: メトリクスのみを計算してビジュアライズ、まだフィルタリングしない

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)
plot_qc_distributions(adata, 'qc_before.png', title='Initial QC')
print_qc_summary(adata, label='Before filtering')

例 2: MT% フィルタリングのみを適用、その他のメトリクスは寛容に

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)

# 高い MT% セルのみをフィルタリング
high_mt = apply_hard_threshold(adata, 'pct_counts_mt', 10, operator='>')
adata_filtered = filter_cells(adata, ~high_mt)
adata_filtered.write('filtered.h5ad')

例 3: 異なるサブセットに異なるしきい値を適用

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)

# タイプ別 QC を適用（cell_type メタデータが存在することを想定）
neurons = adata.obs['cell_type'] == 'neuron'
other_cells = ~neurons

# ニューロンはより高い MT% を許容、その他のセルはより厳しいしきい値を使用
neuron_qc = apply_hard_threshold(adata[neurons], 'pct_counts_mt', 15, operator='>')
other_qc = apply_hard_threshold(adata[other_cells], 'pct_counts_mt', 8, operator='>')

ベストプラクティス

1. フィルタリングは寛容に - デフォルトしきい値は、稀な集団の損失を避けるため、ほとんどのセルを保持する意図で設計されています
2. ビジュアライゼーションを確認 - フィルタリングが生物学的に意味があることを確認するため、常に前後のプロットをレビューしてください
3. データセット固有の要因を検討 - 一部のティッシュは自然にミトコンドリア含有量が高い（例：ニューロン、心筋細胞）
4. ジーンアノテーションをチェック - ミトコンドリアジーンのプレフィックスは種によって異なります（マウスでは mt-、ヒトでは MT-）
5. 必要に応じて反復 - QC パラメータは特定の実験またはティッシュ タイプに基づいて調整が必要な場合があります

参考資料

詳細な QC 方法論、パラメータの根拠、トラブルシューティング ガイダンスについては、references/scverse_qc_guidelines.md を参照してください。この参考資料は以下を提供します：

• 各 QC メトリクスの詳細な説明とそれが重要な理由
• MAD ベースのしきい値の根拠と、それらが固定カットオフより優れている理由
• QC ビジュアライゼーションの解釈に関するガイドライン（ヒストグラム、バイオリンプロット、散布図）
• ジーンアノテーションの種固有の考慮事項
• フィルタリングパラメータを調整する時期と方法
• 高度な QC に関する考慮事項（周囲 RNA 補正、ダブレット検出）

ユーザーが方法論をより深く理解する必要があるときまたは QC の問題をトラブルシューティングするときに、この参考資料を読み込んでください。

QC 後の次のステップ

典型的なダウンストリーム分析ステップ：

• 周囲 RNA 補正（SoupX、CellBender）
• ダブレット検出（scDblFinder）
• 正規化（ログ正規化、scran）
• 機能選択と次元削減
• クラスタリングおよびセルタイプアノテーション