CellScribe

📜 Paper (bioRxiv 2026): From Closed-Set Annotation to In-Context Discovery: Biologically Grounded LLMs for Cellular Profiling

CellScribe is a generative framework that describes a cell along two complementary axes in a single model: its identity (lineage) and its state (active transcriptional programs). It conditions a pretrained language model (Qwen2.5-0.5B-Instruct) on frozen embeddings of a single-cell foundation model (scFoundation) through adaptive layer normalization (AdaLN): the cell embedding sets the scale and shift of every layer normalization of the language model. Depending on the task-specific prompt, the same model generates:

  • Cell typing: an ontology-grounded cell type (Cell Ontology vocabulary of CELLxGENE). Example: "The cell type is B cell."
  • Cell state: a quantified meta-program profile. Meta-programs are the 41 recurrent malignant programs identified across 24 cancer types with the Curated Cancer Cell Atlas (3CA) by Gavish et al., Hallmarks of transcriptional intratumour heterogeneity across a thousand tumours, Nature 2023, and grouped into 11 hallmarks. CellScribe lists the active programs with their activity scores and the dominant hallmark. Example: "Active programs: Cell Cycle - G2/M (1.9), EMT-II (1.1). Dominant hallmark: Cell cycle."

The paper also describes reinforcement learning against cell-ontology distance and meta-program agreement. Beyond these two tasks, CellScribe identifies cell types outside its supervised vocabulary through in-context learning: the prompt lists a few labelled example cells, each conditioning its own line, and the model infers the type of the query cell.

Model

  • Cell encoder: scFoundation (Hao et al., 2024). The encoder embeds the cell's raw counts over 19,264 genes.
  • Conditioning: a linear projection followed by a layer normalization turns the embedding into a conditioning vector. Through adaptive layer normalization (AdaLN, Peebles and Xie, 2023), that vector sets the scale and shift of every layer normalization of the language model. The AdaLN projections are initialised to zero (AdaLN-Zero), so training starts from the unmodified language model.
  • Language model: Qwen2.5-0.5B-Instruct (Qwen Team, 2024), prompted with a task-specific system prompt and question.

The model was trained on CELLxGENE Census datasets (cell typing) and on the Curated Cancer Cell Atlas, 3CA (cell typing and cell state).

Usage

pip install "torch>=2.6" "transformers>=4.51,!=5.3.0" accelerate pandas

The model code is in this repository and is loaded with trust_remote_code=True. The examples below use the example cells of this repository (examples/, raw counts with gene symbols as columns), all held out of training:

  • cell_typing_sample.csv: four CELLxGENE immune cells, for cell typing.
  • cell_state_sample.csv: four malignant cells from the Curated Cancer Cell Atlas (3CA), for cell state.
  • icl_query_sample.csv and icl_examples_sample.csv, for in-context learning: a query cell of a cell type held out of training, and labelled example cells (first column cell_type).

Using the model directly

The model is a torch.nn.Module, which can be used in a custom inference loop or fine-tuned.

Loading

import pandas as pd
import torch
from huggingface_hub import hf_hub_download
from transformers import AutoModel, AutoTokenizer

model = AutoModel.from_pretrained("InstaDeepAI/CellScribe", trust_remote_code=True).to("cuda")
tokenizer = AutoTokenizer.from_pretrained("InstaDeepAI/CellScribe", trust_remote_code=True)


def load_example(name: str) -> pd.DataFrame:
    path = hf_hub_download("InstaDeepAI/CellScribe", f"examples/{name}.csv")
    return pd.read_csv(path, index_col=0)

Cell typing

cells = load_example("cell_typing_sample")
scrnaseq_input = model.preprocess(cells.values, list(cells.columns))  # raw counts -> encoder inputs
prompt = model.build_prompt(tokenizer, task="cell_typing")
inputs = tokenizer([prompt] * len(cells), return_tensors="pt").to(model.device)
generated = model.generate(
    inputs.input_ids, inputs.attention_mask, scrnaseq_preprocessed_input=scrnaseq_input
)
answers = tokenizer.batch_decode(generated, skip_special_tokens=True)
print([model.parse_cell_type(answer) for answer in answers])
# ['CD4-positive, alpha-beta cytotoxic T cell', 'immature B cell',
#  'CD16-negative, CD56-bright natural killer cell, human', 'CD14-low, CD16-positive monocyte']

Cell state

