Metadata-Version: 2.5
Name: mantpy
Version: 1.0.1
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.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

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

[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.

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

## Installation

Mantpy requires Python 3.11 or newer.

```bash
pip install mantpy
```

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
```

## Quick start

This runs as written — `toy_ecm_roi` synthesises a small region of interest in
memory, so there is nothing to download:

```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)

The full analyses behind the [preprint][] run on real cohorts in the
[reproducibility repository][tutorials]; the intestine and lung workflows
open directly in Colab.

## Public datasets

One-line, checksummed loaders for every tutorial dataset, cached outside the
package and reused offline:

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

Every loader returns the same `Bunch` shape as `toy_ecm_roi`, so moving an
example from synthetic to real data is a one-line change. The bundles are frozen
under CC BY 4.0 in an immutable
[Zenodo record](https://doi.org/10.5281/zenodo.21538382).

## 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)

Machine-readable citation metadata is in
[`CITATION.cff`](https://github.com/moeghaf/Mantpy/blob/main/CITATION.cff)
(GitHub's "Cite this repository" button). The tutorial datasets have their own
[Zenodo DOI](https://doi.org/10.5281/zenodo.21538382).

## Contact

For questions and help requests, use the [scverse discourse][]. To report a
bug, use the [issue tracker][].

[preprint]: https://doi.org/10.1101/2025.06.04.657781
[scverse discourse]: https://discourse.scverse.org/
[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
[documentation]: https://mantpy.readthedocs.io
[changelog]: https://mantpy.readthedocs.io/en/latest/changelog.html
[api documentation]: https://mantpy.readthedocs.io/en/latest/api.html
