File size: 3,550 Bytes
59e4fc9 faec2e7 59e4fc9 66b8319 59e4fc9 66b8319 59e4fc9 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 | ---
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 |
| `reactome/human_pathways.csv` | Human pathways of Reactome release 97 with their hierarchy, gene symbols and disease flag, used to map topics to pathways | Built from [Reactome](https://reactome.org) data (CC0) 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 |
## Reactome pathways
`reactome/human_pathways.csv` lists the human pathways of Reactome release 97, one per row, with
their parents, children, top-level categories, gene symbols and Reactome's `isInDisease` flag.
CellLucid maps each topic to one non-disease pathway from this table. Reactome data are released
under CC0. If you use the pathway mapping, please cite Reactome:
> Milacic et al., *The Reactome Pathway Knowledgebase 2024*, Nucleic Acids Research (2024).
## 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.
|