msiverse 0.0.1__tar.gz

msiverse-0.0.1/PKG-INFO

@@ -0,0 +1,188 @@
+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)

msiverse-0.0.1/README.md

@@ -0,0 +1,135 @@
+# 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)

msiverse-0.0.1/msiverse/__init__.py

@@ -0,0 +1,66 @@
+"""
+msiverse: a Python-first, biologist-friendly toolkit for MALDI-MSI.
+
+Designed to address the seven critical gaps in the MALDI-MSI software
+ecosystem identified in our 2026 landscape review:
+
+  1. End-to-end open-source Python platform
+  2. (lobby) imzML 1.2 standardization — interim native handling here
+  3. Vendor I/O coverage (via imzy/MSIGen adapters)
+  4. Accessible deep learning (msiverse.deep)
+  5. Better protein annotation (HIT-MAP-style; planned)
+  6. FAIR / reproducibility (msiverse.workflow)
+  7. Same-section ST + MSI integration (msiverse.multimodal)
+
+Quick start
+-----------
+>>> from msiverse import io, preprocess, segment, annotate, visualize
+>>> data = io.simulate_msi()                          # synthetic demo data
+>>> data = preprocess.standard_pipeline(data)         # baseline → norm → log
+>>> segment.spatial_shrunken_centroids(data, n_clusters=5)
+>>> annotate.annotate_local(data, tol_ppm=5)
+>>> visualize.overview(data, label_key="ssc")
+
+End-to-end (one-call)
+---------------------
+>>> from msiverse.workflow import run_standard_workflow
+>>> data, pipeline = run_standard_workflow(
+...     data, n_clusters=5, output_dir="./results"
+... )
+
+scverse interop
+---------------
+>>> adata = data.to_anndata()        # → Scanpy / Squidpy / SpatialData
+>>> data2 = MSIData.from_anndata(adata)
+"""
+
+__version__ = "0.0.1"
+
+from .core import MSIData
+
+# Submodule aliases for the canonical workflow
+from . import (
+    io,
+    preprocess,
+    segment,
+    annotate,
+    register,
+    multimodal,
+    visualize,
+    workflow,
+    diagnostics,
+)
+
+__all__ = [
+    "MSIData",
+    "io",
+    "preprocess",
+    "segment",
+    "annotate",
+    "register",
+    "multimodal",
+    "visualize",
+    "workflow",
+    "diagnostics",
+    "__version__",
+]

msiverse-0.0.1/msiverse/annotate/__init__.py

