Metadata-Version: 2.4
Name: msiverse
Version: 0.0.1
Summary: Python-first, biologist-friendly toolkit for MALDI-MSI analysis
Author: msiverse contributors
License: BSD-3-Clause
Project-URL: Repository, https://github.com/aqgy2749/msiverse
Project-URL: Documentation, https://msiverse.readthedocs.io
Keywords: mass-spectrometry-imaging,MALDI,MSI,spatial-metabolomics,bioinformatics,scverse
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.9
Requires-Dist: pandas>=1.5
Requires-Dist: scikit-learn>=1.1
Requires-Dist: matplotlib>=3.5
Provides-Extra: imzml
Requires-Dist: pyimzML>=1.5; extra == "imzml"
Provides-Extra: scverse
Requires-Dist: anndata>=0.9; extra == "scverse"
Requires-Dist: scanpy>=1.9; extra == "scverse"
Provides-Extra: deep
Requires-Dist: torch>=2.0; extra == "deep"
Provides-Extra: gui
Requires-Dist: napari[all]>=0.4.18; extra == "gui"
Requires-Dist: magicgui>=0.7; extra == "gui"
Provides-Extra: metaspace
Requires-Dist: metaspace2020>=2.0; extra == "metaspace"
Provides-Extra: workflow
Requires-Dist: pyyaml>=6.0; extra == "workflow"
Provides-Extra: all
Requires-Dist: pyimzML>=1.5; extra == "all"
Requires-Dist: anndata>=0.9; extra == "all"
Requires-Dist: scanpy>=1.9; extra == "all"
Requires-Dist: torch>=2.0; extra == "all"
Requires-Dist: napari[all]>=0.4.18; extra == "all"
Requires-Dist: magicgui>=0.7; extra == "all"
Requires-Dist: metaspace2020>=2.0; extra == "all"
Requires-Dist: pyyaml>=6.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"

# msiverse

> A Python-first, biologist-friendly toolkit for MALDI-MSI analysis.

> [!WARNING]
> **Early development release (`0.0.1`).** `msiverse` is under active
> development. APIs, outputs, and behavior may change without notice, and this
> release is not recommended for production use.

`msiverse` is a reference implementation of the architecture recommended in the
*2026 MALDI-MSI Software Landscape* report. It addresses the seven critical
gaps identified in the open-source ecosystem and demonstrates a viable path to
a "Scanpy moment" for mass spectrometry imaging.

---

## What it does

| Module | Purpose | Report recommendation |
|---|---|---|
| `msiverse.core` | `MSIData` container with AnnData/SpatialData interop | Rec 1 |
| `msiverse.io` | imzML reader + synthetic data generator | Rec 3 |
| `msiverse.preprocess` | TIC / RMS norm, TopHat baseline, hotspot clip, log1p | parity w/ MALDIquant/rMSIproc |
| `msiverse.segment` | k-means, spatial k-means, **Spatial Shrunken Centroids** (Cardinal port) | Rec 1 |
| `msiverse.annotate` | local DB matcher + METASPACE adapter stub | Rec 4 |
| `msiverse.register` | landmark affine + thin-plate-spline; image warping | Rec 5 |
| `msiverse.multimodal` | MSI ↔ Visium/Xenium spot aggregation, MSI ↔ IF/IHC fusion | Rec 5 + scientific frontier |
| `msiverse.visualize` | ion images, segmentation maps, overview panels | core UX |
| `msiverse.deep` | PyTorch `Dataset` + `VAEEmbedding` (pyM²aia / msiPL style) | Rec 6 |
| `msiverse.workflow` | hashed, reproducible `Pipeline` + Snakemake config export | Rec 7 |
| `msiverse.gui` | napari plugin with ion-image browser widget | Rec 2 |

## Installation

```bash
# Minimal install
pip install -e .

# With scverse / DL / GUI extras
pip install -e ".[scverse,deep,gui,imzml,workflow]"

# Everything
pip install -e ".[all]"
```

## Quick start

```python
from msiverse import io, preprocess, segment, annotate, visualize

# Synthetic MSI for tutorials/tests — no data download required
data = io.simulate_msi(height=80, width=80, n_features=200, n_regions=4)

# One-line preprocessing (baseline → TIC norm → hotspot → log1p)
data = preprocess.standard_pipeline(data)

# Cardinal-style Spatial Shrunken Centroids — first Python port
segment.spatial_shrunken_centroids(data, n_clusters=4, shrinkage=1.5)

# Local annotation against built-in lipid/metabolite DB
hits = annotate.annotate_local(data, polarity="positive", tol_ppm=5)

# Overview panel (TIC, mean spectrum, top features, segmentation, ...)
fig = visualize.overview(data, label_key="ssc")
fig.savefig("overview.png")
```

## Reproducible pipelines

```python
from msiverse.workflow import Pipeline

p = (Pipeline("my_run")
     .add("baseline",  preprocess.baseline_correct, window=51)
     .add("normalize", preprocess.normalize, method="tic")
     .add("ssc",       segment.spatial_shrunken_centroids, n_clusters=5))

result = p.run(data)
p.save_provenance("run.json")               # JSON record with input/output hashes
p.to_snakemake_config("Snakefile.yaml")     # HPC handoff
```

## scverse interop

```python
adata = data.to_anndata()    # → Scanpy / Squidpy / SpatialData
data2 = MSIData.from_anndata(adata)
```

## Same-section MSI + spatial transcriptomics

The scientific frontier identified in the report:

```python
from msiverse.multimodal import integrate_with_visium

# Provide fiducial landmarks from both modalities
joint = integrate_with_visium(
    msi=msi_data,
    visium_adata=visium_adata,
    msi_landmarks=msi_pts,
    visium_landmarks=visium_pts,
    aggregation="mean",
)
# joint.obsm['msi'] now contains MSI intensities per Visium spot
```

## GUI (napari)

```python
import napari
from msiverse.gui import view_msi

viewer = view_msi(data, label_key="ssc")
napari.run()
```

## Tests

```bash
pytest tests/ -v
```

## License

BSD-3-Clause.

## Citation

If you use `msiverse` in your work, please cite the underlying methods:

- Cardinal v3: Bemis et al., *Nat. Methods* 20:1883 (2023)
- METASPACE-ML: Wadie et al., *Nat. Commun.* 15:9110 (2024)
- pyM²aia: Cordes et al., *Bioinformatics* 40:btae133 (2024)
- SMA: Vicari et al., *Nat. Biotechnol.* 42:1046 (2024)
