HyperCell

A deep learning model for recovering undersampled single-cell RNA-seq data.

Overview

HyperCell recovers clean transcriptomic profiles from noisy, undersampled scRNA-seq count data by:

• Using a hypergeometric likelihood that respects the discrete nature of RNA counts
• Enforcing the constraint that predicted counts ≥ observed counts via constrained optimization
• Learning interpretable latent representations of cells
• Optionally modeling background RNA to separate technical noise from biological signal

Installation

Requires Python 3.10+ and uv.

# Clone the repository
git clone https://github.com/lhdgsn/HyperCell.git
cd HyperCell

# Create virtual environment and install dependencies
uv sync

# For GPU support (highly recommended), install PyTorch with CUDA separately
# See https://pytorch.org/get-started/locally/ for your platform

Quick Start

1. Prepare your data

HyperCell expects scRNA-seq data in .h5ad cell x gene format (AnnData). The count matrix should contain raw integer UMI counts.

2. Configure your experiment

Edit src/config/experiments.yaml to add your dataset:

my_experiment:
  local_path: "path/to/your/data.h5ad"
  marker_genes: ["GENE1", "GENE2"]
  cluster_col: "celltype"

3. Train the model

cd src
uv run python train_hypercell.py --experiment my_experiment --wandb_project my_project

Key arguments:

• --experiment: Name of experiment defined in experiments.yaml
• --n_cells: Number of cells to use (default: 1e6)
• --n_genes: Number of genes to keep (default: 12000, or "auto")
• --max_epoch: Maximum training epochs (default: 1000)
• --batch_size: Batch size (default: 128)

4. Use the API directly

from HyperCell import HyperCell

# Initialize with a parameter file
hypercell = HyperCell("config/params.json")

# Load data
hypercell.load_data("path/to/counts.h5ad")

# Add marker genes to monitor
hypercell.add_marker_genes(["CD4", "CD8B", "MS4A1"])

# Train
hypercell.train_hypercell(save_dir="checkpoints/")

# Get denoised counts and latent embeddings
adata_denoised = hypercell.get_hypercounts()

Project Structure

HyperCell/
├── src/
│   ├── HyperCell.py          # Main API class
│   ├── VAE.py                # Encoder-decoder neural network
│   ├── hyperutils.py         # Loss functions and constrained optimization
│   ├── sparse_dataset.py     # PyTorch dataset for sparse matrices
│   ├── train_hypercell.py    # Training script
│   └── config/
│       ├── default_config.yaml   # Default hyperparameters
│       └── experiments.yaml      # Dataset configurations
├── analyses/                 # Evaluation notebooks
├── notebooks/                # Example notebooks
└── pyproject.toml

Output

After training, HyperCell produces an estimated denoised AnnData object with:

• Denoised count matrix: Recovered transcriptome estimates (in .X)
• Latent embeddings: Low-dimensional cell representations (in .obsm["latent_embedding"])
• Background estimates: Per-gene background RNA levels (in .var["background"])

Requirements

• Python ≥3.10
• PyTorch ≥2.0
• CUDA-capable GPU (recommended)

License

MIT