scgpt

1# scGPT — Single-Cell Foundation Model
2 
3## Prerequisites
4 
5| Requirement | Minimum | Recommended |
6| ----------- | ------- | ----------- |
7| Python      | 3.10+   | 3.11        |
8| CUDA        | 12.1+   | 12.4+       |
9| GPU VRAM    | 16 GB   | 24 GB+      |
10 
11## How to run
12 
13### Loading the vocabulary and checkpoint
14 
15scGPT checkpoints are **raw directories** (`args.json`, `best_model.pt`,
16`vocab.json`) — not Hugging Face hub repos. Point at the directory, not an HF
17repo id.
18 
19```python
20from scgpt.tokenizer.gene_tokenizer import GeneVocab
21gv = GeneVocab.from_file("/path/to/scgpt-human/vocab.json")
22print(len(gv))   # 60697 for the released human checkpoint
23```
24 
25### Embedding an AnnData
26 
27```python
28import anndata as ad
29from scgpt.tasks import embed_data
30 
31adata = ad.read_h5ad("dataset.h5ad")        # var must contain a gene-name column
32emb = embed_data(
33    adata,
34    model_dir="/path/to/scgpt-human",
35    gene_col="feature_name",
36    use_fast_transformer=False,             # see Gotchas
37)
38# emb is an AnnData with .obsm["X_scGPT"]
39```
40 
41## Output format
42 
43`embed_data` returns an `AnnData` whose `.obsm["X_scGPT"]` is the per-cell
44embedding (`n_cells × emb_dim`, 512 by default). Downstream: feed to
45`scanpy.pp.neighbors` / `scanpy.tl.umap`.
46 
47## Remote compute
48 
49Needs ≥24 GB VRAM and the released human checkpoint (~200 MB:
50`args.json`, `best_model.pt`, `vocab.json`). Read
51`compute_details({provider, mode:'read'})` for an environment with `scgpt`
52and a pre-cached checkpoint directory, then:
53…