---
license: apache-2.0
language:
  - en
tags:
  - biology
  - single-cell
  - rna-seq
  - scRNA-seq
  - embeddings
---

# SCimilarity — Extended Model

An extended version of [SCimilarity](https://github.com/Genentech/scimilarity), a metric-learning model for single-cell RNA-seq that maps cells to a unified 128-dimensional embedding space. The original model and method are described in:

> Heimberg et al., **"A cell atlas foundation model for scalable search of similar human cells"**, *Nature*, 2024. https://doi.org/10.1038/s41586-024-08411-y

---

## What's different here

The original SCimilarity was trained on ~7.9 million annotated cells from 56 studies. This model was retrained from scratch on a significantly larger corpus extracted from [CZ CELLxGENE Discover](https://cellxgene.cziscience.com/), using the same filtering criteria as the original paper (human cells, non-cancerous tissue, 10x Genomics platform).

| | Original | This model |
|---|---|---|
| Training cells | 7.9 M | **39.5 M** |
| Search index cells | 23.4 M | **45.5 M** |

---

## Repository contents

```
├── encoder.ckpt            # encoder weights (use this for embedding)
├── decoder.ckpt            # decoder weights (reconstruction)
├── gene_order.tsv          # 28,231 gene symbols the model expects as input
├── layer_sizes.json        # network architecture
├── hyperparameters.json    # training hyperparameters
├── label_ints.csv          # cell type label → integer mappings
├── metadata.json           # dataset metadata
├── reference_labels.tsv    # per-cell metadata for all reference cells
│                           # (cell type, donor, tissue, dataset)
├── annotation/
│   └── labelled_kNN.bin    # kNN index for cell type annotation
└── cellsearch/
    └── full_kNN.bin        # kNN index for similarity search
```

**The index files (`annotation/` and `cellsearch/`) are large (~160 GB combined) but optional.** If you only need to embed cells into the latent space — for clustering, visualization, or building your own index — you only need `encoder.ckpt`, `gene_order.tsv`, and `layer_sizes.json`.

---

## Installation

```bash
pip install scimilarity
```

Or from source:

```bash
git clone https://github.com/Genentech/scimilarity
cd scimilarity
pip install -e .
```

---

## Usage

For full usage examples including cell type annotation and similarity search, see the [original SCimilarity notebooks](https://github.com/Genentech/scimilarity/tree/main/docs/notebooks). Simply point `model_path` to your local copy of this repository instead of the original model directory.

### Encoder-only (no index required)

If you want to embed cells without downloading the full index:

```python
import scanpy as sc
from scimilarity import CellEmbedding
from scimilarity.utils import align_dataset, lognorm_counts

ce = CellEmbedding(model_path="/path/to/model_v0")

adata = sc.read_h5ad("your_data.h5ad")
adata = align_dataset(adata, ce.gene_order)
adata = lognorm_counts(adata)

embeddings = ce.get_embeddings(adata.X)
adata.obsm["X_scimilarity"] = embeddings
```

---

## Model architecture

| Parameter | Value |
|---|---|
| Input genes | 28,230 |
| Hidden layers | 3 × 1,024 |
| Embedding dimension | 128 |
| Normalization | L2 (unit hypersphere) |
| Loss | Triplet (semi-hard) + MSE reconstruction |