README.md

---
language:
- en
library_name: pytorch
pipeline_tag: feature-extraction
tags:
- single-cell
- transcriptomics
- scRNA-seq
- cell-embedding
- pytorch
license: apache-2.0
---

# scRep

scRep is a PyTorch model for extracting cell embeddings from
single-cell RNA-seq AnnData (`.h5ad`) inputs. This repository is a standalone
Hugging Face release bundle: it includes checkpoint weights, the exact paired
gene vocabulary, the inference implementation, and runnable examples.

## Checkpoints

| Checkpoint | Directory | Vocabulary size | Required paired assets |
| --- | --- | ---: | --- |
| 2026-06-25 / 30M | `checkpoints/scRep_20260625_30M/` | 19,240 | `checkpoints/scRep_20260625_30M/assets/` |
| 2026-07-17 / 3M | `checkpoints/scRep_20260717_3M/` | 19,239 | `checkpoints/scRep_20260717_3M/assets/` |

`model.safetensors`, `config.json`, and `assets/gene_vocab.json` from the
same checkpoint directory must always be used together. The checkpoint names
are retained as release identifiers; they do not by themselves specify a
parameter count or a benchmark claim.

## Installation

Python 3.10--3.12 is supported. Install a PyTorch build appropriate for the
target CPU/CUDA platform first, then install the remaining requirements:

```bash
pip install -r requirements.txt
```

## Upload to Hugging Face

Upload the contents of this directory as a model repository. The included
`.gitattributes` marks `*.safetensors` for Git LFS; run `git lfs install`
before committing the two weight files.

## Quick start

From the root of this model repository:

```bash
python examples/inference.py \
  --input_h5ad /path/to/input.h5ad \
  --output embeddings.npy \
  --checkpoint checkpoints/scRep_20260625_30M
```

The output is a float32 NumPy matrix with one 768-dimensional, L2-normalized
embedding per retained input cell. Input genes are matched by exact names to
the bundled vocabulary. Cells with no matched non-zero genes are skipped.
By default the script reads `adata.X`; add `--use_raw` to use `adata.raw.X`.

The same workflow is available interactively in
`examples/embedding_example.ipynb`.

## Files

```text
scRep_release/
├── README.md
├── LICENSE                         
├── requirements.txt
├── scRep_inference.py
├── scRep_pretrain/                 # Inference architecture implementation
├── examples/
│   ├── inference.py
│   └── embedding_example.ipynb
└── checkpoints/
    ├── scRep_20260625_30M/
    │   ├── config.json
    │   ├── model.safetensors
    │   └── assets/{gene_vocab.json,gene_names.txt,meta_vocab.json,manifest.json}
    └── scRep_20260717_3M/
        ├── config.json
        ├── model.safetensors
        └── assets/{gene_vocab.json,gene_names.txt,meta_vocab.json,manifest.json}
```

## Limitations and responsible use

The embeddings are research outputs, not clinical measurements or diagnostic
predictions. Validate performance, preprocessing, gene naming conventions,
and potential batch/demographic bias for every downstream dataset before use.
Do not use this model as the sole basis for medical decisions.

## License

The code and checkpoint weights in this release are distributed under the
Apache License 2.0. See `LICENSE` for the complete terms.