cells = load_example("cell_state_sample")
scrnaseq_input = model.preprocess(cells.values, list(cells.columns))
prompt = model.build_prompt(tokenizer, task="cell_state")
inputs = tokenizer([prompt] * len(cells), return_tensors="pt").to(model.device)
generated = model.generate(
    inputs.input_ids, inputs.attention_mask, scrnaseq_preprocessed_input=scrnaseq_input
)
for answer in tokenizer.batch_decode(generated, skip_special_tokens=True):
    programs, hallmark = model.parse_cell_state(answer)
    print(programs, hallmark)
# [('Stress (in vitro)', 0.9), ('Stress', 0.8), ('Translation initiation', 0.7), ('MYC-targets', 0.6)] Stress or hypoxia
# [('Unfolded protein response', 1.1), ('immunoglobulins (IGs)', 1.0), ('Protein maturation', 0.8), ('Interferon/MHC-II (I)', 0.8), ('Stress', 0.7)] Protein regulation
# [('Cell Cycle - G1/S', 1.8), ('Cell Cycle - G2/M', 1.7), ('Cell cycle (HMG-rich)', 1.4), ('MYC-targets', 0.9), ('EMT-II', 0.8)] Cell cycle
# [('MYC-targets', 1.0), ('Cell Cycle - G2/M', 0.9), ('Cell cycle (HMG-rich)', 0.7), ('Respiration', 0.6)] Oncogenic

In-context learning

Each example line of the prompt is conditioned by its own cell, the rest of the prompt and the answer by the query cell.

query = load_example("icl_query_sample")
examples = load_example("icl_examples_sample")
example_labels = examples.pop("cell_type").tolist()

with torch.no_grad():
    query_vectors = model.embed_cells(model.preprocess(query.values, list(query.columns)))
    example_vectors = model.embed_cells(model.preprocess(examples.values, list(examples.columns)))
prompt_ids, spans = model.build_in_context_prompt(tokenizer, example_labels)
plan = query_vectors.expand(len(prompt_ids), -1).clone()  # the query cell on every token,
for k, (start, end) in enumerate(spans):
    plan[start:end] = example_vectors[k]  # except the example lines
input_ids = torch.tensor([prompt_ids], device=model.device)
generated = model.generate(
    input_ids,
    torch.ones_like(input_ids),
    conditioning=plan[None],  # batch of one query
    conditioning_default=query_vectors,  # conditions the generated answer
)
print(tokenizer.batch_decode(generated, skip_special_tokens=True))
# ['The cell type is kidney loop of Henle thick ascending limb epithelial cell.']

Training

A teacher-forced loss on the answers (prompt tokens and padding masked out):

cells = load_example("cell_typing_sample")
cell_types = [
    "CD4-positive, alpha-beta cytotoxic T cell",
    "immature B cell",
    "CD16-negative, CD56-bright natural killer cell, human",
    "CD14-low, CD16-positive monocyte",
]
scrnaseq_input = model.preprocess(cells.values, list(cells.columns))
prompt = model.build_prompt(tokenizer, task="cell_typing")
answers = [f"The cell type is {cell_type}.<|im_end|>\n" for cell_type in cell_types]
tokenizer.padding_side = "right"
batch = tokenizer([prompt + answer for answer in answers], return_tensors="pt", padding=True)
batch = batch.to(model.device)
labels = batch.input_ids.clone()
labels[:, : len(tokenizer(prompt).input_ids)] = -100
labels[batch.attention_mask == 0] = -100
model.train()
loss = model(
    batch.input_ids, batch.attention_mask, scrnaseq_preprocessed_input=scrnaseq_input, labels=labels
).loss
loss.backward()

Using CellScribePredictor

