scEPS

scEPS (single-cell Expression exPlainability Statistics)

This repo contains the code of the method, scEPS, for integrating GWAS and single-cell disease cell atlas data to identify disease-associated cell neighborhoods. scEPS calculates a $d$ statistic at each cell neighborhood, representing the difference between the variance in disease explained by variations in the expression of each GWAS vs. each mean-expression matched control gene. An illustration of the scEPS method is shown below:

Reference

The current draft of the manuscript is available here. The code we used to create the figures in the manuscript is available here. We also implemented CNA*, a simple extension of CNA, for estimating the variance in disease attributable to variations in cell abundance at each cell neighborhood.

We also provide a web UI for visualizing the results in the scEPS manuscript here.

Manual

We provide a detailed manual of scEPS in the Wiki page.

Installation

scEPS requires Python 3.9 or newer and is available on PyPI:

pip install sceps

This installs the sceps Python package along with the command-line tools described under Usage. The required dependencies, including scanpy, anndata, numpy, pandas, scipy, scikit-learn and statsmodels, are resolved automatically; the supported version ranges are declared in pyproject.toml.

To keep scEPS in a dedicated conda environment:

conda create -n sceps python=3.11
conda activate sceps
pip install sceps

To install from a checkout instead, for example to modify the scEPS source:

git clone [email protected]:Genentech/sceps.git
cd sceps
pip install -e .

The optional preprocessing helper script misc/preprocess_scdata.py additionally requires harmonypy for batch integration. This is available as an extra:

pip install "sceps[preprocess]"

Reproducing the manuscript environment

The sceps.yml file pins the exact dependency versions used for the analyses in the manuscript. This is only needed to reproduce those results; for ordinary use, pip install sceps above is sufficient.

git clone [email protected]:Genentech/sceps.git
cd sceps
conda env create -f sceps.yml
conda activate sceps
pip install --no-deps .

The --no-deps flag leaves the versions resolved by conda untouched, so the environment matches the pins exactly.

Package	Version used
python	3.9.18
numpy	1.26.2
pandas	1.5.3
scipy	1.13.1
anndata	0.10.7
scanpy	1.10.3
scikit-learn	1.3.2
statsmodels	0.14.5
tqdm	4.67.1
packaging	25.0
matplotlib	3.9.4
seaborn	0.13.2

scEPS is not restricted to these versions. It has also been verified to produce identical output on numpy 2.x, pandas 2.x, anndata 0.12 and scanpy 1.11.

Usage

Installing scEPS provides the following command-line tools. The first four correspond to the four steps of the scEPS workflow:

Command	Purpose
sceps	Estimate scEPS statistics for individual cell neighborhoods
sceps-cluster-neighborhood	Define approximately independent cell neighborhood blocks
sceps-aggregate	Aggregate scEPS statistics across cell types and across all cells
sceps-corr	Correlate scEPS statistics with gene expression
sceps-generate-test-data	Simulate a small test data set for trying out the workflow

Pass --help to any of them for the full list of options, e.g. sceps --help. A detailed description of each step is available in the Wiki page.

scEPS can also be driven from Python rather than the command line:

from sceps.sceps_core import *

See misc/run_sceps_from_python.py for a worked example.

Testing scEPS

The sceps-generate-test-data command simulates a small data set so that the whole workflow can be exercised from a plain pip install, without cloning this repository:

sceps-generate-test-data

This writes test_scdata.h5ad (600 cells of 10 cell types across 20,000 genes for 30 donors) and test_magma.txt into ./input. The four workflow steps can then be run against it:

sceps --adata ./input/test_scdata.h5ad --donor-id-col Donor \
    --gene-list ./input/test_magma.txt --auto-gene-selection \
    --pheno Pheno --scale-pheno --scale-pheno-neighborhood --out ./output/step1
sceps-cluster-neighborhood --adata ./input/test_scdata.h5ad --donor-id-col Donor \
    --neighbors-use-rep X_pca --out ./output/step2
sceps-aggregate --prefix "./output/step1.*.txt.gz" --adata ./input/test_scdata.h5ad \
    --neighborhood-clusters ./output/step2.txt.gz --cell-type-col CellType --out ./output/step3
sceps-corr --adata ./input/test_scdata.h5ad --sceps-result ./output/step3.sceps.omega.txt.gz \
    --min-num-nonzero 3 --out ./output/step4

Create the ./output directory first. The first step analyzes every cell neighborhood in turn and takes a few minutes on the simulated data; add --start-idx 0 --stop-idx 40 to run a subset instead.

Because the simulated expression values and phenotypes are drawn independently, no cell neighborhood is expected to show a genuine disease association. The purpose of the test data is to confirm that the workflow runs end to end and to illustrate the format of each output file.

The equivalent shell scripts, together with reference output files to compare against, are also provided here.

Contact

Please create a GitHub issue if you experience any issue with running scEPS.