scgpt
Embed and annotate single-cell expression data with scGPT, a foundation model for single-cell biology. Use this skill when: (1) Producing cell embeddings from an AnnData for clustering/integration, (2) Zero-shot or fine-tuned cell-type annotation, (3) Gene-level representation for perturbation/GRN tasks. For probabilistic single-cell models (scVI etc.), use the scvi-tools library.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-31
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- scgpt
- license
- Apache-2.0
- metadata
- { "category": "biomodels", "third_party": [ { "kind": "weights", "name": "scGPT", "info_url": "https://github.com/bowang-lab/scGPT", "provider": "Wang Lab (University of Toronto)" } ], "display-name": "scGPT", "requirements": [ "gpu" ] }
- description
- Embed and annotate single-cell expression data with scGPT, a foundation model for single-cell biology. Use this skill when: (1) Producing cell embeddings from an AnnData for clustering/integration, (2) Zero-shot or fine-tuned cell-type annotation, (3) Gene-level representation for perturbation/GRN tasks. For probabilistic single-cell models (scVI etc.), use the scvi-tools library.
03 SKILL.md 正文
scGPT — Single-Cell Foundation Model
Prerequisites
| Requirement | Minimum | Recommended |
|---|---|---|
| Python | 3.10+ | 3.11 |
| CUDA | 12.1+ | 12.4+ |
| GPU VRAM | 16 GB | 24 GB+ |
How to run
Loading the vocabulary and checkpoint
scGPT checkpoints are raw directories (args.json, best_model.pt,
vocab.json) — not Hugging Face hub repos. Point at the directory, not an HF
repo id.
from scgpt.tokenizer.gene_tokenizer import GeneVocab
gv = GeneVocab.from_file("/path/to/scgpt-human/vocab.json")
print(len(gv)) # 60697 for the released human checkpoint
Embedding an AnnData
import anndata as ad
from scgpt.tasks import embed_data
adata = ad.read_h5ad("dataset.h5ad") # var must contain a gene-name column
emb = embed_data(
adata,
model_dir="/path/to/scgpt-human",
gene_col="feature_name",
use_fast_transformer=False, # see Gotchas
)
# emb is an AnnData with .obsm["X_scGPT"]
Output format
embed_data returns an AnnData whose .obsm["X_scGPT"] is the per-cell
embedding (n_cells × emb_dim, 512 by default). Downstream: feed to
scanpy.pp.neighbors / scanpy.tl.umap.
Remote compute
Needs ≥24 GB VRAM and the released human checkpoint (~200 MB:
args.json, best_model.pt, vocab.json). Read
compute_details({provider, mode:'read'}) for an environment with scgpt
and a pre-cached checkpoint directory, then:
c = host.compute.create(provider)
job = c.submit_job(
intent="scGPT embed 50k cells — 1×GPU, ~5 min",
inputs=[
"dataset.h5ad",
"embed.py",
],
# env activation is host-specific — put it IN the command string
# (e.g. "conda run -n <env> python3 embed.py"; see compute_details)
command="python3 embed.py",
outputs=["embedded.h5ad"],
run_timeout_s=1800,
)
# the Job repr just printed itself (id, notes) — cell ends here; the kernel never waits on the job
Then call the wait_for_notification brain-tool. When the
compute_done notification arrives, act on its payload:
save_artifacts(payload["output_files"]) # paths under hpc/<job_id>/
For the full record (files, stdout_tail, notes, …), re-enter the
kernel and bind the compute handle separately — .close() lives on the
handle, not on the job object:
c = host.compute.create(provider)
res = c.attach_job(job_id).result() # a read of the persisted result, never a wait
c.close(intent="scGPT embedding done")
See the remote-compute-ssh / remote-compute-modal skill for the
orchestration details.
In embed.py, pass model_dir= the checkpoint path from compute_details.
If flash-attn is unavailable in that environment, set
use_fast_transformer=False.
Gotchas
use_fast_transformerdefault isTruebut resolves to a FlashAttention path that may not import in every env. Passuse_fast_transformer=Falseunless you've confirmedflash_attnloads cleanly.- The package historically depended on
torchtext.vocab.Vocab; in environments without torchtext a pure-Python shim providesVocab— functionally identical forGeneVocab, but if you hitAttributeError: 'Vocab' object has no attribute …, you're on a stale shim. - Gene names must match the vocab; unmatched genes are dropped. Set
gene_colto the column inadata.varthat holds symbols.
Troubleshooting
| Symptom | Fix |
|---|---|
flash_attn is not installed warning at import |
Harmless; pass use_fast_transformer=False |
'Vocab' object has no attribute 'vocab' |
Env has an old torchtext shim — update the env |
| Nearly all genes dropped | Wrong gene_col; check adata.var.columns |
| "scgpt not in manifest" / env-detection misses scGPT | The baked env manifest lists the distribution as scGPT (and flash_attn), pip's canonical casing — normalize manifest keys before lookup: name.lower().replace('-', '_') |
Next: cluster/annotate the embedding with the scanpy library
(sc.pp.neighbors → sc.tl.leiden / sc.tl.umap), or compare to an
scvi-tools latent space on the same data.
04 同仓库更多 Skills
unslop
Edit substantive human-facing prose to remove AI writing patterns while preserving meaning and tone.
pstack-principle-type-system-discipline
Apply when designing types, reviewing a function signature, or writing code in any statically-typed language. Make illegal states unrepresentable, brand semantic primitives, parse external data at boundaries, refuse to lie to the compiler, exhaust variants, derive from authoritative schemas.
pstack-principle-test-behavior-not-implementation
Apply when you write, change, or keep a test. Call the code the way its users do and assert the result they observe against a literal expected value. If the test would still pass when every imported function returns undefined, rewrite the assertion or delete the test.
pstack-principle-subtract-before-you-add
Apply when sequencing an addition, refactor, or rewrite. Remove dead weight, redundant validators, and stub references first, then build on the simpler base.
pstack-principle-sequence-verifiable-units
Sequence migrations or dependent changes around meaningful verification boundaries.
pstack-principle-separate-before-serializing-shared-state
Apply when concurrent actors might write to the same file, branch, key, or state object. Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant.