# Metabolite Feature Organization

> Use when you have raw imzML and ibd (ion binary data) files from spatial mass spectrometry imaging and need to convert them into a standardized AnnData representation where m/z values are features (columns), spatial spots are observations (rows), and intensities form the feature matrix.

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

---


# metabolite-feature-organization

## Summary

Organize spatial metabolomics mass spectrometry data into a structured AnnData object by parsing binary imzML files, extracting m/z values and intensity matrices, and mapping them to spatial coordinates. This skill is essential for downstream cross-modal spatial analysis in multi-omics workflows.

## When to use

You have raw imzML and ibd (ion binary data) files from spatial mass spectrometry imaging and need to convert them into a standardized AnnData representation where m/z values are features (columns), spatial spots are observations (rows), and intensities form the feature matrix. Use this skill before alignment, normalization, or cross-modal integration with spatial transcriptomics data.

## When NOT to use

- Input data is already in CSV or tabular format (use read_sm_csv_as_anndata instead)
- Mass spectrometry data is from a non-spatial experiment (imzML is specific to spatial imaging)
- AnnData object has already been constructed and validated

## Inputs

- imzML file (text metadata file describing mass spectrometry imaging experiment)
- ibd file (ion binary data file containing mass spectrometry intensities)

## Outputs

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

## How to apply

Load the imzML file and its accompanying ibd file using the spatialmeta.pp.read_sm_imzml_as_anndata function from the spatialMETA preprocessing module. This function parses 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). Construct an AnnData object with the intensity matrix stored in the .X slot, m/z values in .var, spatial coordinates and spot identifiers in .obs, and return the formatted object for downstream metabolomic analysis. Verify that all spatial spots are represented, m/z values are numeric and monotonically ordered, and intensity values are non-negative.

## Related tools

- **spatialMETA** (Provides the read_sm_imzml_as_anndata preprocessing function that parses imzML/ibd files and constructs AnnData objects) — https://github.com/WanluLiuLab/SpatialMETA

## Examples

```
from spatialmeta.pp import read_sm_imzml_as_anndata; adata = read_sm_imzml_as_anndata(imzml_file='sample.imzML', ibd_file='sample.ibd')
```

## Evaluation signals

- AnnData object .X contains non-negative intensity values with shape matching (n_spots, n_mz_features)
- m/z values in .var are numeric, unique, and properly ordered
- Spatial coordinates in .obs correspond exactly to imzML coordinate system (x, y pixel positions)
- No missing values (NaN) in intensity matrix or coordinate data
- Total m/z feature count matches the number of parsed ions in the ibd binary data

## Limitations

- Requires both imzML and ibd files to be present and co-located; missing ibd file will cause read failure
- Binary format compatibility depends on imzML specification version and vendor implementation
- Large imzML files with very high mass resolution or large spatial imaging areas may require substantial memory

## 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"