MSIverse 0.1.0

MSIverse is a pure-Python port of the user-facing analysis, plotting, and interactive functions in SpaMTP 1.1.0.9000. Single-modality data use AnnData; aligned spatial metabolomics/transcriptomics use MuData.

The imzML reader and public-axis matrix construction are pure-Python ports of Cardinal 3.14.0, CardinalIO 1.10.0, and matter 2.14.0. There is no R/rpy2 runtime dependency.

Install

Run these commands from the project directory containing pyproject.toml.

python -m pip install -e .
python -m pip install -e '.[all]'
python -m pip install -e '.[ms1-id]'

Python 3.10–3.12 is supported. pyimzML is installed for imzML writing; Plotting/Notebook controls, METASPACE, Pillow, and pygoslin remain optional extras so importing the core analysis package stays lightweight.

Data conventions

• adata.X: current analysis matrix.
• adata.layers["counts"]: unnormalised intensity loaded from the source.
• adata.var["mz"]: common m/z feature axis.
• adata.obsm["spatial"]: x/y coordinates.
• adata.obsm, adata.varm, and adata.obsp: reductions, loadings, and graphs.
• adata.uns["msi"]: schema and input/spectrum modes.
• adata.uns["read_imzml"], ["peak_align"], ["bin_spectra"]: input and common-axis records.
• adata.uns["normalize"], ["pca"], ["spatial_pca"], etc.: functional records with params, provenance, outputs, optional resolved, and function-specific results.
• adata.uns["mz_annotation"]: base candidates; ["annotation_evidence"]: candidates augmented with MS1-ID support. Evidence integration preserves the ["ms1_id"] run record.
• mdata.mod["spm"] / mdata.mod["spt"]: metabolomic/transcriptomic modalities.

Object-transforming functions modify in place by default and accept copy=True when a separate object is required.

Named runs use key_added; readers select inputs explicitly (for example annotation_key="anno_hmdb"). Normalization stores a custom run in both uns[key_added] and layers[key_added]; PCA retains X_<key_added> and <key_added>_loadings. Existing defaults and explicit matrix/column arguments remain supported. Reusing a key replaces that run; unrelated operation keys are rejected. These records are named results, not an automatic history log.

Old objects remain readable through package adapters. To convert their metadata explicitly, use io.migrate_uns(adata, copy=True, drop_legacy=False). Add return_report=True to return (converted, report). Migration is atomic on conflicts and preserves unknown fields; it does not rewrite saved files. Direct notebook access to old paths must be updated to the new layout.

Modules

from msiverse import annotate, io, preprocess, analysis

adata = io.read_imzml("sample.imzML", as_="annData")
preprocess.normalize(adata, method="tic")
analysis.run_pca(adata, n_components=20)
result = annotate.annotate(adata, polarity="negative", ppm=5, maldi_matrix="9-AA")

from msiverse import plotting
figure = plotting.image_mz_plot(adata, mzs=[400.2], pixel=True)
interactive = plotting.density_map(adata, output_html="density.html")

To specify the spectrum representation explicitly, use spectrum_mode:

adata = io.read_imzml("sample.imzML", as_="annData", spectrum_mode="centroid")
# For profile spectra, use spectrum_mode="profile".

The default spectrum_mode="auto" uses file-level or spectrum-level declarations. For non-continuous data, only a detected centroid declaration selects peak alignment; profile or undeclared spectra use a regular axis with linear resampling. Explicit "centroid"/"profile" overrides the declaration for either output type. Continuous data still uses its existing shared m/z axis. parse_only=True returns the original declarations, even when an explicit mode is supplied.

For large processed imzML files, keep the binary arrays lazy and materialize only the pixels needed for an exploratory comparison. The reference m/z axis is still estimated from a uniform sample of the full acquisition.

arrays = io.read_imzml(
    "sample.imzML", memory=False, as_="arrays", spectrum_mode="centroid"
)
adata = io.convert_arrays_to_experiment(
    arrays, guess_max=1000, pixel_indices=range(min(1000, len(arrays)))
)

See MSIverse_User_Guide.md for usage and SPAMTP_PARITY.md for the complete SpaMTP API map.

Bundled data and licensing

The Python-native Parquet snapshots were converted from SpaMTP's bundled reference resources. They retain their upstream restrictions, including non-commercial/academic conditions for HMDB and KEGG-derived content. Review THIRD_PARTY_NOTICES.md before redistribution.