A computational framework for modelling intrinsic and extrinsic factors driving cell plasticity using spatial transcriptomics data, graph neural networks (GNNs) and geostatistical regression.
SPiCe formalizes state predictability as a quantitative proxy for plasticity: stable cell states are predictable from their spatial neighborhood, while plastic states are not.
Original implementation:Eloise Withnell (scripts).
Package conversion:Cenk Celik restructured the codebase into an installable Python package.
git clone https://github.com/secrierlab/SPiCe.git
cd SPiCe && pip install -e .SPiCe follows the scverse convention: tools live under spice.tl, plotting under spice.pl. All tool functions modify adata in place.
importspice# 1. Discretise the continuous state scorespice.tl.assign_state_labels(
adata,
score_key="EMT_score",
n_states=4, # or 2 for binary classificationtumour_mask_key="tumour_cells", # only label tumour cells
)
# 2. Build the spatial k-NN graph (stored in adata.uns['spice'])spice.tl.build_graph(
adata,
spatial_key="spatial",
n_neighbors=12,
celltype_key="cell_type",
)
# 3. Cross-validatespice.tl.cross_validate(
adata,
feature_mode="celltype", # "intrinsic" or "combined"num_folds=5,
num_epochs=500,
)
# 4. Evaluate and plotspice.tl.evaluate(adata)
spice.pl.auc_per_class(adata, state_map={0: "EPI", 1: "H-EPI", 2: "H-MES", 3: "MES"})
# 5. Explain and plotspice.tl.explain_nodes(adata, n_explanations=50)
spice.pl.node_importance(adata, state_map={0: "EPI", 1: "H-EPI", 2: "H-MES", 3: "MES"})
spice.tl.explain_edges(adata, n_explanations=50)
spice.pl.edge_network(adata, state_map={0: "EPI", 1: "MES"})
# 6. Baseline comparisonspice.tl.run_baseline(adata)
spice.pl.baseline(adata)
# 7. Save adataspice.tl.sanitize(adata)
adata.write_h5ad(adata, "adata.h5ad")All results are written to adata.uns['spice']:
| Key | Written by | Content |
|---|---|---|
graph | tl.build_graph | NetworkX spatial k-NN graph |
label_binarizer | tl.build_graph | Fitted LabelBinarizer for cell types |
params | tl.build_graph | Dict of run parameters |
folds | tl.cross_validate | List of PyG Data objects |
cv_results | tl.cross_validate | Predictions, models, fold performances |
auc | tl.evaluate | Classification AUC DataFrame |
regression | tl.evaluate | Regression R²/correlation DataFrame |
node_attributions | tl.explain_nodes | IG attributions per label |
node_pvalues | tl.explain_nodes | Mann-Whitney p-values (label × feature) |
edge_explanations | tl.explain_edges | Edge importance per label |
baseline | tl.run_baseline | Summary DataFrame + per-fold results |
| Mode | Features | Use case |
|---|---|---|
"celltype" | One-hot cell type | TME influence on state (default) |
"intrinsic" | PCA of gene expression / CNAs | Intrinsic genomic drivers |
"combined" | PCA + cell type | Joint intrinsic + extrinsic modelling |
If you use SPiCe in your research, please cite:
Withnell E, Celik C, Secrier M. Integrative Spatial Modelling of Cellular Plasticity using Graph Neural Networks and Geostatistics. bioRxiv (2025). https://doi.org/10.1101/2025.09.24.678189
See tutorial.md for a step-by-step guide covering the full pipeline, feature modes, explanations and plotting. spice_example.ipynb has a tutorial with an example adata file to replicate the analysis.
GPL-3.0. See LICENSE for details.