Imzml file format parsing

imzml-file-format-parsing

Summary

Parse imzML files (imaging mass spectrometry data) and their accompanying ibd binary files into a structured AnnData object for spatial metabolomics analysis. This skill converts raw mass spectrometry intensities and m/z values from binary format into a feature matrix organized by spatial coordinates.

When to use

You have acquired imaging mass spectrometry (IMS) data stored in imzML format (accompanied by an .ibd ion binary data file) and need to load it into a Python-based spatial metabolomics workflow. Use this skill when you are beginning preprocessing of spatial metabolomics data and require a unified AnnData representation compatible with downstream SpatialMETA tools like alignment, filtering, and multi-omics integration.

When NOT to use

• Input data is already in AnnData format or another preprocessed matrix format (e.g., CSV, TSV feature table) — use direct import instead.
• You are working with non-imaging mass spectrometry data (e.g., bulk metabolomics, untargeted LC-MS without spatial information) — spatial coordinate parsing will fail or be unnecessary.
• The imzML file lacks a corresponding .ibd binary file or the file pair is corrupted — the parser will fail to load intensities.

Inputs

• imzML file (imaging mass spectrometry data format)
• .ibd file (ion binary data companion file)
• file path(s) pointing to imzML and ibd pair

Outputs

• AnnData object with intensity matrix in .X slot
• m/z values stored in .var metadata
• spatial coordinates and spot identifiers in .obs metadata

How to apply

Invoke the read_sm_imzml_as_anndata function from the spatialMETA preprocessing module, passing the imzML file path and its corresponding .ibd file. The function parses mass spectrometry intensities and m/z values from the binary format, constructing a feature matrix where m/z values become columns (variables) and spatial coordinates become rows (observations). Store the intensity matrix in the AnnData .X slot, m/z metadata in .var, spatial coordinates and spot identifiers in .obs, and return the formatted AnnData object for downstream metabolomic analysis steps such as QC filtering, normalization, and spatial alignment.

Related tools

• spatialMETA (Provides the read_sm_imzml_as_anndata preprocessing function for parsing imzML files into AnnData objects; part of the broader spatial multi-omics integration workflow) — https://github.com/WanluLiuLab/SpatialMETA

Examples

from spatialmeta.pp import read_sm_imzml_as_anndata; adata = read_sm_imzml_as_anndata('sample.imzML')

Evaluation signals

• AnnData object is returned without parsing errors and validates against the AnnData schema (n_obs > 0, n_vars > 0, .X is a matrix)
• m/z values in .var are numeric, monotonically increasing or sensible range (e.g., 50–2000 m/z), and match the number of columns in .X
• Spatial coordinates in .obs match the number of rows in .X; spot identifiers are unique and traceable to original imzML pixel/scan metadata
• Intensity matrix .X contains non-negative numeric values consistent with mass spectrometry detector output (counts or normalized intensities)
• Downstream SpatialMETA functions (e.g., calculate_qc_metrics_sm, filter_cells_sm) execute without schema or shape mismatches on the returned AnnData object

Limitations

• Requires both imzML and .ibd files to be present and co-located or explicitly linked; parsing fails silently or with unclear error if either is missing or corrupted.
• No built-in validation of m/z calibration or mass accuracy; assumes the imzML file contains valid, calibrated m/z values from the instrument.
• Memory usage scales with the number of spatial coordinates (pixels/spots) and the number of m/z features; very large imaging datasets may require downsampling or tiling.
• The function does not automatically merge positive and negative ion mode data; use merge_sm_pos_neg separately if both polarities were acquired.

Evidence

• [other] Load imzML and ibd files using read_sm_imzml_as_anndata: "Load the imzML file and its accompanying ibd (ion binary data) file using the read_sm_imzml_as_anndata function from spatialMETA preprocessing module."
• [other] Parse MS intensities and m/z from binary into feature matrix: "Parse mass spectrometry intensities and m/z values from the binary format, organizing them into a feature matrix with m/z as columns (variables) and spatial coordinates as rows (observations)."
• [other] Construct AnnData with intensity in .X, m/z in .var, coordinates in .obs: "Construct an AnnData object with the intensity matrix in the .X slot, m/z values stored in .var, spatial coordinates and spot identifiers in .obs, and return the formatted object for downstream"
• [other] SpatialMETA provides preprocessing functions for spatial metabolomics: "spatialmeta.pp.read_sm_imzml_as_anndata"