ESPACE — spatial proteomics analysis

Companion code for

'A single-cell multi-omic atlas of the human pancreas reveals latent plasticity across development, health, and disease' bioRxiv preprint 2025.10.03, PMC12622017 with the title 'Latent plasticity of the human pancreas across development, health, and disease' [Add full citation and DOI on publication when available]

This repository contains the multiplexed-imaging (CODEX / IMC) analysis code used to generate the spatial-proteomics figures in the manuscript. The single-cell transcriptomics and ATAC components of the ESPACE atlas are in separate repositories maintained by the respective groups; see the manuscript for links.

Repository layout

ESPACE-spatial-proteomics/
├── README.md                  # this file
├── environment.yml            # conda environment (recommended)
├── requirements.txt           # pip alternative
├── pyproject.toml             # makes `espace` pip-installable
├── .gitignore
├── .pre-commit-config.yaml
├── LICENSE
├── R/                         # preprocessing scripts (filter, ComBat, QN)
├── src/
│   └── espace/                # importable Python package
│       ├── barplot.py         # stacked bar plots
│       ├── dotplot.py         # marker expression dot plot
│       ├── io.py              # CSV loading and filtering helpers
│       ├── kmeans.py          # per-batch K-means clustering
│       ├── otsu.py            # Otsu thresholding per donor
│       ├── sankey.py          # Sankey diagrams
│       └── spatial.py         # Euclidean-distance bubble heatmaps
├── tests/                     # pytest test suite
├── notebooks/                 # figure-producing drivers
├── data/                      # not committed; see data/README.md
└── figures/                   # outputs; gitignored

Installation

Python pipeline:

git clone https://github.com/<your-org>/ESPACE-spatial-proteomics.git
cd ESPACE-spatial-proteomics

# Conda (recommended)
conda env create -f environment.yml
conda activate espace
pip install -e .

# Or pip-only
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt && pip install -e .

# Optional: strip notebook outputs automatically on commit
pre-commit install

To verify:

pytest tests/ -v

R preprocessing (only needed to re-run the upstream filtering / batch correction / quantile normalisation steps): see R/README.md for package requirements.

Data

The raw multiplexed-imaging data and cell-level expression tables are deposited at [Zenodo / BioImage Archive — DOI to be added on publication]. Place the downloaded files in data/ and the notebooks will find them. See data/README.md for expected filenames.

Reproducing the manuscript figures

#	Step	Script	Language
01	Data filtration and log-transformation	R/01_data_filtration_and_transformation.R	R
02	ComBat batch correction	R/02_batch_correction.R	R
03	Quantile normalisation	R/03_quantile_normalization.R	R
04	Per-TMA / core / case / region filtering	notebooks/01_data_filtering.ipynb	Python
05	Per-donor Otsu thresholds	notebooks/02_otsu_thresholding.ipynb	Python
06	Per-batch K-means clustering	notebooks/03_kmeans_clustering.ipynb	Python
07	Stacked bar plots	notebooks/04_stacked_barplots.ipynb	Python
08	Euclidean-distance bubble heatmaps	notebooks/05_spatial_distances.ipynb	Python
09	Marker expression dot plot	notebooks/06_dotplot.ipynb	Python
10	Sankey diagrams	notebooks/07_sankey.ipynb	Python
11	Cluster correlation heatmap	notebooks/08_correlation_heatmap.ipynb	Python

Citation

If you use this code, please cite the manuscript (citation block to be added on publication) and, optionally, this repository:

ESPACE multiplexed-imaging analysis pipeline. v0.1.0.
GitHub: <repo URL>

License

MIT (see LICENSE).

Contact

Mariya Mardamshina, Lundberg lab, Stanford ([email]).