scvi-tools

scvi-tools 技能概覽

scvi-tools 是用來做什麼的

scvi-tools 技能能幫你在單細胞 omics 的情境下使用 scVI 風格的機率模型；當一般分析提示詞太籠統時，它特別有用。它最適合處理批次校正、潛在表示學習、跨 runs 或 donor 的整合，以及能考慮不確定性的差異表現分析。如果你的目標是進階單細胞建模，而不是例行前處理，這個 scvi-tools 技能會很合適。

誰應該安裝它

如果你處理的是單細胞 RNA-seq、multiome、CITE-seq、ATAC 或 spatial 資料，而且希望走模型驅動的流程，就應該安裝 scvi-tools。它特別適合需要 PyTorch 基礎框架的 Machine Learning 使用者，而不只是想看一份靜態方法摘要的人。如果你主要需要基本 QC、分群或視覺化，標準的 Scanpy-first 流程通常就夠了。

採用前要先看重什麼

它的核心價值不只是 scvi-tools 存在，而是它能提供一條從原始 counts 到訓練好的潛在模型的實作路徑，且把權衡講得很清楚。關鍵問題是：你是否真的需要機率建模、遷移學習，或多模態整合，才足以合理化額外的設定成本與建模選擇。當輸出品質取決於是否妥善處理批次效應，或是否仔細比較異質資料集時，這個技能就很值得安裝。

如何使用 scvi-tools 技能

安裝 scvi-tools 技能

請使用目錄的安裝流程來安裝 scvi-tools 技能：
npx skills add K-Dense-AI/claude-scientific-skills --skill scvi-tools

安裝後，請確認 scientific-skills/scvi-tools 下的技能路徑，並直接打開原始檔。對這個 repository 來說，SKILL.md 是主要入口；沒有可依賴的 rules/、resources/ 或 scripts/ 資料夾。

先讀對的檔案

先從 SKILL.md 開始，了解範圍、模型家族，以及建議的判斷點。接著在真正下提示詞前，先掃過「何時使用這個技能」、「核心能力」與「single-cell RNA-seq workflow」等段落。由於這個 repository 很精簡，最快降低猜測成本的方法，是先把整份檔案從頭到尾讀一遍，而不是只挑模型名稱看。

把模糊目標轉成可用提示詞

像「分析我的 scRNA-seq 資料」這種弱請求還不夠。更好的 scvi-tools 使用提示詞，會清楚指出 assay、資料形狀，以及你需要做的決策：

• 「用 scVI 整合 6 個 scRNA-seq batches，比較 donor effect，並回傳 latent space 與 batch-mixing 診斷結果。」
• 「為配對的 RNA + ATAC 資料建立 MULTIVI 風格流程，並說明細胞是更接近生物差異還是批次差異。」
• 「對兩個細胞族群執行帶有不確定性的 differential expression，並回報 effect size，而不只是 p-value。」

會影響輸出品質的 workflow 提示

提供這個技能選對模型家族所需要的資訊：資料模態、batch 數量、是否為配對資料，以及任務是整合、註解還是 DE。也要事先說明任何限制，例如 counts 很稀疏、樣本數很小，或需要保持與既有 scanpy 物件相容。若你想拿到最好的 scvi-tools 指南結果，請一次就要求模型選擇、設定步驟、預期輸出，以及常見失敗模式。

scvi-tools 技能 FAQ

scvi-tools 只適合 scRNA-seq 嗎？

不是。scvi-tools 技能涵蓋多種單細胞模態，包括 RNA-seq、ATAC、多模態 assay 與 spatial 使用情境。不過，RNA 整合是最常見的切入點，所以通常也是先驗證是否適合的最好起點，再往更複雜的資料擴展。

如果我已經在用 Scanpy，還需要它嗎？

兩者都用，但用途不同。Scanpy 更適合標準前處理與探索式工作流，而 scvi-tools 更適合在有 batch effect 時需要機率建模、latent embeddings 或整合結果的情境。如果你的分析問題不需要學習式生成模型，scvi-tools 可能就超過你的實際需求。

這個技能對新手友善嗎？

只有在你已經理解 counts matrix、batch、annotation 這類基本單細胞概念時，它才算對新手相對友善。這個技能最有幫助的時候，是你能清楚描述自己的資料與目標。如果你還說不清楚自己需要整合、遷移學習還是 differential expression，先從更簡單的分析路徑開始會比較好。

什麼情況下不該用 scvi-tools？

不要把 scvi-tools 拿來做簡單 normalization、快速繪圖，或一次性的探索檢查。如果你想要的是一套純統計的 cookbook，而且不想碰模型選擇決策，它也不是理想選擇。對於極小資料集或高度客製化的 pipeline，額外開銷可能會大於收益。

如何改進 scvi-tools 技能

提供模型選擇的上下文

最大的品質提升，來自於你先說清楚自己面對的是哪一類 scvi-tools 問題。請先描述資料，再說你需要的是 scVI、TOTALVI、MultiVI，還是其他家族。比起直接說「用 MultiVI」，「配對的 CITE-seq，而且 donor effect 很強」通常更有幫助。

交代資料結構與限制

更好的輸入可以減少最常見的失敗模式：替錯誤的 assay 選到錯誤的模型。請包含 matrix 類型、細胞數、batch、covariates，以及 counts 是 raw 還是 normalized。如果你是在 Machine Learning 的 scvi-tools 工作流中使用它，也請說明你要的是可重複使用的 latent space、下游分類器特徵，還是與另一個模型的可解釋比較。

要求你能實際採用的輸出

不要只問「分析」。請要求具體可交付成果，例如訓練計畫、模型選擇理由、整合診斷，或 notebook 風格的流程。如果第一版結果太籠統，就補上缺少的資訊再迭代：cell type 標籤、batch 定義，或你需要拿來與 scanpy 或其他 baseline 比較的對象。