# Mass Spectrometry Data Matrix Construction

> Use when you have raw spatial metabolomics imzML files (paired with .ibd binary data files) that need to be loaded into a unified AnnData format for integration with spatial transcriptomics data or for cross-modal spatial pattern identification in single or multiple sample datasets.

- Skill: `holobiomicslab/mass-spectrometry-data-matrix-construction` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/mass-spectrometry-data-matrix-construction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/mass-spectrometry-data-matrix-construction/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/mass-spectrometry-data-matrix-construction

---


# mass-spectrometry-data-matrix-construction

## Summary

Parse mass spectrometry intensities and m/z values from binary imzML files and organize them into a feature matrix where m/z values form columns (variables) and spatial coordinates form rows (observations), then encapsulate into an AnnData object for downstream metabolomic analysis.

## When to use

You have raw spatial metabolomics imzML files (paired with .ibd binary data files) that need to be loaded into a unified AnnData format for integration with spatial transcriptomics data or for cross-modal spatial pattern identification in single or multiple sample datasets.

## When NOT to use

- Input is already in CSV or tabular format (use read_sm_csv_as_anndata instead)
- Data lacks spatial coordinates or spot identifiers
- Binary data file (.ibd) is missing or corrupted

## Inputs

- imzML file (spatial metabolomics metadata file)
- ibd file (ion binary data file, paired with imzML)

## Outputs

- AnnData object with intensity matrix in .X, m/z values in .var, spatial coordinates in .obs

## How to apply

Use spatialmeta.pp.read_sm_imzml_as_anndata to simultaneously parse the imzML XML metadata and accompanying .ibd (ion binary data) file. Extract mass spectrometry intensities and their corresponding m/z values from the binary format, organizing intensities into a feature matrix with observations indexed by spatial coordinates (x, y positions) and variables indexed by m/z ratios. Construct an AnnData object with the intensity matrix in the .X slot, m/z values stored in .var (variable metadata), spatial coordinates and spot identifiers in .obs (observation metadata), ensuring consistent indexing and data types. This structured format enables subsequent alignment to a unified resolution with spatial transcriptomics data and cross-modal pattern discovery.

## Related tools

- **spatialMETA** (Provides read_sm_imzml_as_anndata preprocessing function for loading and parsing imzML files into AnnData objects) — https://github.com/WanluLiuLab/SpatialMETA

## Examples

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

## Evaluation signals

- AnnData .X matrix has shape (n_spots, n_mz_features) with non-negative intensity values
- .var index contains unique m/z values sorted in ascending order
- .obs index contains spatial coordinates (x, y) and spot identifiers with no missing values
- Data types are consistent: intensities as float/int, m/z as float, coordinates as numeric
- No NaN or infinite values in intensity matrix; m/z values fall within expected mass range (e.g., 50–2000 m/z for typical spatial metabolomics)

## Limitations

- Requires both imzML and .ibd files to be present and correctly paired; missing or corrupted binary data will cause parsing failure
- Performance depends on file size; very large imzML datasets may require substantial memory for full matrix construction
- m/z alignment across samples requires subsequent use of get_mz_reference or manual harmonization to handle mass shift or calibration drift

## Evidence

- [other] Load the imzML file and its accompanying ibd (ion binary data) file using the read_sm_imzml_as_anndata function from spatialMETA preprocessing module.: "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 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).: "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 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 metabolomic analysis.: "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"
- [readme] spatialMETA is a method for integrating spatial multi-omics data. SMOI aligns ST and SM to a unified resolution: "spatialMETA is a method for integrating spatial multi-omics data. SMOI aligns ST and SM to a unified resolution"
- [other] spatialmeta.pp.read_sm_imzml_as_anndata: "spatialmeta.pp.read_sm_imzml_as_anndata"