Metadata-Version: 2.5
Name: mantpy
Version: 1.2.0
Summary: A framework for extracellular matrix analysis in spatial proteomics
Project-URL: Documentation, https://mantpy.readthedocs.io/
Project-URL: Homepage, https://github.com/moeghaf/Mantpy
Project-URL: Issues, https://github.com/moeghaf/Mantpy/issues
Project-URL: Preprint, https://doi.org/10.1101/2025.06.04.657781
Project-URL: Source, https://github.com/moeghaf/Mantpy
Author: Mohamed Ghafoor
Maintainer-email: Mohamed Ghafoor <moeghaf@gmail.com>
License: MIT License
        
        Copyright (c) 2026, Mohamed Ghafoor
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: AnnData,extracellular matrix,graph,scverse,spatial proteomics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Requires-Dist: anndata>=0.12
Requires-Dist: dask[array]>=2024.10
Requires-Dist: igraph>=0.10
Requires-Dist: joblib>=1.3
Requires-Dist: leidenalg>=0.10
Requires-Dist: matplotlib>=3.8
Requires-Dist: networkx>=3.2
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.1
Requires-Dist: pillow>=10
Requires-Dist: pooch>=1.8
Requires-Dist: requests>=2.28
Requires-Dist: scanpy<1.13,>=1.10
Requires-Dist: scikit-image>=0.21
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.11
Requires-Dist: seaborn>=0.13
Requires-Dist: squidpy<1.9,>=1.8.2
Requires-Dist: tifffile[zarr]<2026.4.11,>=2025.5.21; python_version < '3.12'
Requires-Dist: tifffile[zarr]>=2026.5.2; python_version >= '3.12'
Requires-Dist: tqdm>=4.66
Requires-Dist: zarr<3.2,>=3.1; python_version < '3.12'
Provides-Extra: gnn
Requires-Dist: captum>=0.7; extra == 'gnn'
Requires-Dist: torch-geometric>=2.5; extra == 'gnn'
Requires-Dist: torch>=2.3; extra == 'gnn'
Provides-Extra: patch
Requires-Dist: pytorch-lightning>=2.2; extra == 'patch'
Requires-Dist: torch>=2.3; extra == 'patch'
Provides-Extra: segment
Requires-Dist: cellpose>=4; extra == 'segment'
Provides-Extra: spatial
Requires-Dist: spatialdata>=0.1; extra == 'spatial'
Provides-Extra: topology
Requires-Dist: gudhi>=3.13; extra == 'topology'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/moeghaf/Mantpy/main/docs/_static/mantpy_logo.png" alt="mantpy" width="320"/>
</p>

# Mantpy: extracellular-matrix analysis for spatial proteomics

[![PyPI][badge-pypi]][pypi]
[![Tests][badge-tests]][tests]
[![Documentation][badge-docs]][documentation]
[![Preprint][badge-preprint]][preprint]

[badge-pypi]: https://img.shields.io/pypi/v/mantpy
[badge-tests]: https://img.shields.io/github/actions/workflow/status/moeghaf/Mantpy/test.yaml?branch=main
[badge-docs]: https://img.shields.io/readthedocs/mantpy
[badge-preprint]: https://img.shields.io/badge/bioRxiv-10.1101%2F2025.06.04.657781-b31b1b

Mantpy is a scverse-based framework for graph analysis of the extracellular
matrix (ECM) in spatial proteomics. It represents cells and ECM patches as distinct,
linked node types, so matrix structure can be analysed on its own or together
with cellular context. Mantpy works with `AnnData` and interoperates with
Scanpy, Squidpy, and other single-cell and spatial tools.

- **2026:** Accepted poster presentation, ML4SpatialBio workshop at NeurIPS.
- **2026:** Flash talk, scverse conference.
- **2025:** Top Poster Award, British Society for Matrix Biology conference.

<p align="center">
  <img src="https://raw.githubusercontent.com/moeghaf/Mantpy/main/docs/_static/mantpy_overview.png" alt="Mantpy overview (manuscript Fig. 1): input, graph construction, applications and interoperability" width="820"/>
</p>

## Installation

Mantpy requires Python 3.11 or newer. CPU workflows run on Windows, Linux and
macOS. GPU training additionally requires a compatible PyTorch installation;
the package does not require a GPU for graph construction or descriptive analysis.

```bash
pip install mantpy
```

The current release is 1.2.0 ([PyPI][pypi], [GitHub release v1.2.0][release]);
the [changelog][] lists what changed between releases.

Optional extras add heavier dependencies only when needed:

```bash
pip install "mantpy[gnn]"      # graph learning and explainability
pip install "mantpy[patch]"    # learned image-patch features
pip install "mantpy[spatial]"  # SpatialData integration
pip install "mantpy[segment]"  # Cellpose segmentation
```

