Metadata-Version: 2.4
Name: sceps
Version: 0.2.1
Summary: Integrate GWAS and single-cell disease cell atlas data to identify disease-associated cell neighborhoods
Author: Genentech, Inc.
License-Expression: MIT
Project-URL: Homepage, https://github.com/Genentech/sceps
Project-URL: Documentation, https://github.com/Genentech/sceps/wiki
Project-URL: Repository, https://github.com/Genentech/sceps
Project-URL: Issues, https://github.com/Genentech/sceps/issues
Keywords: single-cell,GWAS,genetics,transcriptomics,scRNA-seq
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.23
Requires-Dist: pandas<3,>=1.5
Requires-Dist: scipy<2,>=1.9
Requires-Dist: anndata<1,>=0.10
Requires-Dist: scanpy<2,>=1.10
Requires-Dist: scikit-learn<2,>=1.1
Requires-Dist: statsmodels<1,>=0.13
Requires-Dist: tqdm>=4.60
Requires-Dist: packaging>=20
Requires-Dist: matplotlib>=3.6
Requires-Dist: seaborn>=0.12
Provides-Extra: preprocess
Requires-Dist: harmonypy>=0.0.9; extra == "preprocess"
Dynamic: license-file

# 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:

![scEPS illustration](https://raw.githubusercontent.com/Genentech/sceps/master/img/scEPS_overview.png  "Overview of the scEPS method")

# Reference

The current draft of the manuscript is available [here](https://www.medrxiv.org/content/10.64898/2026.06.26.26356714v1). The code we used to create the figures in the manuscript is available [here](https://github.com/Genentech/sceps_manuscript). We also implemented [CNA*](https://github.com/Genentech/cna_star), a simple extension of [CNA](https://github.com/immunogenomics/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](https://scepsresultexplorer.streamlit.app/).

# Manual
We provide a detailed manual of scEPS in the [Wiki page](https://github.com/Genentech/sceps/wiki).

# Installation

scEPS requires Python 3.9 or newer and is available on [PyPI](https://pypi.org/project/sceps/):
```shell
pip install sceps
```

This installs the `sceps` Python package along with the command-line tools described under [Usage](#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](https://github.com/conda-forge/miniforge) environment:
```shell
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:
```shell
git clone git@github.com:Genentech/sceps.git
cd sceps
pip install -e .
```

The optional preprocessing helper script `misc/preprocess_scdata.py` additionally requires [harmonypy](https://github.com/slowkow/harmonypy) for batch integration. This is available as an extra:
```shell
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.

```shell
git clone git@github.com: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](https://www.python.org/) | 3.9.18 |
| [numpy](https://numpy.org/) | 1.26.2 |
| [pandas](https://pandas.pydata.org/) | 1.5.3 |
| [scipy](https://scipy.org/) | 1.13.1 |
| [anndata](https://anndata.readthedocs.io/) | 0.10.7 |
| [scanpy](https://scanpy.readthedocs.io/) | 1.10.3 |
| [scikit-learn](https://scikit-learn.org/) | 1.3.2 |
| [statsmodels](https://www.statsmodels.org/) | 0.14.5 |
| [tqdm](https://tqdm.github.io/) | 4.67.1 |
| [packaging](https://packaging.pypa.io/) | 25.0 |
| [matplotlib](https://matplotlib.org/) | 3.9.4 |
| [seaborn](https://seaborn.pydata.org/) | 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](https://github.com/Genentech/sceps/wiki).

scEPS can also be driven from Python rather than the command line:
```python
from sceps.sceps_core import *
```
See [misc/run_sceps_from_python.py](https://github.com/Genentech/sceps/blob/master/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:

```shell
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:

```shell
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](https://github.com/Genentech/sceps/tree/master/test).

# Contact

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