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:

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:

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

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.