virtual-cell-tutorial

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

virtual-cell-tutorial

★ 25 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Virtual Cell

A minimal **virtual cell** built in Python - the companion code for the YouTube tutorial
**["How to Build a Virtual Cell in Python from Scratch."](https://youtu.be/FuMPJQbLVEk)**

▶️ **Watch the tutorial:** https://youtu.be/FuMPJQbLVEk

A *virtual cell* is a program that answers the question: **"What happens to a cell under a given perturbation?"**
Here, "what happens" means a change in **gene expression**, and a "perturbation" is a gene knockdown.
The model takes an embedding of the perturbed gene, predicts how expression changes, and adds that change
to the control cell state.

> ⚠️ This is an **educational** project. It illustrates the main steps of building a virtual cell - it is
> *not* a competitive perturbation-response model. The point is to understand the ideas and have a base to
> play with and improve.

## How it works

The model is simple:

```
gene embedding ──► neural net ──► predicted Δ expression
                                            │
control expression ──────────────────────► (+) ──────────────────────► predicted expression
```

Key ideas covered in the tutorial and implemented here:

- Single-cell RNA-seq perturbation data
- Representing perturbations with ESM2 gene embeddings
- Splitting data by perturbations
- Restricting to highly variable genes and using pseudobulk expression for a stable signal
- Predicting the delta from control
- Comparing against a simple baseline

## Project structure

```
src/
  ml/
    VirtualCell.py          # the model (a small delta-predicting MLP)
    PerturbationDataset.py  # PyTorch dataset
    utils.py                # gene embeddings + pseudobulk helpers
    eval.py                 # loss, baseline metrics, Pearson delta correlation
  scripts/
    download_data.py        # fetch training/validation data from GCS
    train.py                # training loop (saves checkpoints to models/)
    app.py                  # Streamlit app to explore predictions
  notebooks/
    playground.ipynb        # exploration
data/                       # data + embeddings (gitignored)
models/                     # saved checkpoints (gitignored)
```

## Setup

Requires Python 3.11+.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .          # makes the `ml` package importable
```

## Usage

All commands are run from the repository root.

**1. Download the data**

```bash
python src/scripts/download_data.py
```

This pulls the Virtual Cell Challenge training and validation `.h5ad` files into `data/`.
You also need the ESM2 gene embeddings in `data/ESM2/` (`ESM2_emb.csv` and `ESM2_genelist.txt`) -
see the resources below.

**2. Train the model**

```bash
python src/scripts/train.py
```

Checkpoints (model config + weights + the list of highly variable genes) are written to `models/`
as `model_<timestamp>.pth`, keeping the best validation loss.

**3. Explore predictions**

```bash
streamlit run src/scripts/app.py
```

Pick a perturbation gene and see the top predicted expression changes.

> Note: `app.py` loads a specific checkpoint filename. After training your own model, update the
> `torch.load(...)` path in [src/scripts/app.py](src/scripts/app.py) to point at your checkpoint.

## Resources

- Arc Institute Virtual Cell Atlas: https://arcinstitute.org/tools/virtualcellatlas
- Virtual Cell Challenge dataset: https://github.com/ArcInstitute/arc-virtual-cell-atlas/tree/main/virtual-cell-challenge
- Gene embeddings (benchmark paper + downloads): https://www.biorxiv.org/content/10.1101/2025.01.29.635607
- CELLxGENE: https://cellxgene.cziscience.com/

## License

For educational use. Feel free to fork, play around, and improve.

virtual-cell-tutorial

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README