single-cell-foundation-model-geneformer

name: single-cell-foundation-model-geneformer description: > Use this skill when a task involves Geneformer workflows, especially TranscriptomeTokenizer input preparation, tokenized .dataset generation, cell or gene classification with Classifier, embedding extraction with EmbExtractor, and in silico perturbation analysis with InSilicoPerturber.

Geneformer

Use This Skill When

Use this skill when the task involves official Geneformer workflows such as:

• converting raw scRNA-seq data into Geneformer tokenized datasets
• fine-tuning Geneformer for cell or gene classification
• extracting cell or gene embeddings
• generating state embeddings for downstream perturbation analysis
• running in silico perturbation or in silico treatment style analyses
• distinguishing pretrained zero-shot usage from fine-tuned classifier usage

This skill is for Geneformer-specific workflows, not generic single-cell model use.

Start Here

1. Confirm the input is raw-count scRNA-seq data and still suitable for tokenization.
2. Check that ensembl_id and n_counts are available.
3. Tokenize first unless the user already has a Geneformer .dataset.
4. Decide whether the task is classification, embedding extraction, or in silico perturbation.

Choose A Path

Tokenization

Use TranscriptomeTokenizer first for almost every Geneformer workflow. This step converts raw-count .loom or .h5ad data into tokenized datasets used by the downstream APIs.

Geneformer expects:

• row attribute ensembl_id
• cell attribute n_counts

Optional metadata can be passed through during tokenization.

Classification

Use Classifier for:

• cell state classification
• cell type annotation
• gene classification tasks

The input is a tokenized Geneformer .dataset object, not raw AnnData.

Embedding extraction

Use EmbExtractor when the task is to:

• extract CLS, cell, or gene embeddings
• plot or inspect cell embeddings
• generate state embeddings for later perturbation analysis

In silico perturbation

Use InSilicoPerturber for zero-shot or model-based perturbation analyses such as:

• deleting or shifting genes
• modeling start and goal cell states
• ranking perturbations by movement toward a desired cell state

This is one of Geneformer's defining workflows and should be treated as more than ordinary classifier inference.

Guardrails

• Do not pass feature-selected matrices into the tokenizer; the docs expect raw counts without feature selection.
• Do not use gene symbols where the tokenizer expects ensembl_id.
• Do not confuse tokenized .dataset files with AnnData objects.
• Do not skip tokenization and jump directly to classifiers or perturbation APIs.
• For perturbation tasks, be explicit about model type, embedding mode, and target cell states.

Official Workflow Surface

Read More Only If Needed

• For operational usage and required input fields, read references/workflows.md.
• For official source locations and model-specific notes, read references/sources-and-notes.md.