scUNVEIL

scUNVEIL is a pretrained foundation model for human single-cell RNA sequencing (scRNA-seq).

The model is trained using next-UMI prediction, where observed UMI counts are randomly partitioned into retained input counts and held-out target counts. During training, the model predicts the gene-frequency distribution of the held-out molecules from the retained observations.

This objective produces rich cell representations while simultaneously estimating the transcriptome composition expected under deeper sampling of the same effective measurement process, a concept we refer to as measurement enrichment.

The recommended way to use the model is through the official Python package:

pip install scunveil

Quick Start

import anndata as ad
from scunveil import scUnveil

# adata.X must contain raw UMI counts;
# gene identifiers must be available in adata.var.
adata = ad.read_h5ad("raw_counts.h5ad")

model = scUnveil()
model.set_input_anndata(adata)

embeddings = model.get_embeddings()

The default output consists of 512 PCA components.

Additional examples and the complete API are available in the GitHub repository.

Input Requirements

scUNVEIL accepts an AnnData object, typically loaded from an .h5ad file.

The object must contain:

raw, non-negative, integer-like UMI counts in adata.X
human gene identifiers in the adata.var index or one of its columns for mapping to the model vocabulary

Human gene symbols, Ensembl identifiers, and versioned Ensembl identifiers are supported.

Do not place the following in adata.X:

log-transformed expression
normalized expression
scaled expression
batch-corrected expression
previously imputed data

The package validates both the count matrix and feature mapping before inference.

Available Outputs

Depending on the selected API, scUNVEIL can generate:

PCA-reduced cell embeddings
raw 2048-dimensional embeddings
measurement-enriched expression estimates
gene embeddings
autoregressively generated count vectors

Measurement-enriched expression is reported as

log10(predicted gene probability) + 6

which corresponds to log10(CPM). These values are model predictions, not raw counts or additional experimental observations.

Model

scUNVEIL is a dense residual multilayer perceptron containing

~60,000 input/output features
2048 hidden dimensions
7 residual blocks

Unlike transformer-based approaches, each cell is processed as a single count vector in one forward pass.

The model was pretrained on approximately 93 million human cells from the CELLxGENE Census release dated November 8, 2025. The dataset-level training inventory, including CELLxGENE dataset identifiers and source citations, is provided in Supplementary_Table_S1_training_datasets.csv.

Checkpoints

The package automatically downloads the recommended checkpoint from this repository during first use.

The current stable release is

models/2026-07-09_18-42-14_full

Users normally do not need to interact with checkpoint files directly.

Specific model versions can be loaded with

model = scUnveil(model_version="MODEL_VERSION")

For reproducible analyses, record the installed scunveil package version, the selected checkpoint version, and ideally the Hugging Face repository revision.

Limitations

scUNVEIL estimates the transcriptome expected under deeper sampling of the same effective measurement process.

It does not

recover an assay-independent biological ground truth,
remove all technical effects,
perform batch correction,
or provide definitive evidence that an unobserved transcript was present in an individual cell.

Additional considerations:

trained only on human data
performance may vary across tissues, protocols and rare biological states
very sparse cells contain limited cell-specific information
enriched expression should be interpreted as a model prediction rather than an experimental observation

Resources

Inference package: https://github.com/thonzyk/scunveil
PyPI: https://pypi.org/project/scunveil/
Training pipeline: https://github.com/thonzyk/scunveil-training
Experiments: https://github.com/thonzyk/scunveil-experiments

The manuscript will be linked here once publicly available.

Citation

If you use scUNVEIL in your work, please cite the accompanying publication once available.

Until then, please cite the software repository together with the specific model version used for your analyses.

License

Apache License 2.0

Downloads last month: -; Downloads are not tracked for this model. How to track