# Ion Mobility Heatmap Visualization

> Use when you have raw LC-IMS-MS data (Agilent, Thermo, Bruker, or mzML format) and need to visualize and export the spatial distribution of a specific ion species (or ion family) across both ion mobility and retention time dimensions.

- Skill: `holobiomicslab/ion-mobility-heatmap-visualization` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/ion-mobility-heatmap-visualization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/ion-mobility-heatmap-visualization/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/ion-mobility-heatmap-visualization

---


# ion-mobility-heatmap-visualization

## Summary

Generate extracted ion mobility (XIM) heatmaps from raw LC-IMS-MS data by specifying m/z and arrival-time ranges, enabling visualization of ion intensity distributions across mobility and retention time dimensions. This skill is essential for interpreting ion separation and structural dynamics in multidimensional mass spectrometry.

## When to use

You have raw LC-IMS-MS data (Agilent, Thermo, Bruker, or mzML format) and need to visualize and export the spatial distribution of a specific ion species (or ion family) across both ion mobility and retention time dimensions. Apply this skill when you want to extract a subset of ions by m/z and arrival-time range, generate a 2D heatmap representation, and export the visualization as PDF or tabular data (CSV) for publication or further analysis.

## When NOT to use

- Input data is from a traditional LC-MS (without ion mobility dimension) — use extracted ion chromatogram (XIC) instead.
- You require MS/MS fragmentation spectra or spectral library matching — use TandemMatch or Mirador's MS/MS mirror plot feature instead.
- You need to compare heatmaps across multiple acquisition methods or cohorts — use Comparador for harmonized feature comparison.

## Inputs

- Raw mass spectrometry data file (Agilent .d directory, Thermo .raw, Bruker .d, or mzML format)
- m/z range and tolerance (e.g., 500–510 m/z, ±5 ppm)
- Retention time (RT) range in seconds or minutes
- Arrival time (ion mobility) range in milliseconds or inverse reduced mobility units

## Outputs

- Extracted ion mobility (XIM) heatmap in PDF format
- Tabular XIM data in CSV format (retention time, arrival time, intensity matrix)
- Optional: customized visualization parameters logged for reproducibility

## How to apply

Load raw MS data in a supported instrument format (Agilent .d, Thermo .raw, Bruker .d, or mzML) into Mirador. Specify the target m/z range (with user-defined tolerance, typically ppm-based), the retention time window, and the arrival-time (mobility) range boundaries. Mirador extracts all ion intensity signals matching these three-dimensional constraints, bins them into a 2D grid indexed by (retention time, arrival time), and generates a heatmap where intensity is represented as color or gradient. Export the result as both a high-resolution PDF visualization (suitable for figures) and a CSV table containing the binned intensity matrix. Verify output by confirming that the m/z, RT, and arrival-time ranges match your input parameters and that intensity maxima align with expected ion separation patterns for your compounds.

## Related tools

- **Mirador** (Primary tool for raw MS data visualization and XIM heatmap generation, supporting customizable m/z, RT, and arrival-time range extraction and PDF/CSV export.) — https://github.com/pnnl/IonToolPack
- **IonToolPack** (Container suite providing unified GUI access to Mirador and companion tools; handles multi-format data loading and no-installation deployment.) — https://github.com/pnnl/IonToolPack
- **PeakQC** (Optional companion tool for quality assessment of ion signals used to generate heatmaps; applies PCA-based QC and outlier detection on MS1 data.) — https://github.com/pnnl/IonToolPack

## Evaluation signals

- Verify that the exported heatmap intensity range corresponds to the ion count or signal intensity in the input raw file; compare min/max values to raw data statistics.
- Confirm that the CSV matrix dimensions match the binned retention time and arrival-time grid; check for missing or zero-padded cells at grid edges.
- Visual inspection: heatmap should show clustered intensity in expected mobility and RT regions; absence of signal outside specified m/z tolerance indicates correct extraction.
- Reproducibility check: regenerate the heatmap with identical parameters and verify pixel-for-pixel match with previous output.
- Cross-validation: overlay exported CSV data on the PDF heatmap to ensure color/intensity mapping is consistent and colorbar labels are accurate.

## Limitations

- XIM heatmaps require ion mobility (IMS) dimension in the input data; conventional LC-MS data will not produce meaningful 2D mobility separations.
- Arrival-time range and tolerance parameters are instrument-specific and user-defined; incorrect settings may exclude target ions or include chemical noise.
- Export formats (PDF, CSV) are suitable for static visualization and tabular export but do not preserve raw centroid or profile peak shapes; users working with high-resolution isotope patterns may need to inspect raw data directly.
- No changelog provided in repository; version-to-version changes in Mirador heatmap binning or export precision are not formally documented.

## Evidence

- [readme] Mirador: Raw MS data visualization and export (PDF, CSV) including extracted ion chromatograms (XIC), extracted ion mobility (XIM) heatmaps, and MS/MS mirror plots: "**Mirador**: Raw MS data visualization and export (PDF, CSV) including extracted ion chromatograms (XIC), extracted ion mobility (XIM) heatmaps, and MS/MS mirror plots with customizable m/z, RT, and"
- [other] Generate extracted ion mobility (XIM) heatmaps for the specified m/z and arrival-time ranges: "Generate extracted ion mobility (XIM) heatmaps for the specified m/z and arrival-time ranges."
- [readme] Supported formats include Agilent 'd', Thermo '.raw', Bruker 'd', and mzML, and for different types of MS acquisition methods: LC-MS, LC-IMS-MS: "Supported formats include Agilent 'd', Thermo '.raw', Bruker 'd', and mzML, and for different types of MS acquisition methods: * LC-MS * LC-IMS-MS"
- [other] Parse user-specified m/z, retention time (RT), and arrival-time (mobility) range parameters: "Parse user-specified m/z, retention time (RT), and arrival-time (mobility) range parameters."
- [other] Export all visualizations and tabular data as PDF and CSV files: "Export all visualizations and tabular data as PDF and CSV files."