CellLucid model assets

CellLucid enables natural-language querying of single-cell atlases through interpretable topic modeling.

These are the model assets for CellLucid. Each cell is described as a mixture of 128 gene programs (topics).

Contents

Path	What it is	Origin
tf_sapiens/	TF-Sapiens backbone: config.json, model_weights.pt, vocabs/	Not trained by CellLucid. TranscriptFormer weights released by the Chan Zuckerberg Initiative, redistributed unmodified
topic_banks/default/	Topic bank whose topics exclude mitochondrial, ribosomal-protein and TCR/BCR V-segment genes	Trained by CellLucid
topic_banks/all_genes/	Topic bank trained on every gene	Trained by CellLucid
gene_symbols.json	GENCODE v49 gene symbol to Ensembl ID mapping	Built from GENCODE by CellLucid

Backbone: TranscriptFormer (TF-Sapiens)

The files in tf_sapiens/ come from TranscriptFormer by the Chan Zuckerberg Initiative. They were downloaded from CZI and are redistributed here unmodified, so that CellLucid installs from one place. CellLucid keeps the backbone frozen and does not train or fine-tune it. TranscriptFormer is released under the MIT license, and its use follows CZI's Acceptable Use Policy. If you use these weights, please cite TranscriptFormer:

Pearce et al., A cross-species generative cell atlas across 1.5 billion years of evolution: The TranscriptFormer single-cell model, bioRxiv (2025).

Topic banks

CellLucid trained both banks on frozen TF-Sapiens embeddings of 7.5 million cells from 22 Human Cell Atlas studies, each cell used once; five further studies were held out for evaluation. Each bank holds 128 topics: unit vectors in the backbone's embedding space, which assign a cell by a temperature-0.05 softmax, plus a topic-by-gene dictionary. Banks store Ensembl IDs (genes.json) and gene symbols (symbols.json).

Bank	Best for
default	interpreting programs, comparing cell types across studies, querying
all_genes	quality control, technical or sample-level analysis, full-profile reconstruction

Usage

hf download kaichenxu/CellLucid --local-dir assets

Then follow the CellLucid README to preprocess counts and assign topics. The topic banks and CellLucid code are released under GPL-3.0.