Claudeのsingle-cell-rna-qcスキルでscRNA-seqのQCを回す手順

single-cell-rna-qcは、Anthropicが配布するbio-researchプラグインに入っているskillです。シングルセルRNA-seq(scRNA-seq)のデータを渡すと、細胞ごとのQC指標を計算し、外れ値の細胞を除いた.h5adと3枚の図を書き出します。ここでは入れ方、実行されるスクリプトの中身、既定値、研究データに当てるときの調整点を順に見ていきます。

single-cell-rna-qcは何をするskillか

SKILL.mdの定義では、対象は.h5ad(scanpyなどのAnnData形式)と.h5(10X Genomics Cell Rangerの出力)です。QCの方針は、scverseのベストプラクティスに沿ったMADベースの外れ値除去です。

MADは中央値絶対偏差(median absolute deviation)のことです。「中央値から何MAD離れた細胞を外れ値とするか」で足切りの位置を決めるので、固定の閾値より、データセットごとの分布に合わせやすくなります。ガイドは、固定値の足切りがプロトコル・組織・種ごとの違いに対応できない点を、MADを使う理由に挙げています。

skillには2つの使い方があります。

SKILL.mdは、特別な要件がなければApproach 1を使うよう書いています。

bio-researchプラグインの入れ方

bio-researchはknowledge-work-pluginsマーケットプレイスに登録されています。READMEには/install anthropics/knowledge-work-plugins bio-researchとありますが、Claude Codeの標準コマンドでは次の2行になります。

/plugin marketplace add anthropics/knowledge-work-plugins
/plugin install bio-research@knowledge-work-plugins

セッション内の/plugin installは、その場では入れずに詳細パネルを開きます。パネルでスコープを選んでから導入します。反映されないときは/reload-pluginsで読み込み直せます。同じマーケットプレイスから入れる別プラグインの例は、small-businessプラグインの記事にあります。マーケットプレイス自体の仕組みはプラグインとマーケットプレイスの解説が扱っています。

入れる前に、プラグインの中身を知っておくと安心です。READMEは「11のMCPサーバー連携と5つの分析skillを1つにまとめた」と説明しています。.mcp.jsonにはPubMed・bioRxiv・ChEMBL・OpenTargets・Consensus・Wiley・BioRender・Synapse・Owkin・ClinicalTrials・Benchlingの11エントリが並びます。Benchlingのurlは空欄です。QCだけが目的でも、これらの接続定義が一緒に入る点は、詳細パネルで確認できます。

分析skillの5つは、single-cell-rna-qc、scvi-tools、Nextflowパイプライン、Instrument Data to Allotrope、Scientific Problem Selectionです。READMEの「Single-Cell Analysis」の流れは、QCの後にscvi-toolsで統合・バッチ補正・細胞型アノテーションへ進む順になっています。

実行の流れ: 5ステップのスクリプトが何をするか

Claudeにデータのパスを渡して「QCして」と頼むと、skillの説明文に当たる依頼としてsingle-cell-rna-qcが選ばれます。説明文には、QC解析、低品質細胞の除去、データ品質の評価、scverse/scanpyのベストプラクティスに従う依頼、と書かれています。名前を明示するなら/bio-research:single-cell-rna-qcの形でも呼べます。

sample1_filtered_feature_bc_matrix.h5 をQCして。ヒトのデータで、
結果は qc_out/ に出して

SKILL.mdが示す実行コマンドは次の形です。--output-dirは書き出し先を決めるオプションです。

python3 scripts/qc_analysis.py sample1_filtered_feature_bc_matrix.h5 \
  --output-dir qc_out

動かすにはanndata・scanpy・scipy・matplotlib・seaborn・numpyが要ります。SKILL.mdはこの6つを「Requirements」に挙げています。導入していない環境では、先にこれらを入れる必要があります。

出力は<入力名>_qc_results/(または--output-dir)にまとまります。

_with_qc.h5adは元の細胞を残したままpass_qcの列を持つため、どの細胞がなぜ落ちたかを後から追えます。落とす前の状態に戻したいときもこちらを使います。

既定のしきい値を決めているもの

スクリプト冒頭の定数が既定値です。コマンドラインで上書きできます。

ガイドは、この既定を「意図的に緩い」と説明します。希少な細胞集団を落とさないためで、後から厳しくするほうが、失った細胞を戻すより簡単だからです。SKILL.mdの「Best Practices」にも「Be permissive with filtering」とあります。

一方、MT%は他より厳しく扱われています。高いMT%は死にかけた細胞や破れた細胞を示すためで、MADを3に絞り、さらに固定の8%を重ねています。ここはpass_qcの判定で効く場所なので、次の節で調整を見ます。

データに合わせて調整する4つの場面

ガイドの「When to Adjust Parameters」を、コマンドに落とすと次のようになります。

