scvi-tools
Probabilistic single-cell RNA-seq with scvi-tools — scVI for a batch-corrected latent space, scANVI for semi-supervised label transfer, and Bayesian differential expression. Reach for this skill to integrate scRNA-seq batches, embed cells for clustering, transfer annotations from a reference onto a query, or score differentially expressed genes per cluster. For spatial deconvolution / mapping use the cell2location, DestVI, or Tangram methods instead.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- scvi-tools
- license
- Apache-2.0
- metadata
- { "display-name": "scvi-tools" }
- description
- Probabilistic single-cell RNA-seq with scvi-tools — scVI for a batch-corrected latent space, scANVI for semi-supervised label transfer, and Bayesian differential expression. Reach for this skill to integrate scRNA-seq batches, embed cells for clustering, transfer annotations from a reference onto a query, or score differentially expressed genes per cluster. For spatial deconvolution / mapping use the cell2location, DestVI, or Tangram methods instead.
- requirements
- [ "gpu" ]
02 资源文件 1
- 脚本kernel.py2.2 KB
03 SKILL.md 正文
scvi-tools — scVI / scANVI
scvi-tools (Gayoso et al. 2022, github.com/scverse/scvi-tools, BSD-3-Clause)
wraps a family
of deep generative models for single-cell omics. The scRNA-seq core is scVI
(unsupervised batch-corrected latent embedding) and scANVI (scVI + a
classifier head for semi-supervised cell-type label transfer). Both expect
raw integer UMI counts and emit a low-dimensional X_scVI / X_scANVI
that drops into the scanpy neighbors → leiden → umap pipeline.
How to run
scVI — batch-corrected latent space
import scanpy as sc
import scvi
adata = sc.read_h5ad("dataset.h5ad")
adata.layers["counts"] = adata.X.copy() # preserve raw BEFORE any normalize/log1p
sc.pp.normalize_total(adata); sc.pp.log1p(adata) # optional, for HVG / plotting only
sc.pp.highly_variable_genes(adata, n_top_genes=2000, batch_key="batch", subset=True)
scvi.model.SCVI.setup_anndata(adata, layer="counts", batch_key="batch")
model = scvi.model.SCVI(adata, n_latent=30)
model.train(max_epochs=200, early_stopping=True, accelerator="gpu", devices=1)
adata.obsm["X_scVI"] = model.get_latent_representation()
adata.layers["scvi_normalized"] = model.get_normalized_expression(library_size=1e4)
scANVI — label transfer from a partially-annotated reference
lvae = scvi.model.SCANVI.from_scvi_model(
model, labels_key="cell_type", unlabeled_category="Unknown",
)
lvae.train(max_epochs=20, n_samples_per_label=100, accelerator="gpu", devices=1)
adata.obsm["X_scANVI"] = lvae.get_latent_representation()
adata.obs["pred_cell_type"] = lvae.predict()
accelerator="gpu", devices=1 is the PyTorch-Lightning spelling; the legacy
use_gpu= kwarg was removed in scvi-tools 1.x and now raises TypeError.
Differential expression
de = model.differential_expression(
groupby="leiden", group1="3", # group2=None → vs. all other cells
mode="change", delta=0.25,
)
top = de.sort_values("proba_de", ascending=False).head(50)
For one-vs-rest leave group2 out — "rest" is scanpy's
rank_genes_groups convention, not scvi-tools'; here group2 is a literal
category name and "rest" would match zero cells.
scvi-tools ≥1.4 defaults to mode="vanilla", whose result columns are
exactly:
['proba_m1', 'proba_m2', 'bayes_factor', 'scale1', 'scale2', 'raw_mean1',
'raw_mean2', 'non_zeros_proportion1', 'non_zeros_proportion2',
'raw_normalized_mean1', 'raw_normalized_mean2', 'comparison', 'group1',
'group2']
— no lfc_*, no proba_de, no is_de_fdr_*. Pass mode="change" to
get lfc_mean / lfc_median / proba_de / is_de_fdr_0.05. Sort on
proba_de (or on bayes_factor if you deliberately stayed in vanilla
mode).
Output format
| Key | What |
|---|---|
adata.obsm["X_scVI"] |
n_cells × n_latent batch-corrected embedding |
adata.obsm["X_scANVI"] |
label-aware embedding (better separates known classes) |
adata.obs["pred_cell_type"] |
scANVI predicted label per cell |
adata.layers["scvi_normalized"] |
decoded expression, library-size normalized |
| DE dataframe | per-gene lfc_* / proba_de (with mode="change") |
Remote compute
A100-class GPU recommended for >50k cells. The prebuilt singlecell_gpu
Modal env ships scvi-tools 1.4.2 + scanpy 1.11.5 + anndata 0.11.4 — read
compute_details({provider: 'byoc:modal', mode: 'read'}) for the current
image ref, then:
c = host.compute.create('byoc:modal', provider_params={'modal': {
'image': '<image ref from compute_details>', # e.g. im-...
'gpu': 'A100',
'cpu': 8,
'memory': 32768,
'timeout': 3600,
}})
job = c.submit_job(
intent="scVI+scANVI on 80k cells — 1×A100, ~15 min",
inputs=[
{"src": "dataset.h5ad", "dst_filename": "dataset.h5ad"},
{"src": "pipeline.py", "dst_filename": "pipeline.py"},
],
command="python pipeline.py",
outputs=["out/**"],
timeout_seconds=2400,
)
print(job.job_id) # cell ends here — kernel never blocks on compute
h5ad_safe_obs is auto-loaded into the local analysis kernel only — in
pipeline.py running on Modal, paste the helper at the top of the script
(or inline the pd.Index(np.asarray(..., dtype=object)) coercion) before
.write_h5ad().
Then call the wait_for_notification brain-tool. When compute_done
arrives, save_artifacts(payload["featured_files"]). For the full result
dict, re-enter the kernel and bind the compute handle (not the job)
separately — .close() lives on the handle, not on the job:
h = host.compute.create('byoc:modal')
res = h.attach_job(job_id).result() # output_files, remote_workdir, ...
h.close()
See the remote-compute-modal skill for orchestration details.
Gotchas
| Gotcha | What happens / fix |
|---|---|
differential_expression() defaults to mode="vanilla" (scvi-tools ≥1.4) |
KeyError: 'lfc_mean' / 'proba_de' when sorting — pass mode="change" to get lfc_*/proba_de/is_de_fdr_*; in vanilla mode sort on bayes_factor. |
adata.obs index/columns are string[pyarrow] (ArrowStringArray) |
.write_h5ad() dies with IORegistryError: No method registered for writing <class 'pandas.arrays.ArrowStringArray'> (anndata #2377). Coerce before writing: adata.obs = h5ad_safe_obs(adata.obs) (kernel helper — local kernel only; inline the coercion in remote pipeline.py). .astype(str) alone is not enough — on a pyarrow-backed Index/Series it returns another Arrow-backed array; round-trip through np.asarray(..., dtype=object). anndata.settings.allow_write_nullable_strings = True does not cover Arrow-backed strings. |
use_gpu= kwarg |
Removed in 1.x → TypeError: train() got an unexpected keyword argument 'use_gpu'. Use accelerator="gpu", devices=1. |
Log-normalized data fed to setup_anndata |
Silent garbage — scVI's NB likelihood needs raw integer counts. Stash counts in adata.layers["counts"] before normalize/log1p and pass layer="counts". |
Troubleshooting
| Symptom | Fix |
|---|---|
KeyError: 'lfc_mean' (or 'proba_de', 'is_de_fdr_0.05') on DE result |
Add mode="change" to differential_expression(); the default vanilla mode has no LFC columns. |
IORegistryError: No method registered for writing <class 'pandas.arrays.ArrowStringArray'> on .write_h5ad() |
adata.obs = h5ad_safe_obs(adata.obs) (and adata.var if needed) before writing. The allow_write_nullable_strings flag does not help here. |
TypeError: ... unexpected keyword argument 'use_gpu' |
Replace with accelerator="gpu", devices=1. |
ValueError: ... non-negative integers / NB loss explodes |
layer="counts" points at log/float data — restore raw counts. |
MisconfigurationException: No supported gpu backend found |
No CUDA visible — drop accelerator/devices to fall back to CPU, or dispatch via Remote compute. |
UnicodeEncodeError: 'ascii' codec can't encode character ... writing a summary / printing |
Container has no LANG so Python defaults to ASCII. Open files with encoding="utf-8" and/or sys.stdout.reconfigure(encoding="utf-8") at script top. The prebuilt singlecell_gpu env sets PYTHONIOENCODING=utf-8, so this only bites user-built images. |
AttributeError: ... object has no attribute 'close' on a job handle |
You chained host.compute.create(...).attach_job(...) and called .close() on the job. Bind the compute handle separately and close that — see Remote compute above. |
Next: cluster on X_scVI with scanpy (sc.pp.neighbors(use_rep="X_scVI")
→ sc.tl.leiden → sc.tl.umap); for spatial deconvolution train
cell2location / DestVI / Tangram on the scRNA-seq reference.
04 同仓库更多 Skills
workflow-skill-creator
Distills a completed user workflow or interaction into a reusable agent skill. Use when the user asks to turn their workflow, interaction, or multi-step process into a skill, or when they say "make this a skill", "create a skill from what we just did", "package this workflow" or similar. Do not use for creating skills from scratch without an existing workflow (use a generic skill-creator for that).
uv
Checks whether the uv Python package manager is installed and installs it if missing. Ensures uv is on PATH. Use when another skill requires uv as a prerequisite.
uniprot-database
Access protein metadata, function, taxonomy, and sequences across UniProtKB, UniParc, and UniRef. Use when searching for proteins, mapping identifiers, or retrieving functional annotations and publications. Don't use for sequence alignment, protein folding, or sequence similarity search (use specialized skills for those tasks).
unibind-database
Queries the UniBind database for experimentally validated transcription factor (TF) binding sites. Use when retrieving direct TF-DNA interaction datasets, downloading binding site coordinates (BED/FASTA) for local analysis, or listing available datasets by species, cell line, or TF name. Don't use to query specific intervals, locations, genes, motif models or expression data.
ucsc-conservation-and-tfbs
Fetch Evolutionary Conservation scores (phyloP, phastCons) and Transcription Factor Binding Sites (TFBS) from the UCSC Genome Browser. Use when analyzing whether genomic variants or regions are evolutionarily conserved, functionally important, or bounded by TF regulators across major projects (ENCODE, JASPAR, ReMap).
string-database
Query the STRING database for protein-protein interactions (PPIs), functional enrichment, and homology. Use when the user asks about interactions between specific proteins, interaction evidence, confidence scores, protein interaction partners, or pathway enrichments.