## System requirements

Tested on Windows 11 (Python 3.11) and Ubuntu (Python 3.11 and 3.14); no
special hardware is needed. Dependency versions are listed in
[`pyproject.toml`](https://github.com/moeghaf/Mantpy/blob/main/pyproject.toml).
Installing takes about 3 minutes and the quick start below about 20 seconds on
a desktop computer. Notebooks that run online in Google Colab are in the
[reproducibility repository][tutorials].

## Quick start

`toy_ecm_roi` synthesises a small region of interest in memory, so there is
nothing to download. The example draws two figures: the joint cell-ECM graph
and the neighbourhood clusters.

```python
import mantpy as mt

# A small synthetic ROI: image stack, channel panel, cell table.
roi = mt.datasets.toy_ecm_roi()

# Read multiplexed imaging and a cell table into AnnData.
adata = mt.io.read_imc(
    roi.image, panel=roi.panel, cells=roi.cells,
    sample_id="toy", condition="ctrl",
)

# Normalise channels and segment the ECM into patch nodes.
mt.pp.normalize(adata)
mt.pp.extract_ecm_patches(
    adata,
    roi.image,
    ecm_channel="ColIV",
    ecm_K="auto",
    features=["mean"],
)

# Build cell, ECM, and joint cell-ECM graph layers.
mt.gr.build_graph(adata, mode="cell")
mt.gr.build_graph(adata, mode="ecm")
mt.gr.build_graph(adata, mode="cell_ecm")

# Quantify spatial organisation.
mt.tl.cell_ecm_enrichment(adata, cell_type="B")
mt.tl.neighbourhood_clustering(adata, n_clusters=4)

# Visualise results.
mt.pl.cell_ecm_graph(adata)
mt.pl.neighbourhood_clusters(adata)
```

Point `mt.io.read_imc` at your own files to run the same pipeline on real data:

```python
adata = mt.io.read_imc("image.tiff", panel="panel.csv", cells="cells.csv")
```

The toy ROI is synthetic — its clusters and statistics describe the generator,
not biology. Use it to learn the API, then move to real data.

## Tutorials

Step-by-step guides, each executed when the documentation is built:

- [Loading data](https://mantpy.readthedocs.io/en/latest/tutorials/loading-data.html)
- [Building ECM graphs](https://mantpy.readthedocs.io/en/latest/tutorials/ecm-graphs.html)
- [Cell–ECM graphs](https://mantpy.readthedocs.io/en/latest/tutorials/cell-ecm-graphs.html)
- [Exporting to AnnData](https://mantpy.readthedocs.io/en/latest/tutorials/export-anndata.html)
- [Exporting to PyTorch Geometric](https://mantpy.readthedocs.io/en/latest/tutorials/export-pytorch-geometric.html)

## Paper reproducibility

The [paper reproducibility repository][tutorials] contains tutorials, full
experiment notebooks and figure plotting code.

## Public datasets

```python
intestine = mt.datasets.coliv_intestine()   #  93 MB
lung = mt.datasets.balbc_pbs_lung()         #  71 MB
liver = mt.datasets.schistosoma_ecm()       #  38 MB
```

## Documentation

[Documentation][] · [API reference][api documentation] · [Changelog][changelog]

## Citation

If you use Mantpy, please cite the preprint:

> Ghafoor M, Parkinson JE, Pham T, Georgaka S, Haley MJ, Jokl E, Piper Hanley K,
> Allen JE, Sutherland TE, Rattray M. **Mantpy: a framework for extracellular
> matrix analysis in spatial proteomics.** *bioRxiv* (2026).
> doi: [10.1101/2025.06.04.657781](https://doi.org/10.1101/2025.06.04.657781)

## Contact

For questions, contact [moeghaf@gmail.com](mailto:moeghaf@gmail.com) or
[mohamed.ghafoor@postgrad.manchester.ac.uk](mailto:mohamed.ghafoor@postgrad.manchester.ac.uk).
To report a bug, use the [issue tracker][].

[preprint]: https://doi.org/10.1101/2025.06.04.657781
[tutorials]: https://github.com/moeghaf/mantpy_reproducibility
[issue tracker]: https://github.com/moeghaf/Mantpy/issues
[tests]: https://github.com/moeghaf/Mantpy/actions/workflows/test.yaml
[pypi]: https://pypi.org/project/mantpy/
[release]: https://github.com/moeghaf/Mantpy/releases/tag/v1.2.0
[documentation]: https://mantpy.readthedocs.io
[changelog]: https://mantpy.readthedocs.io/en/latest/changelog.html
[api documentation]: https://mantpy.readthedocs.io/en/latest/api.html
