MATerial analysis of SPATially resolved histology images.
A Python package that applies physics-informed spatial analysis to single-cell histology data for binary disease classification. MatSpat treats cells as point particles and borrows techniques from materials science (freud, spatial correlation functions) to quantify how immune cells organize around tumors — then uses those spatial patterns to distinguish disease states.
- Characterize local tissue structure using freud (local density, bond order, neighbor composition)
- Measure how immune–tumor spatial correlation (Lee's L) changes across a tumor density gradient, producing per-image trajectories
- Control for tissue structure confounds using geographically weighted partial correlation (GWPCor)
- Classify disease by fitting class-dependent Hidden Markov Models to the spatial trajectories
| Module | Purpose |
|---|---|
preprocessing |
Load CSV data, standardize columns, ICA-based tissue rotation |
density |
Gaussian KDE on tumor cells, quantile-based spatial partitioning |
descriptors |
freud-based per-cell features: local density, k-atic order, neighbor counts |
interactions |
Lee's L correlation, GWPCor partial correlation, pairwise trajectory computation |
classification |
Sequence assembly, Gaussian HMM training, stratified evaluation with bootstrap CIs |
pip install -e ".[dev]"
mamba install -c conda-forge freud # freud must be installed via condaSee the tutorial notebook for a full pipeline walkthrough on built-in example data. For a real-data example using the Schürch et al. colorectal cancer CODEX dataset, see the real data pipeline notebook.
Any spatial point-pattern dataset with x/y coordinates, a type label, and an image/sample identifier. The primary use case is multiplexed tissue imaging (e.g., CODEX, mIF) but the methods generalize to any labeled 2D point cloud.
Per-image disease classification with confidence intervals, confusion matrices, and per-class log-likelihoods. Intermediate outputs (trajectories, descriptors, sequences) are all accessible as DataFrames for custom downstream analysis.
Copyright The Regents of the University of Michigan.
Released under the BSD 3-Clause License — see LICENSE.