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-11-14
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- scgpt
- license
- Apache-2.0
- category
- biomodels
- metadata
- { "third_party": [ { "kind": "weights", "name": "scGPT", "info_url": "https://github.com/bowang-lab/scGPT", "provider": "Wang Lab (University of Toronto)" } ], "display-name": "scGPT" }
- 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.
- requirements
- [ "gpu" ]
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=[
{"src": "dataset.h5ad", "dst_filename": "dataset.h5ad"},
{"src": "embed.py", "dst_filename": "embed.py"},
],
command="python3 embed.py",
environment=..., # env name from compute_details
outputs=["embedded.h5ad"],
timeout_seconds=1800,
)
print(job.job_id) # cell ends here — kernel never blocks on compute
Then call the wait_for_notification brain-tool. When the
compute_done notification arrives, act on its payload:
save_artifacts(payload["featured_files"]) # paths under hpc/<job_id>/
For the full result dict (output_files, remote_workdir, …), re-enter the
kernel and bind the compute handle separately — .close() lives on the
handle, not on the job object:
h = host.compute.create(provider)
res = h.attach_job(job_id).result()
h.close()
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
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.