expression-copilot 0.2.0

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 easily and efficiently. It also provides several baseline models to predict gene expression from image embeddings.

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
docker run --gpus all -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 spatial data and histological image 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