# 神経細胞や心筋: MT%が自然に高いので固定上限を緩める
python3 scripts/qc_analysis.py brain.h5ad --mt-threshold 15
 
# 希少な細胞集団を調べる: 遺伝子フィルタを緩める
python3 scripts/qc_analysis.py sample.h5ad --min-cells 10
 
# 背景RNAが多い疑い: MADを狭くして厳しくする
python3 scripts/qc_analysis.py sample.h5ad --mad-counts 4 --mad-genes 4 --mad-mt 2.5
 
# マウスのデータ: 接頭辞は既定で両対応だが、明示もできる
python3 scripts/qc_analysis.py mouse.h5ad --mt-pattern "mt-" --ribo-pattern "Rpl,Rps"

組織ごとの目安として、ガイドは脳・神経は10〜15%、血液は5〜8%のMT%を挙げています。腫瘍サンプルは生物学的なばらつきが大きく、緩めの閾値が要る場合が多いという記述です。

種の違いはMT遺伝子の接頭辞に出ます。マウスはmt-、ヒトはMT-で、既定のmt-,MT-は両方を拾います。それ以外の生物種では、接頭辞を自分で指定します。ガイドも、EnsemblなどのアノテーションでMT遺伝子の接頭辞を確かめるよう案内しています。

細胞種ごとに閾値を変えたいときはApproach 2を使います。SKILL.mdの例3は、神経細胞のMT%上限を15、それ以外を8にする書き方です。ただし例の末尾は、2つのapply_hard_thresholdでマスクを作るところまでです。2つのマスクを元のデータの細胞順に合わせて結合し、filter_cellsに渡す処理は、自分で足す必要があります。

ガイドとコードの食い違い: 対数変換の有無

ここで、references/scverse_qc_guidelines.mdとscripts/qc_core.pyを見比べると、1点だけ書き方が違います。

ガイドは、総カウント数と遺伝子数について「5 MADs(対数変換した値で)」と書いています。理由は、右に裾の長い分布を正規に近づけるためです。MT%は対数変換しない生のパーセントを使うと書かれています。

一方、detect_outliers_madの実装は、obsの列の値をそのままnp.medianとmedian_abs_deviationに渡します。log1pなどの変換処理は関数の中にありません。calculate_qc_metricsにあるlog1p=Falseは、scanpyが対数をとった列(log1p_total_countsなど)を別に作らないという指定です。MADもscaleを指定せず呼ばれるので、正規分布の標準偏差に換算する係数(1.4826)は掛かりません。

この差が効くのは、総カウント数のような右に歪んだ分布です。生の値で「中央値 ± 5 × MAD」を計算すると、分布の形によっては下限が0を下回り、少ない側の外れ値(空の液滴に近い細胞)がpass_qcの判定で拾われにくくなる可能性があります。実際にどう効くかは、データの分布しだいです。

確かめる手順は単純です。qc_filtering_thresholds.pngの下限の線が、ヒストグラムのどこに引かれているかを見ます。線が分布の左端より外にあるなら、その指標の低い側は実質的に素通りです。気になるときは、Approach 2で対数変換した列を作り、その列をdetect_outliers_madに渡す形に組み替えられます。

このskillに含まれない処理と、入力の前提

ガイドは、このワークフローに入れていないものとして、背景RNAの補正(SoupX、CellBender、DecontX)、ダブレット検出(scDblFinder、scrublet、DoubletFinder)、細胞周期スコア、バッチ補正を挙げています。ダブレット検出は、液滴方式のデータでは常に推奨と書かれています。SKILL.mdの「Next Steps After QC」の順は、背景RNA補正、ダブレット検出、正規化、特徴量選択と次元削減、クラスタリングと細胞型アノテーションです。

つまり、このskillが出す_filtered.h5adは、下流解析の入口として使える状態ですが、QCの全工程が済んだ状態ではありません。

入力にも前提があります。

• 総カウント数や検出遺伝子数はXの値から計算されるので、.h5adを渡すならXに生カウントが入っている必要があります。SKILL.mdには、この条件を明記した記述がありません
• SKILL.mdの.h5の例はraw_feature_bc_matrix.h5です。Cell Rangerにはフィルタ済みの行列もあります。中央値とMADはファイル内の全バーコードで計算されるため、どちらを渡すかで基準が変わります
• リボソームとヘモグロビンは指標として計算されますが、pass_qcの判定には使われません

使い分け: QCをClaudeに任せる場面と手元で回す場面

CSVやParquetを、DBを用意せずにその場で集計する別の手段は、DuckDBプラグインの記事が扱っています。研究者向けの環境全体の話は、Claude Scienceの文献レビュー実例にあります。

QCは、後続の統合やクラスタリングの前提になります。閾値を機械的に確定せず、図を見て「この組織で、この値が妥当か」を判断する工程を残しておく運用は、SKILL.mdの「Best Practices」が勧める進め方でもあります。