alterlab-scgpt

Files (3)

• SKILL.md
• evals.json · evals/
• scgpt_usage.md · references/

SKILL.md (first lines)

# scGPT (single-cell foundation model)

## Overview

**scGPT** (Cui et al., *Nature Methods* 2024; `bowang-lab/scGPT`) is a transformer **foundation
model** pretrained on tens of millions of cells. It provides **zero-shot** and fine-tuned
**cell-type annotation**, **gene and cell embeddings**, **batch integration**, and
gene-regulatory / perturbation inference — all operating on **AnnData** (`.h5ad`) objects.

Its niche vs. the existing single-cell skills: scGPT is the *pretrained-transformer* route.
For probabilistic latent-variable models use `alterlab-scvi-tools`; for the conventional
Scanpy analysis pipeline use `alterlab-scanpy`; scGPT complements both.

## When to Use This Skill

Use this skill when the user wants to:
- **Annotate cell types** with a pretrained foundation model (zero-shot or fine-tuned).
- Generate **scGPT embeddings** for cells or genes.
- **Integrate batches** using the transformer's representation.
- Run **zero-shot** inference / transfer to a new dataset without training from scratch.

### Does NOT Trigger

| Scenario | Use instead |
|----------|-------------|
| Probabilistic integration / latent model (scVI, scANVI) | `alterlab-scvi-tools` |
| Standard QC → cluster → UMAP → differential expression | `alterlab-scanpy` |
| Read/write/wrangle the `.h5ad` data structure itself | `alterlab-anndata` |
| RNA velocity | `alterlab-scvelo` |
| Protein (not single-cell) language models | `alterlab-esm` |

## Core Capabilities

### 1. Zero-shot cell embedding & annotation

```python
import scanpy as sc
from scgpt.tasks import embed_data

adata = sc.read_h5ad("cells.h5ad")
adata = embed_data(
    adata,
    model_dir="checkpoints/scGPT_human",   # downloaded checkpoint folder
    gene_col="feature_name",               # column in adata.var holding gene symbols
    batch_size=64,
    device="cuda",
)
# cell embeddings land in adata.obsm["X_scGPT"]
```

`gene_col` must name an `adata.var` column of gene symbols matching the checkpoint's vocabulary
(pass `"index"` to use `var_names`); symbols that miss the vocab are dropped, so check how many
genes survive before trusting the embedding. Set `use_fast_transformer=False` when flash-attn
is not installed. Zero-shot mode maps a new dataset onto scGPT's learned space without training
— fast triage of cell identities. Fine-tuning on labeled reference data improves accuracy on a
specific tissue.

### 2. Embeddings for downstream analysis

Produce cell embeddings (for clustering/visualization) or gene embeddings (for
gene-network/similarity analysis). Feed embeddings back into a Scanpy neighbors/UMAP workflow.

### 3. Batch integration

Use the model representation to integrate across batches/donors, comparable in role to
scVI-based integration but from the pretrained-transformer paradigm.

### 4. Environment, GPU, and dispatch

scGPT's last release is 0.2.4 (March 2025) and its pins have not moved since: it requires
`scvi-tools<1.0` and `scanpy<2.0`, and imports `torchtext`, whose own last release was 0.18.0
in April 2024. That stack will not co-install with a current scverse environment, so give scGPT
its own venv and move data between environments as `.h5ad` files rather than trying to satisfy
both sets of pins at once. Say so plainly when a user expects it to drop into their existing
environment.

Checkpoints (whole-human, continual-pretrained, organ-specific) are downloaded by hand from the
Drive links in the upstream README — there is no `from_pretrained` downloader. The
whole-human model is the default choice; the continual-pretrained one is aimed at zero-shot
cell-embedding tasks.

scGPT needs a GPU for realistic dataset sizes; fine-tuning is heavy. Dispatch fine-tuning /
large inference via `alterlab-remote-compute` (submit → poll → harvest). Keep the AnnData I/O
consistent with `alterlab-anndata`.

Because the model has been static for over a year while the foundation-model field has not,
treat its published benchmarks as a 2024 snapshot: report the checkpoint name and date with any
result, and where annotation accuracy matters, sanity-check the labels against marker-gene
evidence (`alterlab-scanpy`) rather than accepting them unverified.

## Resources

- `references/scgpt_usage.md` — install/pinning, checkpoints, embed/annotate/fine-tune calls,
  scverse integration, and paradigm comparison. Loaded on demand.

Part of the AlterLab Academic Skills suite.

From AlterLab-IEU/AlterLab-Academic-Skills, MIT.

More from AlterLab-IEU/AlterLab-Academic-Skills