---
license: gpl-3.0
library_name: celllucid
tags:
  - single-cell
  - topic-modeling
  - transcriptomics
  - human-cell-atlas
  - transcriptformer
---

# CellLucid model assets

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

These are the model assets for [CellLucid](https://github.com/Catchxu/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](https://github.com/czi-ai/transcriptformer) by the Chan Zuckerberg Initiative.
They were downloaded from
[CZI](https://czi-transcriptformer.s3.amazonaws.com/weights/tf_sapiens.tar.gz) 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](https://github.com/czi-ai/transcriptformer/blob/main/LICENSE.md), and its use
follows CZI's [Acceptable Use Policy](https://virtualcellmodels.cziscience.com/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

```bash
hf download kaichenxu/CellLucid --local-dir assets
```

Then follow the [CellLucid README](https://github.com/Catchxu/CellLucid#usage) to preprocess
counts and assign topics. The topic banks and CellLucid code are released under GPL-3.0.