{
  "skill": "alterlab-scgpt",
  "evals": [
    {
      "id": "zero-shot-annotation",
      "prompt": "I have an unlabeled scRNA-seq dataset in h5ad. Use a pretrained single-cell foundation model to annotate the cell types without training my own classifier.",
      "expected_output": "Invokes alterlab-scgpt: loads a pretrained scGPT checkpoint, embeds the AnnData cells, and transfers cell-type labels zero-shot. Notes GPU need and heavy fine-tuning dispatch via alterlab-remote-compute.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "zero-shot" },
        { "type": "behavior", "value": "Uses a pretrained foundation model for annotation rather than training a classifier from scratch." }
      ]
    },
    {
      "id": "cell-embeddings",
      "prompt": "Generate scGPT embeddings for my cells so I can cluster them in the learned representation.",
      "expected_output": "Invokes alterlab-scgpt to produce cell embeddings from a pretrained checkpoint, then feeds them into a neighbors/UMAP workflow (alterlab-scanpy) for clustering.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "output_contains", "value": "embedding" }
      ]
    },
    {
      "id": "batch-integration",
      "prompt": "Integrate several scRNA-seq batches using a transformer foundation-model representation to remove batch effects.",
      "expected_output": "Invokes alterlab-scgpt to integrate batches via the model representation, comparable in role to scVI integration but from the pretrained-transformer paradigm.",
      "assertions": [
        { "type": "should_trigger", "value": true },
        { "type": "behavior", "value": "Integrates batches using the scGPT representation." }
      ]
    },
    {
      "id": "near-miss-scvi-tools",
      "prompt": "I want a probabilistic latent-variable model (scVI/scANVI) to integrate my data and do differential expression with uncertainty.",
      "expected_output": "Should NOT trigger this skill; defers to alterlab-scvi-tools, which provides the probabilistic VAE models (scVI/scANVI). scGPT is the pretrained-transformer route, not the probabilistic-latent-model route.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-scvi-tools" }
      ]
    },
    {
      "id": "near-miss-scanpy",
      "prompt": "Run the standard single-cell workflow: QC filtering, normalization, PCA, Leiden clustering, and a UMAP with marker genes.",
      "expected_output": "Should NOT trigger this skill; defers to alterlab-scanpy, the standard analysis pipeline. scGPT is a foundation model for annotation/embeddings, not the conventional QC→cluster→UMAP toolchain.",
      "assertions": [
        { "type": "should_not_trigger", "value": true },
        { "type": "output_contains", "value": "alterlab-scanpy" }
      ]
    }
  ]
}

# scGPT — Usage Reference

Deeper detail for `alterlab-scgpt`. API and packaging below were checked against the upstream
`bowang-lab/scGPT` repo (2026-09); PyPI `scgpt` is still 0.2.4 (March 2025).

## Install

```bash
# dedicated environment — scgpt's pins conflict with a current scverse stack
uv venv .venv-scgpt && source .venv-scgpt/bin/activate
uv pip install scgpt "flash-attn<1.0.5"   # flash-attn optional; needs CUDA to build
```

Upstream also documents `"orbax<0.1.8"` as a workaround for resolver failures. Poetry
installation is documented as out of sync — use pip/uv.

Then download a checkpoint folder (whole-human, continual-pretrained, or organ-specific) from
the Drive links in the upstream README; each folder ships the paired gene-name→id vocabulary.
A GPU is strongly recommended.

## Zero-shot embedding API

```python
from scgpt.tasks import embed_data

adata = embed_data(
    adata_or_file,            # AnnData or path to .h5ad
    model_dir="checkpoints/scGPT_human",
    gene_col="feature_name",  # or "index" to use var_names
    max_length=1200,          # genes per cell fed to the transformer
    batch_size=64,
    obs_to_save=["celltype"], # obs columns to carry through
    device="cuda",
    use_fast_transformer=True,  # False when flash-attn is absent
    return_new_adata=False,     # False: writes adata.obsm["X_scGPT"] in place
)
```

`scgpt.tasks` also exposes `get_batch_cell_embeddings` (the lower-level batched call) and
`GeneEmbedding` (gene-embedding / GRN work).

## Typical tasks

- **Zero-shot annotation** — embed a query dataset with a pretrained checkpoint and transfer
  labels from a reference. Fast, no training.
- **Fine-tuned annotation** — fine-tune on a labeled reference for a specific tissue for higher
  accuracy (GPU-heavy — dispatch via `alterlab-remote-compute`).
- **Embeddings** — export cell/gene embeddings for clustering, UMAP, or gene-network analysis.
- **Integration** — use the model representation to integrate batches/donors.

Annotation and perturbation fine-tuning are driven by the scripts and notebooks in the repo's
`examples/` and `tutorials/` directories (e.g. `examples/finetune_integration.py`), not by a
stable importable API — read the notebook matching your task rather than assuming a function
name.

## scverse integration

Inputs and outputs are AnnData (`.h5ad`). Keep the object well-formed with `alterlab-anndata`,
and feed scGPT embeddings into a Scanpy neighbors/UMAP/Leiden workflow (`alterlab-scanpy`) for
downstream steps.

## Choosing the single-cell skill

| Goal | Skill |
|------|-------|
| Pretrained foundation-model annotation/embeddings | `alterlab-scgpt` |
| Probabilistic latent model (scVI/scANVI), integration, DE | `alterlab-scvi-tools` |
| Standard pipeline: QC, clustering, UMAP, marker DE | `alterlab-scanpy` |
| `.h5ad` data structure I/O and wrangling | `alterlab-anndata` |
| RNA velocity | `alterlab-scvelo` |