@@ -0,0 +1,255 @@
+"""
+msiverse.annotate
+=================
+
+Metabolite annotation for MSI data.
+
+Strategy: provide a *thin local matcher* for offline workflows + an
+optional adapter to METASPACE / METASPACE-ML for FDR-controlled cloud
+annotation. Lipid in-source fragmentation (rMSIfragment-style) and
+spatial coherence scoring (METASPACE's MSM) are stubbed for future work.
+
+What works today:
+- Local mass-only matching against a small built-in lipid/metabolite
+  reference list with common adducts.
+- Adduct enumeration ([M+H]+, [M+Na]+, [M-H]-, [M+K]+, ...).
+- Returns per-feature ranked candidates with mass error in ppm.
+
+What's pluggable:
+- The METASPACEClient stub mirrors the metaspace2020/python-client
+  API so it can be swapped in once a network is available.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from ..core import MSIData
+
+
+# Proton mass / common adduct deltas
+PROTON = 1.00728
+ADDUCTS = {
+    "[M+H]+": (+PROTON, +1),
+    "[M+Na]+": (+22.98922, +1),
+    "[M+K]+": (+38.96316, +1),
+    "[M+NH4]+": (+18.03383, +1),
+    "[M-H]-": (-PROTON, -1),
+    "[M+Cl]-": (+34.96885, -1),
+    "[M+FA-H]-": (+44.99765, -1),  # formate adduct
+}
+
+
+# =============================================================================
+# Tiny built-in database for demos / offline use
+# =============================================================================
+def builtin_db() -> pd.DataFrame:
+    """
+    A minimal panel of common biological metabolites and lipids.
+    Intended for tutorials and offline tests, not production annotation.
+    """
+    return pd.DataFrame(
+        [
+            # (name, formula, monoisotopic_mass, class)
+            ("Glucose", "C6H12O6", 180.0634, "Sugar"),
+            ("Cholesterol", "C27H46O", 386.3549, "Sterol"),
+            ("Phosphatidylcholine 34:1", "C42H82NO8P", 759.5778, "Lipid/PC"),
+            ("Phosphatidylcholine 36:2", "C44H84NO8P", 785.5935, "Lipid/PC"),
+            ("Sphingomyelin d18:1/16:0", "C39H79N2O6P", 702.5676, "Lipid/SM"),
+            ("Glutamic acid", "C5H9NO4", 147.0532, "Amino acid"),
+            ("ATP", "C10H16N5O13P3", 506.9957, "Nucleotide"),
+            ("Heme B", "C34H32FeN4O4", 616.1773, "Cofactor"),
+            ("Taurine", "C2H7NO3S", 125.0147, "Amino acid"),
+            ("Creatine", "C4H9N3O2", 131.0695, "Amino acid"),
+            ("Dopamine", "C8H11NO2", 153.0790, "Neurotransmitter"),
+            ("Acetylcholine", "C7H16NO2", 146.1181, "Neurotransmitter"),
+            ("PE 36:2", "C41H78NO8P", 743.5465, "Lipid/PE"),
+            ("LysoPC 16:0", "C24H50NO7P", 495.3325, "Lipid/LPC"),
+        ],
+        columns=["name", "formula", "neutral_mass", "class"],
+    )
+
+
+# =============================================================================
+# Local annotation
+# =============================================================================
+@dataclass
+class AnnotationHit:
+    feature_idx: int
+    observed_mz: float
+    name: str
+    formula: str
+    adduct: str
+    theoretical_mz: float
+    ppm_error: float
+    db_class: str
+
+    def to_dict(self) -> dict:
+        return {
+            "feature_idx": self.feature_idx,
+            "observed_mz": self.observed_mz,
+            "name": self.name,
+            "formula": self.formula,
+            "adduct": self.adduct,
+            "theoretical_mz": self.theoretical_mz,
+            "ppm_error": self.ppm_error,
+            "class": self.db_class,
+        }
+
+
+def annotate_local(
+    data: MSIData,
+    db: pd.DataFrame | None = None,
+    adducts: list[str] | None = None,
+    polarity: str = "positive",
+    tol_ppm: float = 5.0,
+    inplace: bool = True,
+) -> pd.DataFrame:
+    """
+    Annotate features against a local DataFrame database (mass-only).
+
+    Each feature is matched against every (compound, adduct) pair within
+    ±tol_ppm. Best hit per feature is written to var; full list returned.
+
+    Parameters
+    ----------
+    db : DataFrame, optional
+        Columns must include {name, formula, neutral_mass, class}.
+        Defaults to the built-in demo database.
+    adducts : list of str
+        Which adducts to consider. Defaults to mode-appropriate set.
+    polarity : 'positive' or 'negative'
+        Filters adducts by charge if `adducts` not provided.
+    tol_ppm : float
+        Match tolerance.
+
+    Returns
+    -------
+    DataFrame
+        All candidate hits, sorted by ppm_error.
+    """
+    if db is None:
+        db = builtin_db()
+    if adducts is None:
+        # Filter by charge from ADDUCTS table
+        sign = +1 if polarity == "positive" else -1
+        adducts = [a for a, (_, q) in ADDUCTS.items() if q == sign]
+
+    hits: list[AnnotationHit] = []
+    for j, observed_mz in enumerate(data.mz):
+        tol_da = observed_mz * tol_ppm * 1e-6
+        for _, row in db.iterrows():
+            for ad in adducts:
+                delta, _q = ADDUCTS[ad]
+                theo = row["neutral_mass"] + delta
+                if abs(theo - observed_mz) <= tol_da:
+                    ppm = (observed_mz - theo) / theo * 1e6
+                    hits.append(
+                        AnnotationHit(
+                            feature_idx=j,
+                            observed_mz=float(observed_mz),
+                            name=row["name"],
+                            formula=row["formula"],
+                            adduct=ad,
+                            theoretical_mz=theo,
+                            ppm_error=float(ppm),
+                            db_class=row["class"],
+                        )
+                    )
+
+    if not hits:
+        result = pd.DataFrame(
+            columns=[
+                "feature_idx", "observed_mz", "name", "formula", "adduct",
+                "theoretical_mz", "ppm_error", "class",
+            ]
+        )
+    else:
+        result = pd.DataFrame([h.to_dict() for h in hits]).sort_values(
+            ["feature_idx", "ppm_error"], key=lambda s: s.abs() if s.name == "ppm_error" else s
+        )
+
+    if inplace:
+        # Annotate var with best hit per feature
+        best = (
+            result.loc[result.groupby("feature_idx")["ppm_error"].apply(lambda s: s.abs().idxmin())]
+            if not result.empty
+            else pd.DataFrame()
+        )
+        data.var["annotation"] = ""
+        data.var["adduct"] = ""
+        data.var["ppm_error"] = np.nan
+        data.var["compound_class"] = ""
+        if not best.empty:
+            for _, h in best.iterrows():
+                idx = int(h["feature_idx"])
+                data.var.iloc[idx, data.var.columns.get_loc("annotation")] = h["name"]
+                data.var.iloc[idx, data.var.columns.get_loc("adduct")] = h["adduct"]
+                data.var.iloc[idx, data.var.columns.get_loc("ppm_error")] = h["ppm_error"]
+                data.var.iloc[idx, data.var.columns.get_loc("compound_class")] = h["class"]
+        data.uns["annotation_db_size"] = len(db)
+        data.uns["annotation_tol_ppm"] = tol_ppm
+
+    return result
+
+
+# =============================================================================
+# METASPACE cloud adapter (stub; real call requires network + token)
+# =============================================================================
+class METASPACEClient:
+    """
+    Thin adapter to the METASPACE platform.
+
+    On a connected machine, install `metaspace2020` and pass an API token:
+
+        >>> client = METASPACEClient(api_key="your_token")
+        >>> ds_id = client.submit(imzml_path, metadata)
+        >>> hits = client.get_annotations(ds_id, fdr=0.1)
+
+    This class deliberately wraps but does not reimplement the
+    metaspace2020 client, to stay in sync with their API.
+    """
+
+    def __init__(self, api_key: str | None = None, host: str | None = None) -> None:
+        try:
+            from metaspace import SMInstance
+        except ImportError:
+            self._sm = None
+            self._unavailable_reason = (
+                "metaspace2020 package not installed. "
+                "Run `pip install metaspace2020`."
+            )
+            return
+        kwargs = {}
+        if api_key:
+            kwargs["api_key"] = api_key
+        if host:
+            kwargs["host"] = host
+        self._sm = SMInstance(**kwargs)
+        self._unavailable_reason = None
+
+    @property
+    def available(self) -> bool:
+        return self._sm is not None
+
+    def get_annotations(
+        self,
+        dataset_id: str,
+        fdr: float = 0.1,
+        database: str = "HMDB-v4",
+    ) -> pd.DataFrame:
+        """Fetch FDR-controlled annotations for an existing dataset."""
+        if not self.available:
+            raise RuntimeError(self._unavailable_reason)
+        ds = self._sm.dataset(id=dataset_id)
+        ann = ds.annotations(fdr=fdr, database=database)
+        return pd.DataFrame(ann)
+
+    def submit(self, imzml_path: str, metadata: dict) -> str:
+        """Submit a new dataset to METASPACE for annotation."""
+        if not self.available:
+            raise RuntimeError(self._unavailable_reason)
+        return self._sm.submit_dataset(imzml_path, metadata=metadata)