cellwhisperer

CellWhisperer

CellWhisperer is a multimodal AI model combining transcriptomics with natural language to enable intuitive interaction with scRNA-seq datasets. CellWhisperer is published in Nature Biotechnology. The project website hosts the web tool with several example datasets as well as a short video tutorial. We also provide our model weights and curated datasets.

This repository contains detailed instructions on how to run your own CellWhisperer instance and import custom datasets, as well as the full source code, models, and training data.

Table of Contents

• Installation
• Analyze Your Own Datasets
• Folder Structure
• Reproducing Paper Analyses
• Citation and Contact

Pixi, very similarly to uv, provides a fast, reproducible setup with a single command.

1. Clone the repository with all submodules:

   git clone git@github.com:epigen/cellwhisperer.git --recurse-submodules
   cd cellwhisperer
   

2. Install:

   bash envs/setup_pixi.sh
   

All dependencies (including snakemake and cellxgene) are resolved automatically from pixi.toml. Use pixi run or pixi shell to execute commands in the environment.

Option B: Conda (Linux-only)

1. Clone the repository with all submodules (required):

   git clone git@github.com:epigen/cellwhisperer.git --recurse-submodules
   cd cellwhisperer
   

   If you've already cloned without submodules, retrieve them with:

   git submodule update --init --recursive
   

2. Set up the conda environments:

   ./envs/setup.sh
   

   This script creates the necessary conda environments including cellwhisperer (main environment) and llava (for the chat model).

3. Install snakemake (optional, for running paper analyses):

   conda install -c bioconda -n base snakemake=7
   

   Alternatively, snakemake is accessible within the cellwhisperer environment after activation.

4. Verify installation: Activate the environment and check that cellxgene is available:

   conda activate cellwhisperer
   cellxgene --version
   

Note on compilers: If you encounter build issues, you may need to install gcc and g++ (version 9.5 recommended). If installing via conda, be aware of potential compatibility issues with snakemake.

You're now ready to run CellWhisperer locally (see next section) or analyze your own datasets.

Option C: Docker (Best for deployment; Linux-only)

For users who prefer containerized environments, CellWhisperer can be installed and run using Docker. This approach includes all dependencies and installation steps in a self-contained environment.

1. Build the Docker image:

   docker build -t cellwhisperer .
   

2. Run the container:

   docker run --gpus all -it --volume .:/opt/cellwhisperer cellwhisperer bash
   # Also works without GPUs (omit --gpus all)
   

3. Activate the environment inside the container:

   conda activate cellwhisperer
   

Note on volumes: The command above mounts the project directory as a volume (--volume .:/opt/cellwhisperer) so that code modifications are visible inside the container. For processing datasets, consider also mounting resources and results directories:

docker run --gpus all -it \
  --volume .:/opt/cellwhisperer \
  --volume /path/to/resources:/opt/cellwhisperer/resources \
  --volume /path/to/results:/opt/cellwhisperer/results \
  cellwhisperer bash