Metadata-Version: 2.4
Name: azizilab-sherlock
Version: 0.1.0
Summary: SHERLOCK: structured representation learning and causal inference of downstream perturbation effects in single-cell data
Author: Mingxuan Zhang, Joshua D. Myers, Lingting Shi, Azizi Lab
License-Expression: CC-BY-NC-ND-4.0
Project-URL: Homepage, https://github.com/azizilab/SHERLOCK
Project-URL: Documentation, https://azizilabsherlock.readthedocs.io
Project-URL: Source, https://github.com/azizilab/SHERLOCK
Project-URL: Reproducibility, https://github.com/azizilab/SHERLOCK_Reproducibility
Keywords: single-cell,perturbation,Perturb-seq,causal inference,variational autoencoder
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.1
Requires-Dist: pyro-ppl>=1.9
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Requires-Dist: anndata>=0.10
Requires-Dist: scanpy>=1.10
Requires-Dist: statsmodels>=0.14
Requires-Dist: matplotlib>=3.7
Requires-Dist: seaborn>=0.13
Requires-Dist: networkx>=3.0
Requires-Dist: dcor>=0.6
Requires-Dist: tqdm>=4.65
Provides-Extra: benchmarks
Requires-Dist: scvi-tools>=1.1; extra == "benchmarks"
Requires-Dist: cell-gears>=0.1.2; extra == "benchmarks"
Provides-Extra: tutorials
Requires-Dist: leidenalg>=0.10; extra == "tutorials"
Requires-Dist: umap-learn>=0.5; extra == "tutorials"
Requires-Dist: gseapy>=1.1; extra == "tutorials"
Requires-Dist: jupyterlab; extra == "tutorials"
Requires-Dist: ipykernel; extra == "tutorials"
Provides-Extra: docs
Requires-Dist: sphinx<8,>=7; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: ipython; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: all
Requires-Dist: azizilab-sherlock[benchmarks,test,tutorials]; extra == "all"
Dynamic: license-file

# SHERLOCK: structured representation learning and causal inference of downstream perturbation effects

