--- license: apache-2.0 language: - en pipeline_tag: text-generation tags: - biology - single-cell - scRNA-seq - cell-type-annotation --- # CellScribe 📜 **[Paper (bioRxiv 2026)](https://www.biorxiv.org/content/10.64898/2026.10.07.757352)**: *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](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct)) on frozen embeddings of a single-cell foundation model ([scFoundation](https://www.nature.com/articles/s41592-024-02305-7)) 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](https://www.nature.com/articles/s41586-023-06130-4), 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](https://www.nature.com/articles/s41592-024-02305-7) (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](https://openaccess.thecvf.com/content/ICCV2023/html/Peebles_Scalable_Diffusion_Models_with_Transformers_ICCV_2023_paper.html)), 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](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct) ([Qwen Team, 2024](https://qwenlm.github.io/blog/qwen2.5/)), prompted with a task-specific system prompt and question. The model was trained on [CELLxGENE Census](https://chanzuckerberg.github.io/cellxgene-census/) datasets (cell typing) and on the [Curated Cancer Cell Atlas, 3CA](https://www.weizmann.ac.il/sites/3CA/) (cell typing and cell state). ## Usage ```bash 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 ```python 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 ```python 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 ```python 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. ```python 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): ```python 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). ```python predictor = model.predictor(tokenizer) # model and tokenizer loaded as above ``` #### Cell typing ```python 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 ```python 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 ```python 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](LICENSE.md), except for its cell encoder: the scFoundation encoder weights (`scrna_encoder.*`, unmodified) remain under the [scFoundation Model License](https://github.com/biomap-research/scFoundation/blob/main/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](https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct) (Apache 2.0). See [`NOTICE`](NOTICE) for the third-party terms, including the scFoundation Model License. The example cells in `examples/` are from [CELLxGENE](https://cellxgene.cziscience.com/) and the [Curated Cancer Cell Atlas (3CA)](https://www.weizmann.ac.il/sites/3CA/) and remain under their sources' terms. ## Citation ```bibtex @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: ```bibtex @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: ```bibtex @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: ```bibtex @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} } ```