msiverse 0.0.1

Python-first, biologist-friendly toolkit for MALDI-MSI analysis

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

# 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

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

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

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

Same-section MSI + spatial transcriptomics

The scientific frontier identified in the report:

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)

import napari
from msiverse.gui import view_msi

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

Tests

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)