CellScribePredictor wraps the model, tokenizer and preprocessing: raw counts in, parsed answers out. It runs in float32 by default (pass autocast_dtype="auto" to any method for bfloat16 on GPU, as in the paper's evaluation).

predictor = model.predictor(tokenizer)  # model and tokenizer loaded as above

Cell typing

cells = load_example("cell_typing_sample")
print(predictor.predict_cell_type(cells.values, list(cells.columns)))
# ['CD4-positive, alpha-beta cytotoxic T cell', 'immature B cell',
#  'CD16-negative, CD56-bright natural killer cell, human', 'CD14-low, CD16-positive monocyte']

Cell state

cells = load_example("cell_state_sample")
for prediction in predictor.predict_cell_state(cells.values, list(cells.columns)):
    print(prediction.programs, prediction.hallmark)
# [('Stress (in vitro)', 0.9), ('Stress', 0.8), ('Translation initiation', 0.7), ('MYC-targets', 0.6)] Stress or hypoxia
# [('Unfolded protein response', 1.1), ('immunoglobulins (IGs)', 1.0), ('Protein maturation', 0.8), ('Interferon/MHC-II (I)', 0.8), ('Stress', 0.7)] Protein regulation
# [('Cell Cycle - G1/S', 1.8), ('Cell Cycle - G2/M', 1.7), ('Cell cycle (HMG-rich)', 1.4), ('MYC-targets', 0.9), ('EMT-II', 0.8)] Cell cycle
# [('MYC-targets', 1.0), ('Cell Cycle - G2/M', 0.9), ('Cell cycle (HMG-rich)', 0.7), ('Respiration', 0.6)] Oncogenic

An AnnData object holding raw counts can be used directly with predictor.predict_anndata(adata, task="cell_typing") (or task="cell_state").

In-context learning

query = load_example("icl_query_sample")
examples = load_example("icl_examples_sample")
example_labels = examples.pop("cell_type").tolist()

# Without examples: the held-out cell type cannot be predicted
print(predictor.predict_cell_type(query.values, list(query.columns)))
# ['kidney distal convoluted tubule epithelial cell']

# With labelled examples
print(
    predictor.predict_cell_type_in_context(
        query.values, list(query.columns), examples.values, list(examples.columns), example_labels
    )
)
# ['kidney loop of Henle thick ascending limb epithelial cell']

Input

  • Counts: raw UMI counts, not normalised values. The model applies its own normalisation (CP10k + log1p).
  • Gene names: HGNC symbols. For CELLxGENE files, set adata.var_names = adata.var["feature_name"].
  • Genes: the cell encoder reads a fixed list of 19,264 genes (gene_list.txt). Datasets rarely measure exactly these genes, so model.preprocess maps the input genes onto this list: listed genes absent from the input are given a count of zero, and genes outside the list are dropped.

Files

File Content
config.json, model.safetensors model hyper-parameters and weights
*.py the model code, loaded with trust_remote_code=True
tokenizer files Qwen2.5 tokenizer
gene_list.txt the 19,264 genes read by the cell encoder, in order
cell_types.txt cell-type vocabulary used to read cell-typing answers
examples/ example cells of this card (raw counts, gene symbols as columns)
LICENSE.md, NOTICE license terms (see below)

License

CellScribe is released by InstaDeep Ltd and CentraleSupélec under the Apache License 2.0, except for its cell encoder: the scFoundation encoder weights (scrna_encoder.*, unmodified) remain under the scFoundation Model License of BioMap, which allows non-commercial research use only and excludes any commercial, military or illegal purpose. The language model is derived from Qwen2.5-0.5B-Instruct (Apache 2.0). See NOTICE for the third-party terms, including the scFoundation Model License.

The example cells in examples/ are from CELLxGENE and the Curated Cancer Cell Atlas (3CA) and remain under their sources' terms.

Citation

@article{gelard2026closed,
  title={From Closed-Set Annotation to In-Context Discovery: Biologically Grounded LLMs for Cellular Profiling},
  author={Gelard, Maxence and Benkirane, Hakim and Pierrot, Thomas and Cournede, Paul-Henry and P. de Almeida, Bernardo},
  journal={bioRxiv},
  pages={2026--10},
  year={2026},
  publisher={Cold Spring Harbor Laboratory}
}

The cell encoder is scFoundation:

@article{hao2024large,
  title={Large-scale foundation model on single-cell transcriptomics},
  author={Hao, Minsheng and Gong, Jing and Zeng, Xin and Liu, Chiming and Guo, Yucheng and Cheng, Xingyi and Wang, Taifeng and Ma, Jianzhu and Zhang, Xuegong and Song, Le},
  journal={Nature Methods},
  volume={21},
  number={8},
  pages={1481--1491},
  year={2024},
  publisher={Nature Publishing Group}
}

The language model is Qwen2.5-0.5B-Instruct:

@article{qwen2024qwen25,
  title={{Qwen2.5} Technical Report},
  author={{Qwen Team}},
  journal={arXiv preprint},
  year={2024}
}

The cell-state task uses the meta-programs of the Curated Cancer Cell Atlas:

@article{gavish2023hallmarks,
  title={Hallmarks of transcriptional intratumour heterogeneity across a thousand tumours},
  author={Gavish, Avishai and Tyler, Michael and Greenwald, Alissa C. and Hoefflin, Rouven and Simkin, Dor and Tschernichovsky, Roi and Galili Darnell, Noam and Somech, Einav and Barbolin, Chaya and Antman, Tomer and others},
  journal={Nature},
  volume={618},
  number={7965},
  pages={598--606},
  year={2023},
  publisher={Nature Publishing Group}
}
Downloads last month
59
Safetensors
Model size
0.7B params
Tensor type
F32
·
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support