[![Documentation Status](https://readthedocs.org/projects/azizilabsherlock/badge/?version=latest)](https://azizilabsherlock.readthedocs.io/en/latest/)

SHERLOCK (Single-cell Hierarchical Embedding of peRturbations and Learning Of Causal Knowledge) is
an interpretable deep generative framework for single-cell perturbation data. It models each
genetic or chemical perturbation as a structured intervention on a latent baseline cell state,
with perturbation effects that are correlated across perturbations and sparse across latent
factors. From the fitted model you can

- **group perturbations** by the transcriptional responses they share,
- **estimate downstream effects counterfactually**, by applying a perturbation to control cells'
  inferred baseline states and decoding the result,
- **measure how responses depend on a condition** such as drug exposure or T-cell co-culture, and
- **compose single perturbations** to predict combinations, including unseen ones, and classify
  genetic interactions.

📖 **Documentation:** https://azizilabsherlock.readthedocs.io

## Installation

SHERLOCK requires Python ≥ 3.10 and is published on PyPI as `azizilab-sherlock`; the package is
imported as `sherlock`.

```bash
pip install azizilab-sherlock
```

Optional extras:

| Extra | Adds |
|---|---|
| `tutorials` | Leiden clustering, UMAP, gene-set enrichment (`gseapy`) and Jupyter, used by the tutorials |
| `benchmarks` | the baseline models: cVAE, sVAE+, contrastiveVI and scGen (`scvi-tools`), and GEARS (`cell-gears`) |
| `all` | `tutorials`, `benchmarks` and `test` |

```bash
pip install "azizilab-sherlock[tutorials]"
```

To install from source, or with conda:

```bash
git clone https://github.com/azizilab/SHERLOCK.git
cd SHERLOCK
pip install -e ".[tutorials]"          # or: conda env create -f environment.yml
```

Install PyTorch first if you need a specific CUDA build ([pytorch.org](https://pytorch.org/get-started/locally/)).
See the [installation guide](https://azizilabsherlock.readthedocs.io/en/latest/installation.html)
for details.

## Quickstart

```python
import scanpy as sc
import torch
import sherlock as slk

# Raw counts in .X; one perturbation label per cell, controls labelled e.g. "non-targeting"
adata = sc.read_h5ad("my_screen.h5ad")
slk.pp.slk_prepare_data(adata, pert_key="guide_target", ntc_label="non-targeting", inplace=True)

# Observed average treatment effects, used for validation during training
slk.pp.treat_effect(adata, label_col="pert", control_label="NTC", method="perturbseq", inplace=True)

# Train and evaluate
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
out = slk.tl.run(adata, model="vae", latent_dim=16, device=device)
model = out["model"]
slk.tl.eval(model, adata, device=device)       # writes adata.obsm["z"] and adata.uns["results"]

# Perturbation groups and counterfactual downstream effects
slk.pl.plot_corr(adata)
cf = model.predict_counterfactual_effects(adata, observed_effect=adata.uns["treat_effect"])
slk.tl.ev_sig(adata)
slk.pl.plot_ev_sig(adata)

slk.tl.save_results(out, "sherlock_model.pth")
```

For screens with conditions, also pass `treatment_key` and `untreated_label` to
`slk_prepare_data` and train with `use_conditions=True`. For combinations (`A+B` labels), train
with `combinatorial=True, synergy=True`. See the
[API reference](https://azizilabsherlock.readthedocs.io/en/latest/api/index.html).

## Tutorials

| Design | Tutorial | Data |
|---|---|---|
| One perturbation per cell | [Single perturbations](https://azizilabsherlock.readthedocs.io/en/latest/tutorials/single_perturbations.html) | genome-scale CRISPRi Perturb-seq, K562 (Replogle et al. 2022) |
| One perturbation per cell, under several conditions | [Single perturbations across conditions](https://azizilabsherlock.readthedocs.io/en/latest/tutorials/conditional_perturbations.html) | 11 kinase inhibitors in BT333 glioblastoma cells with and without cytotoxic T cells, sci-Plex (Shi et al. 2026) |
| One or two perturbations per cell | [Combinatorial perturbations](https://azizilabsherlock.readthedocs.io/en/latest/tutorials/combinatorial_perturbations.html) | combinatorial CRISPRa Perturb-seq, K562 (Norman et al. 2019) |

The tutorial notebooks are in [`docs/tutorials/`](docs/tutorials).

## Datasets

The processed Replogle and Norman datasets are downloaded on first use:

```python
adata = slk.datasets.replogle()   # ~570 MB
adata = slk.datasets.norman()     # ~1.7 GB
```

Files are stored in `$SHERLOCK_DATA_DIR` (default `~/.cache/sherlock`); pass `path=` to read a
local copy instead. The processed versions of the other datasets analysed in the manuscript
(Perturb-RAEFISH, EGFR inhibitor screen, glioblastoma kinome and kinase-inhibitor screens) are
available from the first authors on request.

## Repository structure

The repository root is the `sherlock` package:

```
├── __init__.py, _configs.py
├── tools/           # models, training, evaluation, clustering, interaction scoring (slk.tl)
├── preprocessing/   # label preparation and observed treatment effects (slk.pp)
├── plotting/        # plots (slk.pl)
├── datasets/        # dataset loaders (slk.datasets); downloaded data is not tracked
├── notebooks/       # analysis notebooks for every dataset in the manuscript
│   ├── replogle_analysis.ipynb, benchmarking.ipynb
│   ├── raefish/     # spatial CRISPR screen
│   ├── gbm/         # glioblastoma: EGFR inhibitors, kinome CRISPRi/a, 11 drugs ± T cells
│   └── norman/      # combinatorial CRISPRa screen
├── docs/            # documentation source: guides, API reference, tutorials
├── tests/           # unit tests
├── pyproject.toml   # packaging (pip install)
└── environment.yml  # conda environment
```

The notebooks import the installed package, so run `pip install -e .` in the repository root
before opening them. They read their inputs from `datasets/`. A version organized by figure,
with instructions for obtaining the data and saved models, is in
[azizilab/SHERLOCK_Reproducibility](https://github.com/azizilab/SHERLOCK_Reproducibility).

## Citation

If you use SHERLOCK, please cite our preprint:
https://www.biorxiv.org/content/10.64898/2026.09.25.754573v1

_SHERLOCK: Structured representation learning and causal inference of downstream perturbation effects_

```bibtex
@article{zhang2026sherlock,
  title   = {SHERLOCK: Structured representation learning and causal inference of downstream perturbation effects},
  author  = {Zhang, Mingxuan and Myers, Joshua D. and Shi, Lingting and Giglio, Ross M. and
             Chatterjee, Sharanya and McFaline-Figueroa, Jos{\'e} L. and Azizi, Elham},
  journal = {bioRxiv},
  year    = {2026},
  doi     = {10.64898/2026.09.25.754573}
}
```

## License

This work is licensed under a [Creative Commons Attribution-NonCommercial-NoDerivatives 4.0
International License](LICENSE).
