Features

Data Input

• Support for centroid and profile data stored in imzML format:
  • Range-based ion images
  • Individual spectra
  • imzML metadata
• Gray-scale images (ie. ion images, mask images, normalization images) are accessible as SimpleITK's Image objects.
  • ImzML images and images exported using SimpleITK (e.g. in NRRD format) can be explored interactively in M²aia desktop application.

Data Structures & Functions:

• Signal Processing for profile imzML files:
  • Baseline correction
  • Normalization
  • Smoothing
• Batch generators (TensorFlow/PyTorch):
  • Spectral, spatial, and spatio-spectral access
  • Optional in-memory or on-disk batch/data buffering

Data Output

• Write Continuous Centroid imzML files

Examples@ https://github.com/m2aia/pym2aia-examples.git

Installation

Requirements on Windows

Microsoft Visual C++ Redistributable latest supported downloads: https://learn.microsoft.com/de-de/cpp/windows/latest-supported-vc-redist?view=msvc-170

Requirements on Ubuntu/Linux

apt-get install -q -y --no-install-recommends \
    libglu1-mesa-dev \
    libgomp1 \
    libopenslide-dev \
    python3 \
    python3-pip \
    python3-venv

Package installation

Consider to install pyM²aia in an virtual environment.

Install pyM²aia on windows or linux using pip.

# cd projectDir/
python3 -m venv .venv

source .venv/bin/activate
pip3 install --upgrade pip

pip install m2aia

Note: Different versions of the pypi package exists for windows and linux based systems:

• Linux: m2aia-x.x.x-py3-none-manylinux_2_31_x86_64.whl
• Windows: m2aia-x.x.x-py3-none-win-amd64.whl
• Source: m2aia-x.x.x.tar.gz

Getting started

pyM2aia offers a interface to M2aia’s imzML reader and signal processing utilities. Complete processing examples can be found on pym2aia-examples

Example create ion images:

import m2aia as m2

I = m2.ImzMLReader("path/to/imzMl/file.imzML")
I.SetNormalization(m2.m2NormalizationTIC)
I.SetIntensityTransformation(m2.m2IntensityTransformationSquareRoot)
ys_2 = I.GetMeanSpectrum()
# get the ion image as array
center_mz = 1123.43
i_2 = I.GetArray(center_mz, 75)

Example write continuous centroid imzML:

import m2aia as m2
import numpy as np

# load a coninuous profile imzML
I = m2.ImzMLReader("path/to/imzMl/file.imzML")

# Find/load centroids ...
# centroids = [x for x in range(2000,3000,20)]

# csv with i.e. 3 columns with header line ('mz','min','max')
centroids = np.genfromtxt("path/to/csv/centroids.csv", delimiter=',', skip_header=1)[:,0]

I.SetTolerance(50)
I.WriteContinuousCentroidImzML("/tmp/continuous_centroid.imzML", centroids)

Developer Documentation

Known issues

The following Warnings can be ignored:

• "WARNING: In AutoLoadModulesFromPath at /opt/mitk/Modules/CppMicroServices/core/src/util/usUtils.cpp:176 : Auto-loading of module /usr/local/lib/python3.10/dist-packages/m2aia/binaries/bin/MitkCore/libMitk<XY>IO.so failed."

• "WARNING: In load_impl at /opt/mitk/Modules/CppMicroServices/core/src/util/usUtils.cpp:76 : libMitk<XY>.so: cannot open shared object file: No such file or directory"

Development

New python features for MSI processing

Python side processing utilities are currently limited. To change this, you can add new Python based features by adding new utilities. New tools should focus on the utilization of pyM²aia's data access and structures.

./utils/<toolName>.py

To promote your work you can just create a pull request or contact me personally.

Improve the C++-Python interface

To Further enhance the C++-Python interface it is required to make changes in m2PythonWrapper.cpp. By using MITK's super build approach, a development environment can be setup following these instructions. It is required to change the library search path for pyM2aia to the modified libraries. This can be realized by setting a system environment variable. Following the example shown in the above mentioned instructions, ie. it is required to set it in windows to

M2AIA_PATH=C:/M2aiaWorkDir/build/MITK-build/lib

For linux you can add the following lines to the end of your ~/.profile file:

M2AIA_PATH=/home/username/M2aiaWorkDir/build/MITK-build/lib

All pyM2aia libraries on the system will now use this custom library search path.

To promote your work you can just create a pull requests in both repositories or contact me personally.

Manual package installation using the source distribution from pypi

The pypi Source distribution contains *.so and *.dll library files for both, windows and linux. You can try to install pyM²aia by extracting the archive and using the following command within the project folder:

python setup.py install

Cite M²aia

M²aia is an interactive desktop application for visualization and processing of mass spectrometry (MS) imaging data. Please visit https://m2aia.github.io/m2aia for further information.

Cordes J; Enzlein T; Marsching C; Hinze M; Engelhardt S; Hopf C; Wolf I (July, 2021): M²aia - Interactive, fast and memory efficient analysis of 2D and 3D multi-modal mass spectrometry imaging data https://doi.org/10.1093/gigascience/giab049