# Single Cell Foundation Model Langcell

> Use this skill when a task involves the LangCell project for single-cell language-cell modeling, especially zero-shot cell type annotation, few-shot annotation, LangCell-CE finetuning, Geneformer-style tokenization, or preparing text descriptions for candidate cell identities and multimodal cell-text matching workflows.

- Skill: `pharmolix/single-cell-foundation-model-langcell` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add pharmolix/single-cell-foundation-model-langcell`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pharmolix/single-cell-foundation-model-langcell/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: pharmolix (https://skillmd.com/u/pharmolix)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pharmolix/single-cell-foundation-model-langcell

---


# LangCell

## Use This Skill When

Use this skill for the local LangCell project at `/DATA/disk0/zhaosy/home/LangCell`.
It is the right choice when the task involves:

- zero-shot cell identity or cell type annotation from tokenized single-cell data
- few-shot cell type annotation with very limited labels
- finetuning only the LangCell cell encoder (`LangCell-CE`)
- preprocessing AnnData into the tokenized format expected by LangCell
- preparing text descriptions for candidate cell identities
- understanding how LangCell combines cell embeddings and text embeddings

Do not use this skill for ordinary Scanpy analysis that does not depend on LangCell.

## Start Here

1. Confirm whether the user wants zero-shot annotation, few-shot annotation, or cell-encoder-only finetuning.
2. Check that the input is already tokenized, or route through preprocessing first.
3. Check whether the required external assets exist: checkpoints, tokenized dataset, ontology / text-description JSON.
4. Prefer the zero-shot path first if the user is exploring LangCell rather than benchmarking a supervised baseline.

## Choose A Path

### Zero-shot annotation

Start here for most LangCell usage. The defining behavior is:

- encode cells with `cell_bert + cell_proj`
- encode candidate texts with `text_bert + text_proj`
- score cell-text matches with `ctm_head`
- combine similarity and matching scores for final predictions

Use `LangCell-annotation-zeroshot/zero-shot.ipynb` as the primary reference path.

### Few-shot annotation

Use `LangCell-annotation-fewshot/fewshot.py` when only a tiny labeled support set
is available and the user still wants the multimodal LangCell path.

### LangCell-CE finetuning

Use `LangCell-CE-annotation/finetune.py` when the user wants a standard
supervised classifier on top of the pretrained cell encoder.

### Preprocessing

LangCell does not take raw `.h5ad` directly for these downstream scripts. First:

- read AnnData with `scanpy`
- add `obs["n_counts"]`
- ensure `var["ensembl_id"]` exists
- tokenize with `LangCellTranscriptomeTokenizer`
- save with `save_to_disk(...)`

## Guardrails

- Do not claim raw `.h5ad` can be passed directly into LangCell inference; tokenization is required first.
- Do not assume checkpoints live in the repo. The official repo expects external downloads.
- Do not treat zero-shot prediction as plain nearest-neighbor on cell embeddings; the project combines similarity and cell-text matching.
- Do not assume label columns are named consistently. The repo checks several alternatives such as `celltype`, `cell_type`, `str_labels`, and `labels`.
- If new cell types are needed, prepare textual descriptions carefully instead of inventing bare labels with no ontology context.

## Read More Only If Needed

- Read `references/local-usage.md` for entry points, asset requirements, and practical checks.
- Read `references/model-notes.md` when the task depends on LangCell's multimodal design or paper-level motivation.