expression-copilot 0.2.1

ADDME

Expression Copilot

Installation • Documentation • Citation • FAQ • Acknowledgement

We introduce two metrics: EPS (Expression Predictability Score) and SPS (Slice Predictability Score), to quantify the predictability of gene expression from histology image. Python package expression_copilot is developed to calculate these metrics efficiently. It also provides several baseline models to predict gene expression from image embeddings, such as MLP.

Installation

PyPI

[!IMPORTANT] Requires Python >= 3.10

We recommend to install expression_copilot to a new conda environment:

mamba create -n expression_copilot -c conda-forge python=3.11 -y && conda activate expression_copilot
pip install expression_copilot

(Optional) If you have CUDA-enabled GPU, you could install cuml&cupy to accelerate KNN building, and install torch to accelerate MLP baseline training:

mamba create -n expression_copilot_cuda -c conda-forge -c rapidsai -c nvidia python=3.11 rapids=25.06 'cuda-version>=12.0,<=12.8' -y && conda activate expression_copilot_cuda
pip install expression_copilot[torch]

Docker

You could pull and use our docker image directly:

docker pull huhansan666666/expression_copilot:latest

# GPU version
docker run --gpus all -it --rm huhansan666666/expression_copilot:latest

# CPU version
docker run -it --rm huhansan666666/expression_copilot:latest

Documentation

Quick Start

The following code snippet shows how to calculate EPS and SPS using expression_copilot. We assume you have already preprocessed your spatial transcriptomics data into an AnnData object (adata), where adata.X stores raw counts and adata.obsm['KEY_NAME'] stores image embeddings of spots.

import scanpy as sc
import numpy as np
from expression_copilot import ExpressionCopilotModel

# Read data
# adata.X is expected to be raw counts
# adata.obsm['KEY_NAME'] is expected to store image embeddings of spots
adata = sc.read_h5ad('path/to/adata')

model = ExpressionCopilotModel(adata, image_key = 'KEY_NAME')

# Calculate EPS and SPS
eps = model.calc_metrics_per_gene()
sps = eps.mean()

# Run baseline models (method could be 'ridge', 'linear', 'ensemble', 'mlp')
baseline_metrics_per_gene, _ = model.calc_baseline_metrics(method = 'mlp')

Notebooks

We provide several tutorials in the resource/tutorials folder. You could also run them in Google Colab directly:

Name	Description	Colab
Basic Tutorial	Basic tutorial of calculating EPS
Advanced Tutorial	Start with 10x spatial-ranger output from scratch
Multi-omics Tutorial	Calculating EPS and SPS on single cell multi-omics data

Citation

In coming.

If you want to repeat results in the manuscript, please check the experiments folder.

FAQ

Please open a new github issue if you have any question.

1. numba related bugs

We use numba to increase the speed (up to 12x). However, it may have compatibility issues with different python/numpy versions. We tested the latest version of numba (0.6.12) and it works fine with Python 3.11/3.12, numpy 1.26.

Acknowledgement

We thank the following great open-source projects for their help or inspiration:

• HEST
• UNI
• entropy_estimators